We're back after a server migration that caused effbot.org to fall over a bit harder than expected. Expect some glitches.

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.

Example: Example: Using the Console module
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.

keycode

keycode (integer)

The numerical keycode for KeyPress or KeyRelease events.

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.