Porting Extension Modules to Python 3. Descriptor Ncurses library download windows free Guide. This document describes how to use the curses extension module to control text-mode displays. The curses library supplies a terminal-independent screen-painting and keyboard-handling facility for text-based terminals; such terminals include VTs, the Linux console, and the simulated terminal provided by various programs.
Display terminals support various control codes to perform common operations such as moving the cursor, scrolling the screen, and erasing areas. Different terminals use widely differing codes, and often have their own minor quirks.
Another is tools such as OS installers and kernel configurators that may have to run before any graphical support is available. The curses library provides fairly basic functionality, providing the programmer with an abstraction of a display containing multiple non-overlapping windows of text. The contents of a window can be changed in various ways—adding text, erasing it, changing its appearance—and the curses library will figure out what control codes need to be sent to the terminal to produce the right output.
Since most current commercial Unix versions are based on System V code, all the functions described here will probably be available. The older versions of curses carried by some proprietary Unixes may not support everything, though.
A ported version called UniCurses is available. The biggest difference is that the Python interface makes things simpler by merging different C functions such as addstrmvaddstrand mvwaddstr into a single addstr method. It will, however, give you the basic ideas. Before doing anything, curses must be initialized. This is done by calling the initscr function, which will determine the terminal type, send any required setup codes to the terminal, and create various internal data structures.
If successful, initscr returns a window object representing the entire screen; this is usually called stdscr after the name of the corresponding C variable. Usually curses applications turn off automatic echoing of keys to the screen, in order to be able to read keys and only display them under certain circumstances.
This requires calling the noecho function. Applications will also commonly need to react to keys instantly, without requiring the Enter key to be pressed; this is called cbreak mode, as opposed to the usual buffered input mode. Terminals usually return special keys, such as the cursor keys or navigation keys such as Page Up and Home, as a multibyte escape sequence.
While you could write your application to expect such sequences and process them accordingly, ncurses library download windows free can do it for you, returning a special value such as curses. Then call the endwin function to restore the terminal to its original operating mode. A common problem when debugging a curses application is to get your terminal messed up when the application dies without restoring the terminal to its previous state.
In Python this commonly happens when your code is buggy and raises an uncaught exception. Keys are no longer echoed to the screen when you type them, for example, which makes using the shell difficult. In Python you can avoid these complications and make debugging much easier by importing the curses. The wrapper function takes a callable object and does the initializations described above, also initializing colors if color support is present.
Once the callable returns, wrapper will restore the original state of the terminal. The callable is called inside a try … except that catches exceptions, restores the state of the terminal, and then re-raises the exception. Windows are the basic abstraction in curses. A window object represents a rectangular area of the screen, and supports methods to display text, erase it, allow the user to input strings, and so forth. The stdscr object returned by the initscr function is a window object that covers the entire screen.
Many programs may need only this single window, but you might wish to divide the screen into smaller windows, in order to redraw or clear them separately. The newwin function creates a new window of a given size, returning the new window object. Note that the coordinate system used in curses is unusual. Coordinates are always passed ncurses library download windows free the order y,xand the top-left corner of a window is coordinate 0,0.
This breaks the normal convention for handling coordinates where the x coordinate comes first. Your application can determine the size of the screen by using the curses. LINES and curses. COLS variables to obtain the y and x sizes. Legal coordinates will then extend from 0,0 to curses. LINES - ncurses library download windows free, curses. COLS - 1.
Instead you must call the refresh method of window objects to update the screen. This is because curses was originally written with ncurses library download windows free baud terminal connections in mind; with these terminals, minimizing the time required to redraw the screen was very important. Instead curses accumulates changes to the screen and displays them in the most efficient manner when you call refresh.
Most programs go into a flurry of activity, and then pause waiting for a keypress or some other action on the part of the user. All you have to do is to be sure that the screen has been redrawn before pausing to wait for user input, by first calling stdscr. A pad is a special case of a window; it can be larger than the actual display screen, and only a portion of the pad displayed at a time. The refresh call displays a section of the pad in the rectangle extending from coordinate 5,5 to coordinate 20,75 ncurses library download windows free the screen; the upper left corner of the displayed section is coordinate 0,0 on the pad.
Beyond that difference, pads are exactly like ordinary windows and support the same methods. If you have multiple windows and pads on screen there is a more efficient way to update the screen and prevent annoying screen flicker as each part of the screen gets updated.
Calls the noutrefresh method of each window to update an underlying data structure representing the desired state of the screen.
Calls the function doupdate function to change the physical screen to match the desired state recorded in the data structure. Instead you can call noutrefresh on a number of windows to update the data structure, and then call doupdate to update the screen.
For example, addstr displays a string at the current cursor location in the stdscr window, while mvaddstr moves to a given y,x coordinate first before displaying the string. Fortunately the Python interface hides all these details. Usually there are four different forms. Display the string str or character chusing attribute attr at the current position. Move to position y,x within the window, and display str or chusing attribute attr.
Attributes allow displaying text in highlighted ncurses library download windows free such as boldface, underline, reverse code, or in color.
The addstr method takes a Python string or bytestring as the value to be displayed. The contents of bytestrings are sent to the terminal as-is.
The addch methods take a character, which can be either a string of length 1, a bytestring of length 1, or an integer. Constants are provided for extension characters; these constants are integers greater than You can also use the appropriate Unicode character.
Windows remember where the cursor was left after the last operation, so if you leave out the y,x coordinates, the string or character will be displayed wherever the last operation left off.
You can also move the cursor with the move y,x method. Characters can ncurses library download windows free displayed in ncurses library download windows free ways. Status lines in a text-based application are commonly shown in reverse video, or a text viewer may need to highlight certain words.
An attribute is an integer, each bit representing a different attribute. The curses library also supports color on those terminals that provide it. The most common such terminal is probably the Linux console, followed by color xterms. The curses library maintains a finite number of color pairs, containing a foreground or text color and ncurses library download windows free background color. As I said before, a color pair consists of a foreground and background color.
Color ncurses library download windows free 0 is hard-wired to white on black, and cannot be changed. They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and 7:white. The curses module defines named constants for each of these colors: curses.
To change color 1 to red text on a white background, you would call:. When you change a color pair, any text already displayed using that color pair will change to the new colors. You can also display new text in this color with:. Very fancy terminals can change the definitions of the actual colors to a given RGB value.
This lets you change color 1, which is usually red, to purple or blue or any other color you like. The C curses library ncurses library download windows free only very simple input mechanisms. Other libraries such as Urwid have more extensive collections of widgets. You can optionally specify a coordinate to which the cursor should be moved before pausing.
After nodelay Truegetch and getkey for the window become non-blocking. To signal that no input is ready, getch returns curses. ERR a value of -1 and getkey raises an exception. Values greater than are special keys such as Page Ncurses library download windows free, Home, or the cursor keys. You can compare ncurses library download windows free value returned to constants such as curses. The main loop of your program may look something like this:. The curses. It also supplies conversion functions that take either integer or 1-character-string arguments and return the same type.
For example, curses. It can optionally be limited to a fixed number of characters. Various methods of the Textbox class support editing with input validation and gathering the edit results either with or without trailing spaces.
See the library documentation on curses.
