Commands related to Windows consoles
|clear_console CONOUTH ?-fillchar CHARACTER? ?-windowonly BOOL?|
|console_read CONINH ?options?|
|console_read_input_records CONINH ?-peek? ?-count COUNT?|
|console_write CONOUTH STRING ?options?|
|fill_console CONOUTH ?options?|
|generate_console_control_event EVENT ?PROCESSGROUP?|
|get_console_screen_buffer_info CONH ?options?|
|modify_console_input_mode CONINH MODEOPTIONS...|
|modify_console_output_mode CONOUTH MODEOPTIONS...|
|set_console_cursor_position CONOUTH XY|
|set_console_default_attr CONOUTH ?options?|
|set_console_screen_buffer_size CONOUTH SCRSIZE|
|set_console_window_location CONOUTH RECT ?-absolute BOOL?|
|set_standard_handle TYPE HANDLE|
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 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 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 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.
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.|
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.
|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:
|menu||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
|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.|
|-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.|
|-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.|
Copyright © 2004-2014 Ashok P. Nadkarni