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
Concepts
Screen
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.
Cursor
The console driver keeps track of the current cursor position. However, only three methods actually use this position: write, page, and of course pos.
The cursor method allows you to switch the cursor on and off.
Styles
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")
Console Methods
Instances returned by getconsole have the following methods:
Basic Graphic Methods
text
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
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
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.
page
page()
Blanks the screen, and moves the cursor to (0, 0).
page
page(style, character)
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).
File-Like Output
write
write(string)
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.
pos
pos(column, line)
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
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.
Input
get
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
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
peek() => event
Fetch the first event from the input queue, without removing it. If the input queue is empty, this method returns None.
Console Properties
cursor
cursor(flag)
cursor(0) makes the text cursor invisible. cursor(1) makes it visible. [TBD: better name?]
size
size() => (width, height)
Get the current size of the console window, as a 2-tuple (width, height).
title
title(string)
Set the window title to string. If the string is omitted, this method returns the current title.
save
save()
TBD: document save and restore.
The Event Class
The get and peek methods return event descriptors. These are modelled after the Tkinter Event type, with a few minor differences.
Event Subtypes
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.
KeyPress
KeyRelease
ButtonPress
ButtonRelease
Motion
Configure
Event Attributes
type
type (string)
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.
char
char (string)
The character code for KeyPress or KeyRelease events. If this is empty, the event doesn’t have an ASCII representation.
keysym
keysym (string)
The symbolic name for KeyPress or KeyRelease events. If this is an empty string, this event doesn’t have a symbolic name.
state
state (integer)
The button and control key state. This is valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, and Motion events.
x, y
x (integer)
y (integer)
The current mouse coordinate. This is valid for ButtonPress, ButtonRelease, and Motion events.
width, height
width (integer)
height (integer)
The new window size. This is only valid for Configure events.
serial
serial (integer)
serial is the serial number for this event.
time
time (integer)
The relative time in milliseconds when this event was generated. In the current implementation, this is always 0.
widget
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.
License
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.
rendered by a django application. hosted by webfaction.