Commands related to Windows consoles
package require twapi
This module provides commands for manipulating console windows.
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.
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.
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.
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.
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. |
-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. |
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. |
-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). |
-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. |
-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. |
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_input_mode stdin -echoinput 0 -lineinput 1will 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 1will turn off -echoinput mode, turn on -lineinput mode but will leave others unchanged.
set_console_output_mode stdout -processedoutput 0will set the console output to only have mode -processedoutput set. On the other hand,
modify_console_output_mode stdout -processedoutput 0will turn off -processedoutput mode but leave others unchanged.
-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 © 2004-2006 Ashok P. Nadkarni