The Console Module

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, and NT.

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 coordinates. 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 fill 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


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(column, line, string, style) writes string to the screen at the given position, using the given style. This method does not move the cursor.

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.

page() blanks the screen, and moves the cursor to (0, 0).

page(style, character) clears the screen, using the given style and fill character. It moves the cursor to (0, 0).

File-Like Output

write(string) writes text to the window title to 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(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?]

Input

get() returns the first event from the input queue. The return value is an instance of the Event class (see below). If the input queue is empty, this method blocks.

peek() returns the first event from the input queue, without removing it. If the input queue is empty, this method returns None.

Console Properties

cursor(0) makes the text cursor invisible. cursor(1) makes it visible. [TBD: better name?]

size() returns the current size of the console window, as a 2-tuple (width, height).

title(string) sets the window title to string. If the string is omitted, this method returns the current title.

TBD: document save and restore

Attributes

softspace is an integer attribute. This isn't used by the console driver itself, but is there to make sure the print statement works as expected when printing to a console device.

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 Attributes

type is the event type. This is 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 is the character code for KeyPress or KeyRelease events. If this is empty, the event doesn't have an ASCII representation.

keycode is the numerical keycode for KeyPress or KeyRelease events.

keysym is the symbolic name for KeyPress or KeyRelease events. If this is an empty string, this event doesn't have a symbolic name.

state is the button and control key state. This is valid for KeyPress, KeyRelease, ButtonPress, ButtonRelease, and Motion events.

x, y is the current mouse coordinate. This is valid for ButtonPress, ButtonRelease, and Motion events.

width, height is the new window size. This is only valid for Configure events.

serial is the serial number for this event.

time is the relative time in milliseconds when this event was generated. In the current implementation, this is always 0.

widget is the widget that generated this event. Unless you're using uiToolkit/Text or another console widget toolkit built on top of this module, this is always None.

License Details

The Console module was written by Fredrik Lundh at Secret Labs AB, in January 1999.

Copyright (c) 1999 by Secret Labs AB

Copyright (c) 1999 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.