The Console Module
Updated December 2, 2000 | Fredrik Lundh
The Console module provides a simple console interface, which provides cursor-addressable text output, plus support for keyboard and mouse input.
The Console module is currently only available for Windows 95, 98, NT, and 2000. It probably works under Windows XP, but it hasn’t been tested on that platform.
Software (including precompiled binaries) and documentation can be downloaded from http://effbot.org/downloads
The console screen consists of a 2-dimensional grid containing character cells. All characters cells have the same size.
Each character cell has a unique coordinate (column, row). The coordinate origin (0, 0) is in the upper left corner, as usual.
You can use negative coordinates as well. They work pretty much like negative sequence indexes in Python; for example, column -1 is the rightmost column on the console.
The rectangle and save methods require you to specify character rectangles. A rectangle is a tuple containing two coordinate pairs. The second pair of coordinates specify the cell just to the right and below the last cell in the rectangle. In other words, the rectangle (0, 0, 20, 10) is twenty characters wide and ten characters high.
Note that the second coordinate must be equal to or larger than the first coordinate. Also, the current implementation doesn’t support negative coordinates in rectangles.
The cursor method allows you to switch the cursor on and off.
Several methods take style arguments. The style is an integer value that combines a foreground and a background color. The console driver supports 16 colors in total:
0 = black (#000000) 1 = blue (#0000a8) 2 = dark green (#00a800) 3 = n/a (#00a8a8) 4 = red (#a80000) 5 = magenta (#a800a8) 6 = brown (#a8a800) 7 = light grey (#a8a8a8) 8 = dark grey (#545454) 9 = n/a (#5454fc) 10 = green (#54fc54) 11 = cyan (#54fcfc) 12 = n/a (#fc5454) 13 = n/a (#fc54fc) 14 = yellow (#fcfc54) 15 = white (#fcfcfc)
To calculate the style, combine the colour for the foreground and background as follows:
style = foreground + background*16
The default style is light grey on black background.
TBD: add names for remaining colors (see the HTML 3.2 specification?)
The Console Class
To create a Console instance, import the Console module and call the getconsole factory function.
import Console c = Console.getconsole() c.title("Console Example") c.text(0, 0, "here's some white text on white background", 0x1f) c.text(10, 5, "line five, column ten")
Instances returned by getconsole have the following methods:
Basic Graphic Methods
text(column, line, string, style)
Write string to the screen at the given position, using the given style. This method does not move the cursor. If the style is omitted, it defaults to white text on black background.
rectangle(rect, style, character)
Blanks the given rectangle. The rect argument should be a 4-tuple. If the character argument is omitted, it defaults to space. If the style argument is omitted, it defaults to black.
scroll(rect, dx, dy, style, character)
Moves the given rectangle dx cells to the right (or left, if dx is negative), and dy cells down (or up). The style and character attributes are used to fill empty regions. If the character argument is omitted, it defaults to space. If the style argument is omitted, it defaults to black.
Blanks the screen, and moves the cursor to (0, 0).
Clears the screen, using the given style and fill character. The style will also become the new default style. It moves the cursor to (0, 0).
Writes string at the current position, using a default style. This method treats the console as a conventional text terminal, which means that tabs, backspace, newline, and the bell character works as expected. The cursor is moved to the position just after the last written character.
Moves the cursor to the given column and line. If the coordinates are omitted, this method returns the current cursor position [TBD: better name?]
softspace (integer def)
This attribute isn’t used by the console driver itself, but is there to make sure Python’s print statement works as expected when printing to a console device.
get() => event
Get the first event from the input queue. The return value is an instance of the Event class. If the input queue is empty, this method blocks.
getchar() => event
Get the first character event from the input queue, ignoring any other kind of event. The return value is an instance of the KeyPress class. If the input queue is empty, this method blocks.
peek() => event
Fetch the first event from the input queue, without removing it. If the input queue is empty, this method returns None.
cursor(0) makes the text cursor invisible. cursor(1) makes it visible. [TBD: better name?]
size() => (width, height)
Get the current size of the console window, as a 2-tuple (width, height).
Set the window title to string. If the string is omitted, this method returns the current title.
TBD: document save and restore.
The Event Class
Note: In the current release, all event objects are implemented using the same Python type. To check what kind of event you have, use the type attribute.
The event type, given as a string. This attribute contains one of KeyPress, KeyRelease, ButtonPress, ButtonRelease, Motion, or Configure. Other event types may be returned, but such events should always be ignored by the application.
The new window size. This is only valid for Configure events.
serial is the serial number for this event.
The relative time in milliseconds when this event was generated. In the current implementation, this is always 0.
widget (widget or None)
The widget that generated this event. Unless you’re using a console widget toolkit built on top of this module, this is always None.
The Console module was written by Fredrik Lundh at Secret Labs AB, in January 1999.
Copyright © 1999-2000 by Secret Labs AB
Copyright © 1999-2000 by Fredrik Lundh
By obtaining, using, and/or copying this software and/or its associated documentation, you agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, modify, and distribute this software and its associated documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies, and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Secret Labs AB or the author not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.
SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.