Console

Commands related to Windows consoles

SYNOPSIS

package require twapi

allocate_console
clear_console CONOUTH ?-fillchar CHARACTER? ?-windowonly BOOL?
console_read CONINH ?options?
create_console_screen_buffer ?options?
fill_console CONOUTH ?options?
flush_console_input CONINH
free_console
generate_console_control_event EVENT ?PROCESSGROUP?
get_console_handle TYPE
get_console_input_codepage
get_console_input_mode ?CONINH?
get_console_output_mode ?CONOUTH?
get_console_pending_input_count CONINH
get_console_screen_buffer_info CONH ?options?
get_console_title
get_console_window
get_console_window_maxsize
get_standard_handle TYPE
modify_console_input_mode CONINH MODEOPTIONS...
modify_console_output_mode CONOUTH MODEOPTIONS...
num_console_mouse_buttons
set_console_active_screen_buffer CONOUTH
set_console_control_handler SCRIPT
set_console_cursor_position CONOUTH X Y
set_console_default_attr CONOUTH ?options?
set_console_input_codepage CODEPAGE
set_console_input_mode CONINH MODEOPTIONS...
set_console_output_codepage CODEPAGE
set_console_output_mode CONOUTH MODEOPTIONS...
set_console_screen_buffer_size CONOUTH SCRSIZE
set_console_title TEXT
set_console_window_location CONOUTH RECT ?-absolute BOOL?
set_standard_handle TYPE HANDLE
write_console CONOUTH STRING ?options?

DESCRIPTION

This module provides commands for manipulating console windows.

Consoles

A console may have multiple processes attached to it. However, a process may be attached to at most one console. Character mode applications are generally started with a console attached. GUI mode processes however do not have a console attached. The command allocate_console may be used to allocate and attach to a console. An allocated console may be released with the free_console command.

Console Handles

The input and screen buffers for a console are identified by handles that can be retrieved through the get_console_handle call. Alternately, the the strings stdin, stdout and stderr may be passed to the various console commands to identify the input, output and error handles. The standard input, output and error handles may be retrieved through the get_standard_handle calls. These may not refer to the console if standard input/output has been redirected.

Console Input

A console is associated with an input buffer that contains input events such as keyboard and mouse inputs. The console can be read through the console_read command. The number of events in the input buffer can be obtained through get_console_pending_input_count and any pending events can be flushed through flush_console_input.

Console input is associated with a specific code page that can be retrieved and set through the get_console_input_codepage and set_console_input_codepage commands.

A console control event may be generated with the generate_console_control_event command. Console control event handlers may be set up with the set_console_control_handler command.

The number of mouse buttons available through the console interface is returned by the num_console_mouse_buttons command.

Console Output

A console may have one or more screen buffers only one of which is active and visible at a time. A screen buffer is a two dimensional array of cells with each cell containing a character and an attribute that controls how the character is displayed. Screen buffers can be written to with the write_console command. The code page used for output can be retrieved and set through the get_console_output_codepage and set_console_output_codepage commands.

Screen buffers can be allocated through create_console_screen_buffer and made to be the active buffer by calling set_console_active_screen_buffer. The size of the buffer can be controlled through the set_console_screen_buffer_size command.

The console window is the portion of the screen buffer that is actually visible on the display. The command set_console_window_location can be used to control the location of this window into the screen buffer. The window handle of the console window can be obtained through the get_console_window command. The maximum possible size of the window that can fit on the display given the font can be obtained through get_console_window_maxsize. The title associated with a console window may be retrieved and set through the get_console_title and set_console_title respectively.

The command clear_console clears the screen buffer or a portion of it and can optionally fill it with a specific character.

Characteristics of the screen buffer such as buffer size, cursor position, window coordinates can be obtained through get_console_screen_buffer_info.

Console Modes

A console's input and output modes control how characters are handled when when entered and displayed.

Characters typed into a console window may be handled differently based on the input mode of the console. The commands get_console_input_mode, set_console_input_mode and modify_console_input_mode allow retrieval and setting of the input mode. The various mode settings are specified as arguments to these functions and may contain zero or more of the following elements:

-autoposition BOOL If true, position of console windows is determined by the operating system when the windows are opened.
-echoinput BOOL If true, characters are echoed as they are read in. This is only valid if the -lineinput mode is true.
-extendedmode BOOL Must be set if -quickeditmode or -insertmode are specified.
-insertmode BOOL If true, characters are inserted as they entered and do not overwrite the characters at the current cursor position.
-lineinput BOOL If true, calls to read input only return when a carriage return character is read.
-mouseinput BOOL If true, mouse events are placed in the input queue when the console window has focus and the mouse is within the window coordinates.
-processedinput BOOL If true, control characters are handled by the system and not placed in the input queue. If -lineinput is also true, carriage returns, line feeds and tabs are also handled by the system.
-quickeditmode BOOL If true, allows the user to use the mouse to select and edit text.
-windowinput BOOL If true, changes in the console window coordinates are reported through the input queue.
In a similar fashion, the characters written to a screen buffer may be displayed differently depending on the output mode of the console. The commands get_console_output_mode, set_console_output_mode and modify_console_output_mode allow retrieval and setting of the input mode. The various mode settings are specified as arguments to these functions and may contain zero or more of the following elements:

-processedoutput BOOL If true, characters written to the screen buffer are processed for ASCII control characters - backspace, tab, bell, carriage return, linefeed - and appropriate action taken.
-wrapoutput BOOL If true, characters written to the screen buffer will wrap around to the next row when the end of row is reached. Otherwise, the last character in the row will be overwritten with characters that extend beyond the width of the row.

Text Attributes

Each cell in a screen buffer has attributes that control the display characteristics of that cell. The default attribute used for writing to the screen buffer can be set through set_console_default_attr.

Text attributes are retrieved and controlled through the following options:

-bgCOLOR BOOL If true, adds COLOR to the background text color. COLOR may be one of blue, green, red, purple, yellow, gray, or white.
-fgCOLOR BOOL If true, adds COLOR to the foreground text color. COLOR may be one of blue, green, red, purple, yellow, gray, or white.
-fgbright BOOL If true, intensifies the foreground color.
-bgbright BOOL If true, intensifies the background color.
The command fill_console can be used to change the attribute of portions of the screen buffer.

Commands

allocate_console
Allocates a console for the process. If the process already has a console, an error exception is generated.

clear_console CONOUTH ?-fillchar CHARACTER? ?-windowonly BOOL?
If no option are specified, sets the contents of the entire screen buffer to spaces. The -fillchar option may be used to specify a different character to use. If -windowonly is specified as true, only the portion of screen buffer that is visible is cleared.

console_read CONINH ?options?
Reads input from the console. Note that the input is from the console even if standard input has been redirected. options specify the input mode to use and are passed to modify_console_input_mode before input is read. The original mode is restored before returning.

create_console_screen_buffer ?options?
Creates a new console screen buffer and returns a handle to it. The following options may be specified:

-inherit BOOL If true, the returned handle is inheritable by child processes.
-mode read|write|readwrite Specifies whether the buffer access is read, write or both.
-secd SECURITY_DESCRIPTOR Specifies a security descriptor to be attached to the screen buffer.
-share none|read|write|readwrite Specifies whether the buffer is not shared or can be shared for read, write or both (default).


The allocated screen buffer handle should be closed by calling close_handles when no longer needed.

fill_console CONOUTH ?options?
Sets the text attribute of cells in specified area of the screen buffer. The text attributes are specified with one or more of the options described in Text Attributes. The following additional options may also be specified:

-fillchar CHARACTER Normally, the command does not change the text contents in the specified region. If this option is specified, in addition to changing the attributes in the specified region, the contents of each cell are set to CHARACTER.
-mode line|column If specified as column (default), the fill region in the second line starts at the same column as the first line. If specified as line, the fill region starts at the first column in the second and subsequent lines.
-numcols INTEGER Width of the region to be filled. By default, the fill region extends to the rightmost column of the screen buffer.
-numlines INTEGER Number of rows to be filled. By default, the fill region extends to the rightmost column of the screen buffer.
-position POSITION Location of the top left corner of the fill region. POSITION is specified as a list of two integers corresponding to the column and row.
-window BOOL If specified as true, the fill region is the visible window portion of the screen buffer. This option cannot be used with the -position, -numlines and -numrows options.


flush_console_input CONINH
Removes any pending input events from the buffer of the specified input console.

free_console
Frees the console attached to the process.

generate_console_control_event EVENT ?PROCESSGROUP?
Sends a control event to a process group. EVENT should be one of ctrl-c or ctrl-break. PROCESSGROUP indicates the console process group to which the event should be sent. By default, the event is sent to all processes sharing the console of the caller.

get_console_handle TYPE
Returns a handle to console input, output or error. Note if input and output have been redirected, the handle may not be the same as returned by get_standard_handle. TYPE must be stdin or stdout.

get_console_input_codepage
Returns the input code page of the console.

get_console_input_mode ?CONINH?
Returns the input mode of the console. CONINH is a handle to console input and defaults to stdin. The returned value is a list describing the current mode. See Console Modes for the possible values.

get_console_output_mode ?CONOUTH?
Returns the output mode of the console. CONOUTH is a handle to console output and defaults to stdout. The returned value is a list describing the current mode. See Console Modes for the possible values.

get_console_pending_input_count CONINH
Returns the number of pending input events for the specified console.

get_console_screen_buffer_info CONH ?options?
Retrieves various information about a screen buffer as a flat list of option VALUE pairs. The following options determine what information is returned:

-all Equivalent to specifying all other options.
-cursorpos Returns the cursor position in the screen buffer.
-maxwindowsize Returns the maximum possible size of a window in the screen buffer as a pair of integer corresponding to the width and height. This takes into account the screen buffer size, the display size and the font being used.
-size Returns a list of two integers containing the number of columns and rows in the screen buffer.
-textattr Returns the default text attributes used when writing into the screen buffer.
-windowpos Returns a list of two integers corresponding to the column and row of the top left cell of the window.
-windowsize Returns a list of two integers containing the number of columns and rows in the window.


get_console_title
Returns the title of the window of the currently attached console.

get_console_window
Returns the handle to the window displaying the currently attached console.

get_console_window_maxsize
Returns the maximum size of a console window given the current display size and font as a list of two integers corresponding to the width and height. This command does not take into account the size of the screen buffer itself. The -maxwindowsize option of get_console_screen_buffer_info does take into account the screen buffer size.

get_standard_handle TYPE
Returns a handle to standard input, output or error. This may correspond to the console or some other device if the standard devices have been redirected. If the process does not have associated standard handles, an exception is generated with errorCode set to WINDOWS 2 ERRORMESSAGE. If the returned handle corresponds to a console device, it can be passed to the other console commands. TYPE is one of stdin, stdout, stderr.

Note this command returns a handle to standard input, output and error, which may not be the console if they have been redirected. To retrieve handles to the console, use the get_console_handle function.

modify_console_input_mode CONINH MODEOPTIONS...
Modifies the input modes for the console identified by CONINH according to the mode options specified. MODEOPTIONS must correspond to the input mode options described in Console Modes. Any options not specified are unchanged. The command returns the previous input modes of the console.

Also see set_console_input_mode.

modify_console_output_mode CONOUTH MODEOPTIONS...
Modifies the output modes for the console identified by CONOUTH according to the mode options specified. MODEOPTIONS must correspond to the output mode options described in Console Modes. Any options not specified are unchanged. The command returns the previous output modes of the console.

Also see set_console_output_mode.

num_console_mouse_buttons
Returns the number of console mouse buttons.

set_console_active_screen_buffer CONOUTH
Sets the active screen buffer of the currently attached console to CONOUTH.

set_console_control_handler SCRIPT
Registers SCRIPT to be invoked when a console application receives one of the control events in the table below. The appropriate event name is appended to SCRIPT before it is invoked. The script should return a non-zero integer value if it has handled the event itself. Any other value returned from the script will result in the event being passed on to other handlers including the operating system default handler.

Calling the command a second time will result in the previous callback script being replaced. So if multiple scripts are to be invoked, the application has to do the chaining itself.

If SCRIPT is empty, the callback handler is unregistered.

In order for the callback scripts to be invoked, the Tcl event loop must be running (through vwait, update etc.). Note that this function should be used only in console applications, not Win32 GUI applications.

The following event names are passed to SCRIPT.

ctrl-c A Ctrl-C signal was received.
ctrl-break A Ctrl-Break signal was received.
close The user requested the console window to be closed.
logoff The user is logging off.
shutdown The system is being shut down.

set_console_cursor_position CONOUTH X Y
Sets the cursor position in a screen buffer. CONOUTH is the handle to the buffer and X Y is a list of two integers specifying the column and row that the cursor is to be positioned at.

set_console_default_attr CONOUTH ?options?
Sets the default attribute to be used when writing to the specified screen buffer. See Text Attributes for a list of valid options.

set_console_input_codepage CODEPAGE
Sets the input code page of the console.

set_console_input_mode CONINH MODEOPTIONS...
Sets the input mode for the console identified by CONINH according to the mode options specified. MODEOPTIONS must correspond to the input mode options described in Console Modes. Any options not specified are assumed to be false. To change the input mode for specific options without affecting others, use modify_console_input_mode. For example,

    set_console_input_mode stdin -echoinput 0 -lineinput 1

will set the console input to only have mode -lineinput set. -echoinput as well as unspecified modes will be reset. On the other hand,

    modify_console_input_mode stdin -echoinput 0 -lineinput 1

will turn off -echoinput mode, turn on -lineinput mode but will leave others unchanged.

set_console_output_codepage CODEPAGE
Sets the output code page of the console.

set_console_output_mode CONOUTH MODEOPTIONS...
Sets the output modes for the console identified by CONOUTH according to the modes specified. MODEOPTIONS must correspond to the output modes described in Console Modes. Any modes not specified are reset. To change the output modes for specific options without affecting others, use modify_console_output_mode. For example,

    set_console_output_mode stdout -processedoutput 0

will set the console output to only have mode -processedoutput set. On the other hand,

    modify_console_output_mode stdout -processedoutput 0

will turn off -processedoutput mode but leave others unchanged.

set_console_screen_buffer_size CONOUTH SCRSIZE
Sets the size of the specified console screen buffer. SCRSIZE should be a list of two integers containing the width and height of the screen buffer in characters.

set_console_title TEXT
Sets the title of the window of the currently attached console to TEXT.

set_console_window_location CONOUTH RECT ?-absolute BOOL?
Sets the position and size of the visible window within the specified screen buffer. RECT is a list of four integers containing the left column position, the top row position, the right column position and the bottom row position. If option -absolute is true (default), the coordinates are absolute coordinates in the screen buffer. Otherwise, they are relative to the current window coordinates.

set_standard_handle TYPE HANDLE
Redirects standard input, output or error to the specified HANDLE. TYPE is one of stdin, stdout, stderr. HANDLE may be any handle to a device.

write_console CONOUTH STRING ?options?
Writes the sequence of characters in STRING to the screen buffer identified by CONOUTH. The characters are always written to the screen buffer in raw mode, i.e. as if the -processedoutput mode (see Console Modes) was off. The original mode setting is restored after the write is completed. Note however, that newline characters are treated specially.

In addition, the following options may be specified to alter the behavour of the write.

-newlinemode line|column If the -newlinemode is set to column (default), a newline character in STRING causes further characters to be written at the original starting column position on the next line. If the option is specified as line, characters after the newline character are written starting at the first column on the next line.
-position COORD By default, the characters are written starting at the current cursor position. This option may be specified to change the location at which the characters are written. COORD is a list of two integers containing the column and row coordinates of the starting location.
-restoreposition BOOL

COPYRIGHT

Copyright © 2004-2006 Ashok P. Nadkarni