/Doc/howto/curses.rst

  1.. _curses-howto:
  2
  3**********************************
  4  Curses Programming with Python
  5**********************************
  6
  7:Author: A.M. Kuchling, Eric S. Raymond
  8:Release: 2.03
  9
 10
 11.. topic:: Abstract
 12
 13   This document describes how to write text-mode programs with Python 2.x, using
 14   the :mod:`curses` extension module to control the display.
 15
 16
 17What is curses?
 18===============
 19
 20The curses library supplies a terminal-independent screen-painting and
 21keyboard-handling facility for text-based terminals; such terminals include
 22VT100s, the Linux console, and the simulated terminal provided by X11 programs
 23such as xterm and rxvt.  Display terminals support various control codes to
 24perform common operations such as moving the cursor, scrolling the screen, and
 25erasing areas.  Different terminals use widely differing codes, and often have
 26their own minor quirks.
 27
 28In a world of X displays, one might ask "why bother"?  It's true that
 29character-cell display terminals are an obsolete technology, but there are
 30niches in which being able to do fancy things with them are still valuable.  One
 31is on small-footprint or embedded Unixes that don't carry an X server.  Another
 32is for tools like OS installers and kernel configurators that may have to run
 33before X is available.
 34
 35The curses library hides all the details of different terminals, and provides
 36the programmer with an abstraction of a display, containing multiple
 37non-overlapping windows.  The contents of a window can be changed in various
 38ways-- adding text, erasing it, changing its appearance--and the curses library
 39will automagically figure out what control codes need to be sent to the terminal
 40to produce the right output.
 41
 42The curses library was originally written for BSD Unix; the later System V
 43versions of Unix from AT&T added many enhancements and new functions. BSD curses
 44is no longer maintained, having been replaced by ncurses, which is an
 45open-source implementation of the AT&T interface.  If you're using an
 46open-source Unix such as Linux or FreeBSD, your system almost certainly uses
 47ncurses.  Since most current commercial Unix versions are based on System V
 48code, all the functions described here will probably be available.  The older
 49versions of curses carried by some proprietary Unixes may not support
 50everything, though.
 51
 52No one has made a Windows port of the curses module.  On a Windows platform, try
 53the Console module written by Fredrik Lundh.  The Console module provides
 54cursor-addressable text output, plus full support for mouse and keyboard input,
 55and is available from http://effbot.org/zone/console-index.htm.
 56
 57
 58The Python curses module
 59------------------------
 60
 61Thy Python module is a fairly simple wrapper over the C functions provided by
 62curses; if you're already familiar with curses programming in C, it's really
 63easy to transfer that knowledge to Python.  The biggest difference is that the
 64Python interface makes things simpler, by merging different C functions such as
 65:func:`addstr`, :func:`mvaddstr`, :func:`mvwaddstr`, into a single
 66:meth:`addstr` method.  You'll see this covered in more detail later.
 67
 68This HOWTO is simply an introduction to writing text-mode programs with curses
 69and Python. It doesn't attempt to be a complete guide to the curses API; for
 70that, see the Python library guide's section on ncurses, and the C manual pages
 71for ncurses.  It will, however, give you the basic ideas.
 72
 73
 74Starting and ending a curses application
 75========================================
 76
 77Before doing anything, curses must be initialized.  This is done by calling the
 78:func:`initscr` function, which will determine the terminal type, send any
 79required setup codes to the terminal, and create various internal data
 80structures.  If successful, :func:`initscr` returns a window object representing
 81the entire screen; this is usually called ``stdscr``, after the name of the
 82corresponding C variable. ::
 83
 84   import curses
 85   stdscr = curses.initscr()
 86
 87Usually curses applications turn off automatic echoing of keys to the screen, in
 88order to be able to read keys and only display them under certain circumstances.
 89This requires calling the :func:`noecho` function. ::
 90
 91   curses.noecho()
 92
 93Applications will also commonly need to react to keys instantly, without
 94requiring the Enter key to be pressed; this is called cbreak mode, as opposed to
 95the usual buffered input mode. ::
 96
 97   curses.cbreak()
 98
 99Terminals usually return special keys, such as the cursor keys or navigation
100keys such as Page Up and Home, as a multibyte escape sequence.  While you could
101write your application to expect such sequences and process them accordingly,
102curses can do it for you, returning a special value such as
103:const:`curses.KEY_LEFT`.  To get curses to do the job, you'll have to enable
104keypad mode. ::
105
106   stdscr.keypad(1)
107
108Terminating a curses application is much easier than starting one. You'll need
109to call  ::
110
111   curses.nocbreak(); stdscr.keypad(0); curses.echo()
112
113to reverse the curses-friendly terminal settings. Then call the :func:`endwin`
114function to restore the terminal to its original operating mode. ::
115
116   curses.endwin()
117
118A common problem when debugging a curses application is to get your terminal
119messed up when the application dies without restoring the terminal to its
120previous state.  In Python this commonly happens when your code is buggy and
121raises an uncaught exception.  Keys are no longer be echoed to the screen when
122you type them, for example, which makes using the shell difficult.
123
124In Python you can avoid these complications and make debugging much easier by
125importing the module :mod:`curses.wrapper`.  It supplies a :func:`wrapper`
126function that takes a callable.  It does the initializations described above,
127and also initializes colors if color support is present.  It then runs your
128provided callable and finally deinitializes appropriately.  The callable is
129called inside a try-catch clause which catches exceptions, performs curses
130deinitialization, and then passes the exception upwards.  Thus, your terminal
131won't be left in a funny state on exception.
132
133
134Windows and Pads
135================
136
137Windows are the basic abstraction in curses.  A window object represents a
138rectangular area of the screen, and supports various methods to display text,
139erase it, allow the user to input strings, and so forth.
140
141The ``stdscr`` object returned by the :func:`initscr` function is a window
142object that covers the entire screen.  Many programs may need only this single
143window, but you might wish to divide the screen into smaller windows, in order
144to redraw or clear them separately. The :func:`newwin` function creates a new
145window of a given size, returning the new window object. ::
146
147   begin_x = 20 ; begin_y = 7
148   height = 5 ; width = 40
149   win = curses.newwin(height, width, begin_y, begin_x)
150
151A word about the coordinate system used in curses: coordinates are always passed
152in the order *y,x*, and the top-left corner of a window is coordinate (0,0).
153This breaks a common convention for handling coordinates, where the *x*
154coordinate usually comes first.  This is an unfortunate difference from most
155other computer applications, but it's been part of curses since it was first
156written, and it's too late to change things now.
157
158When you call a method to display or erase text, the effect doesn't immediately
159show up on the display.  This is because curses was originally written with slow
160300-baud terminal connections in mind; with these terminals, minimizing the time
161required to redraw the screen is very important.  This lets curses accumulate
162changes to the screen, and display them in the most efficient manner.  For
163example, if your program displays some characters in a window, and then clears
164the window, there's no need to send the original characters because they'd never
165be visible.
166
167Accordingly, curses requires that you explicitly tell it to redraw windows,
168using the :func:`refresh` method of window objects.  In practice, this doesn't
169really complicate programming with curses much. Most programs go into a flurry
170of activity, and then pause waiting for a keypress or some other action on the
171part of the user.  All you have to do is to be sure that the screen has been
172redrawn before pausing to wait for user input, by simply calling
173``stdscr.refresh()`` or the :func:`refresh` method of some other relevant
174window.
175
176A pad is a special case of a window; it can be larger than the actual display
177screen, and only a portion of it displayed at a time. Creating a pad simply
178requires the pad's height and width, while refreshing a pad requires giving the
179coordinates of the on-screen area where a subsection of the pad will be
180displayed.   ::
181
182   pad = curses.newpad(100, 100)
183   #  These loops fill the pad with letters; this is
184   # explained in the next section
185   for y in range(0, 100):
186       for x in range(0, 100):
187           try: pad.addch(y,x, ord('a') + (x*x+y*y) % 26 )
188           except curses.error: pass
189
190   #  Displays a section of the pad in the middle of the screen
191   pad.refresh( 0,0, 5,5, 20,75)
192
193The :func:`refresh` call displays a section of the pad in the rectangle
194extending from coordinate (5,5) to coordinate (20,75) on the screen; the upper
195left corner of the displayed section is coordinate (0,0) on the pad.  Beyond
196that difference, pads are exactly like ordinary windows and support the same
197methods.
198
199If you have multiple windows and pads on screen there is a more efficient way to
200go, which will prevent annoying screen flicker at refresh time.  Use the
201:meth:`noutrefresh` method of each window to update the data structure
202representing the desired state of the screen; then change the physical screen to
203match the desired state in one go with the function :func:`doupdate`.  The
204normal :meth:`refresh` method calls :func:`doupdate` as its last act.
205
206
207Displaying Text
208===============
209
210From a C programmer's point of view, curses may sometimes look like a twisty
211maze of functions, all subtly different.  For example, :func:`addstr` displays a
212string at the current cursor location in the ``stdscr`` window, while
213:func:`mvaddstr` moves to a given y,x coordinate first before displaying the
214string. :func:`waddstr` is just like :func:`addstr`, but allows specifying a
215window to use, instead of using ``stdscr`` by default. :func:`mvwaddstr` follows
216similarly.
217
218Fortunately the Python interface hides all these details; ``stdscr`` is a window
219object like any other, and methods like :func:`addstr` accept multiple argument
220forms.  Usually there are four different forms.
221
222+---------------------------------+-----------------------------------------------+
223| Form                            | Description                                   |
224+=================================+===============================================+
225| *str* or *ch*                   | Display the string *str* or character *ch* at |
226|                                 | the current position                          |
227+---------------------------------+-----------------------------------------------+
228| *str* or *ch*, *attr*           | Display the string *str* or character *ch*,   |
229|                                 | using attribute *attr* at the current         |
230|                                 | position                                      |
231+---------------------------------+-----------------------------------------------+
232| *y*, *x*, *str* or *ch*         | Move to position *y,x* within the window, and |
233|                                 | display *str* or *ch*                         |
234+---------------------------------+-----------------------------------------------+
235| *y*, *x*, *str* or *ch*, *attr* | Move to position *y,x* within the window, and |
236|                                 | display *str* or *ch*, using attribute *attr* |
237+---------------------------------+-----------------------------------------------+
238
239Attributes allow displaying text in highlighted forms, such as in boldface,
240underline, reverse code, or in color.  They'll be explained in more detail in
241the next subsection.
242
243The :func:`addstr` function takes a Python string as the value to be displayed,
244while the :func:`addch` functions take a character, which can be either a Python
245string of length 1 or an integer.  If it's a string, you're limited to
246displaying characters between 0 and 255.  SVr4 curses provides constants for
247extension characters; these constants are integers greater than 255.  For
248example, :const:`ACS_PLMINUS` is a +/- symbol, and :const:`ACS_ULCORNER` is the
249upper left corner of a box (handy for drawing borders).
250
251Windows remember where the cursor was left after the last operation, so if you
252leave out the *y,x* coordinates, the string or character will be displayed
253wherever the last operation left off.  You can also move the cursor with the
254``move(y,x)`` method.  Because some terminals always display a flashing cursor,
255you may want to ensure that the cursor is positioned in some location where it
256won't be distracting; it can be confusing to have the cursor blinking at some
257apparently random location.
258
259If your application doesn't need a blinking cursor at all, you can call
260``curs_set(0)`` to make it invisible.  Equivalently, and for compatibility with
261older curses versions, there's a ``leaveok(bool)`` function.  When *bool* is
262true, the curses library will attempt to suppress the flashing cursor, and you
263won't need to worry about leaving it in odd locations.
264
265
266Attributes and Color
267--------------------
268
269Characters can be displayed in different ways.  Status lines in a text-based
270application are commonly shown in reverse video; a text viewer may need to
271highlight certain words.  curses supports this by allowing you to specify an
272attribute for each cell on the screen.
273
274An attribute is a integer, each bit representing a different attribute.  You can
275try to display text with multiple attribute bits set, but curses doesn't
276guarantee that all the possible combinations are available, or that they're all
277visually distinct.  That depends on the ability of the terminal being used, so
278it's safest to stick to the most commonly available attributes, listed here.
279
280+----------------------+--------------------------------------+
281| Attribute            | Description                          |
282+======================+======================================+
283| :const:`A_BLINK`     | Blinking text                        |
284+----------------------+--------------------------------------+
285| :const:`A_BOLD`      | Extra bright or bold text            |
286+----------------------+--------------------------------------+
287| :const:`A_DIM`       | Half bright text                     |
288+----------------------+--------------------------------------+
289| :const:`A_REVERSE`   | Reverse-video text                   |
290+----------------------+--------------------------------------+
291| :const:`A_STANDOUT`  | The best highlighting mode available |
292+----------------------+--------------------------------------+
293| :const:`A_UNDERLINE` | Underlined text                      |
294+----------------------+--------------------------------------+
295
296So, to display a reverse-video status line on the top line of the screen, you
297could code::
298
299   stdscr.addstr(0, 0, "Current mode: Typing mode",
300                 curses.A_REVERSE)
301   stdscr.refresh()
302
303The curses library also supports color on those terminals that provide it, The
304most common such terminal is probably the Linux console, followed by color
305xterms.
306
307To use color, you must call the :func:`start_color` function soon after calling
308:func:`initscr`, to initialize the default color set (the
309:func:`curses.wrapper.wrapper` function does this automatically).  Once that's
310done, the :func:`has_colors` function returns TRUE if the terminal in use can
311actually display color.  (Note: curses uses the American spelling 'color',
312instead of the Canadian/British spelling 'colour'.  If you're used to the
313British spelling, you'll have to resign yourself to misspelling it for the sake
314of these functions.)
315
316The curses library maintains a finite number of color pairs, containing a
317foreground (or text) color and a background color.  You can get the attribute
318value corresponding to a color pair with the :func:`color_pair` function; this
319can be bitwise-OR'ed with other attributes such as :const:`A_REVERSE`, but
320again, such combinations are not guaranteed to work on all terminals.
321
322An example, which displays a line of text using color pair 1::
323
324   stdscr.addstr( "Pretty text", curses.color_pair(1) )
325   stdscr.refresh()
326
327As I said before, a color pair consists of a foreground and background color.
328:func:`start_color` initializes 8 basic colors when it activates color mode.
329They are: 0:black, 1:red, 2:green, 3:yellow, 4:blue, 5:magenta, 6:cyan, and
3307:white.  The curses module defines named constants for each of these colors:
331:const:`curses.COLOR_BLACK`, :const:`curses.COLOR_RED`, and so forth.
332
333The ``init_pair(n, f, b)`` function changes the definition of color pair *n*, to
334foreground color f and background color b.  Color pair 0 is hard-wired to white
335on black, and cannot be changed.
336
337Let's put all this together. To change color 1 to red text on a white
338background, you would call::
339
340   curses.init_pair(1, curses.COLOR_RED, curses.COLOR_WHITE)
341
342When you change a color pair, any text already displayed using that color pair
343will change to the new colors.  You can also display new text in this color
344with::
345
346   stdscr.addstr(0,0, "RED ALERT!", curses.color_pair(1) )
347
348Very fancy terminals can change the definitions of the actual colors to a given
349RGB value.  This lets you change color 1, which is usually red, to purple or
350blue or any other color you like.  Unfortunately, the Linux console doesn't
351support this, so I'm unable to try it out, and can't provide any examples.  You
352can check if your terminal can do this by calling :func:`can_change_color`,
353which returns TRUE if the capability is there.  If you're lucky enough to have
354such a talented terminal, consult your system's man pages for more information.
355
356
357User Input
358==========
359
360The curses library itself offers only very simple input mechanisms. Python's
361support adds a text-input widget that makes up some of the lack.
362
363The most common way to get input to a window is to use its :meth:`getch` method.
364:meth:`getch` pauses and waits for the user to hit a key, displaying it if
365:func:`echo` has been called earlier.  You can optionally specify a coordinate
366to which the cursor should be moved before pausing.
367
368It's possible to change this behavior with the method :meth:`nodelay`. After
369``nodelay(1)``, :meth:`getch` for the window becomes non-blocking and returns
370``curses.ERR`` (a value of -1) when no input is ready.  There's also a
371:func:`halfdelay` function, which can be used to (in effect) set a timer on each
372:meth:`getch`; if no input becomes available within a specified
373delay (measured in tenths of a second), curses raises an exception.
374
375The :meth:`getch` method returns an integer; if it's between 0 and 255, it
376represents the ASCII code of the key pressed.  Values greater than 255 are
377special keys such as Page Up, Home, or the cursor keys. You can compare the
378value returned to constants such as :const:`curses.KEY_PPAGE`,
379:const:`curses.KEY_HOME`, or :const:`curses.KEY_LEFT`.  Usually the main loop of
380your program will look something like this::
381
382   while 1:
383       c = stdscr.getch()
384       if c == ord('p'): PrintDocument()
385       elif c == ord('q'): break  # Exit the while()
386       elif c == curses.KEY_HOME: x = y = 0
387
388The :mod:`curses.ascii` module supplies ASCII class membership functions that
389take either integer or 1-character-string arguments; these may be useful in
390writing more readable tests for your command interpreters.  It also supplies
391conversion functions  that take either integer or 1-character-string arguments
392and return the same type.  For example, :func:`curses.ascii.ctrl` returns the
393control character corresponding to its argument.
394
395There's also a method to retrieve an entire string, :const:`getstr()`.  It isn't
396used very often, because its functionality is quite limited; the only editing
397keys available are the backspace key and the Enter key, which terminates the
398string.  It can optionally be limited to a fixed number of characters. ::
399
400   curses.echo()            # Enable echoing of characters
401
402   # Get a 15-character string, with the cursor on the top line
403   s = stdscr.getstr(0,0, 15)
404
405The Python :mod:`curses.textpad` module supplies something better. With it, you
406can turn a window into a text box that supports an Emacs-like set of
407keybindings.  Various methods of :class:`Textbox` class support editing with
408input validation and gathering the edit results either with or without trailing
409spaces.   See the library documentation on :mod:`curses.textpad` for the
410details.
411
412
413For More Information
414====================
415
416This HOWTO didn't cover some advanced topics, such as screen-scraping or
417capturing mouse events from an xterm instance.  But the Python library page for
418the curses modules is now pretty complete.  You should browse it next.
419
420If you're in doubt about the detailed behavior of any of the ncurses entry
421points, consult the manual pages for your curses implementation, whether it's
422ncurses or a proprietary Unix vendor's.  The manual pages will document any
423quirks, and provide complete lists of all the functions, attributes, and
424:const:`ACS_\*` characters available to you.
425
426Because the curses API is so large, some functions aren't supported in the
427Python interface, not because they're difficult to implement, but because no one
428has needed them yet.  Feel free to add them and then submit a patch.  Also, we
429don't yet have support for the menus or panels libraries associated with
430ncurses; feel free to add that.
431
432If you write an interesting little program, feel free to contribute it as
433another demo.  We can always use more of them!
434
435The ncurses FAQ: http://invisible-island.net/ncurses/ncurses.faq.html
436