Tcl Windows API extension

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 high-level console_read command or through console_read_input_records which return low-level input records. These commands should generally not be intermixed with use Tcl's gets or read commands to read from standard input if it has not been redirected to a file.

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 console_write 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 commands get_console_window_location and set_console_window_location can be used to retrieve and set 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. The position of the cursor can be retrived or set through the commands get_console_cursor_position and set_console_cursor_position respectively.

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, 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:

-echoinput BOOL	If true, characters are echoed as they are read in. This is only valid if the -lineinput mode is true.
-extendedmode BOOL	This is automatically 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. If false, input is returned without a carraige return character required. Note when multiple characters are typed, they may be returned in a single read or require multiple reads. If this option is specified as false, the -echoinput option must also be specified to be false or be already set to false in the console input mode.
-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, 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.

This command should generally not be intermixed with use Tcl's gets or read commands to read from standard input if it has not been redirected to a file.

console_read_input_records CONINH ?-peek? ?-count COUNT?

Reads low-level input records from the console including function keys, mouse actions and window sizing events which are not passed through to console_read. Note that receiving mouse and window events requires that mouse and window events are enabled for the console window are described in Console Modes.

If -peek is specified, the read records are not removed from the input queue.

The -count option specifies the maximum number of records to return and defaults to 1. The actual number returned may be less than this. The command will block until at least one record is available in the input queue unless the -peek option is specified in which case it returns right away even if no records are available.

The returned value is a list of input records each of which is represented as a pair of elements. The first element in the pair indicates the type of the event:

focus

Internally used by the system and should be ignored.

key

Indicates a keyboard event. The second element in the pair is a dictionary with the following entries:

char	Value is the character entered. For keys like the arrow keys, this is set to the empty string.
controls	A list of zero or more of the following values: capslock, enhanced, leftalt, leftctrl, numlock, rightalt, rightctrl, scrolllock, and shift. All indicate the state of the control and modifier keys except enhanced which indicates that the key is an enhanced key.
keycode	The virtual key code for the key.
keystate	Either up or down depending whether the key is pressed or not.
repeat	An integer indicating how many times the key has been repeated. This should be treated as the input record having occured that many times.
scancode	The virtual scan code for the key.

Internally used by the system and should be ignored.

mouse

Indicates a mouse event. Mouse events should be enabled and quick edit mode disabled for this event type to be received as described in Console Modes. The second element in the pair is a dictionary with the following entries:

buttons	The value is a list that indicates which buttons are pressed. This is a list of zero or more button specifiers: left for the leftmost button, right for the rightmost button and left2, left3, left4 for the buttons starting from the left where the number indicates the position.
controls	Specifies which control keys are pressed. See the description of the key event type for details.
doubleclick	The value is a boolean indicating whether this corresponds to a double-click of a button.
horizontalwheel	Indicates that the horizontal wheel was rotated. A negative value indicates the wheel was rotated left, a positive value indicates the wheel was rotated right.
moved	The value is a boolean indicating whether the mouse position was changed.
position	The value is the position of the mouse in character cell coordinates.
verticalwheel	Indicates that the vertical wheel was rotated. A negative value indicates the wheel was rotated backward (towards user), a positive value indicates the wheel was rotated forward.

buffersize

Indicates a change in the screen buffer size. The second element in the pair specifies the new screen buffer width and height (in characters). Window events should be enabled for this event type to be received as described in Console Modes.

This command should generally not be intermixed with use Tcl's gets or read commands to read from standard input if it has not been redirected to a file.

console_write 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

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_handle 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_cursor_position CONOUTH

Returns the cursor position in a screen buffer as a list of two integers specifying the column and row that the cursor is to be positioned at. CONOUTH is the handle to the buffer and XY is a list of two integers.

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_location CONOUTH

Returns a list of four integers containing the left column position, the top row position, the right column position and the bottom row position of the window within the screen buffer.

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 TWAPI_WIN32 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.

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.

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.

This command requires a threaded build of Tcl and will raise an exception on non-threaded builds.

Only one Tcl interp should register a console control handler. Behaviour with multiple registrations is undefined.

set_console_cursor_position CONOUTH XY

Sets the cursor position in a screen buffer. CONOUTH is the handle to the buffer and XY 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_output_codepage CODEPAGE

Sets the output code page of the console.

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.

Console

SYNOPSIS

DESCRIPTION

Consoles