Win32::Console (Perl in a Nutshell, 2nd Edition)

22.2. Win32::Console

Win32::Console implements the Win32 console and character mode functions. They give you full control on the console input and output, including support of offscreen console buffers (e.g., multiple screen pages); reading and writing of characters, attributes, and whole portions of the screen; and complete processing of keyboard and mouse events.

The new constructor is used to create a console object. It can take two forms:

$con = Win32::Console->new(standard_handle); 
$con = Win32::Console->new(accessmode, sharemode);

The first form creates a handle to a standard channel. standard_handle can be one of STD_OUTPUT_HANDLE, STD_ERROR_HANDLE, or STD_INPUT_HANDLE.

The second form creates a console screen buffer in memory, which you can access for reading and writing as a normal console, and then redirect on the standard output (the screen) with Display. In this case, you can specify accessmode to be GENERIC_READ, GENERIC_WRITE, or both, determining the permissions you will have on the created buffer.

sharemode affects how the console can be shared. It can be specified as either FILE_SHARE_READ, FILE_SHARE_WRITE, or both. If you don't specify any of those parameters, all four flags will be used.

The following methods are supported by the Win32::Console module.

Alloc

$cons->Alloc

Allocates a new console for the process. Returns undef on error or a nonzero value on success. A process cannot be associated with more than one console, so this method will fail if there is already an allocated console. Use Free to detach the process from the console, and then call Alloc to create a new console.

Attr

$cons->Attr([attr])

Gets or sets the current console attribute. This attribute is used by the Write method.

Cls

$cons->Cls([attr])

Clears the console with the specified attr, if given. Uses ATTR_NORMAL otherwise.

Cursor

$cons->Cursor([x, y, size, visible])

Gets or sets cursor position and appearance. Returns undef on error, or a four-element list containing x, y, size, and visible. x and y give the current cursor position.

Display

$cons->Display

Displays the specified console on the screen. Returns undef on error or a nonzero value on success.

FillAttr

$cons->FillAttr([value, number, col, row])

Fills the specified number of consecutive attributes, beginning at col, row, with the value specified. Returns the number of attributes filled, or undef on error.

FillChar

$cons->FillChar(char, number, col, row)

Fills the specified number of consecutive characters, beginning at col, row, with the character specified in char. Returns the number of characters filled, or undef on error.

Flush

$cons->Flush

Flushes the console input buffer. All the events in the buffer are discarded. Returns undef on error, a nonzero value on success.

Free

$cons->Free

Detaches the process from the console. Returns undef on error, a nonzero value on success.

GenerateCtrlEvent

$cons->GenerateCtrlEvent([type, processgroup])

Sends a break signal of the specified type to the specified process group. type can be one of CTRL_BREAK_EVENT or CTRL_C_EVENT, signaling, respectively, the pressing of Ctrl + Break and Ctrl-C. If not specified, type defaults to CTRL_C_EVENT. processgroup is the PID of a process sharing the same console. If omitted, it defaults to 0 (the current process), which is also the only meaningful value that you can pass to this function. Returns undef on error, a nonzero value on success.

GetEvents

$cons->GetEvents

Returns the number of unread input events in the console's input buffer, or undef on error.

Info

$cons->Info

Returns an array of information about the console, which contains:

Number of columns (X size) of the console buffer
Number of rows (Y size) of the console buffer
Current column (X position) of the cursor
Current row (Y position) of the cursor
Current attribute used for Write
Left column (X of the starting point) of the current console window
Top row (Y of the starting point) of the current console window
Right column (X of the final point) of the current console window
Bottom row (Y of the final point) of the current console window
Maximum number of columns for the console window, given the current buffer size, font, and screen size
Maximum number of rows for the console window, given the current buffer size, font, and screen size

This example prints the cursor's current position:

@info = $CONSOLE->Info( );
print "Cursor at $info[3], $info[4].0";

Input

$cons->Input

Reads an event from the input buffer. Returns a list of values, determined by the type of event. A keyboard event will contain the following values, in order:

Event type (1 for keyboard)
Key state—true if the key is being pressed, false if the key is being released
Repeat count—the number of times the key is held down
Virtual keycode of the key
Virtual scancode of the key
ASCII code of the character (if the key is a character key, 0 otherwise)
State of the control keys (Shifts, Ctrls, Alts, etc.)

A mouse event will return the following values, in order:

Event type (2 for mouse)
X coordinate (column) of the mouse location
Y coordinate (row) of the mouse location
Button state—the mouse button(s) that are pressed
State of the control keys (Shifts, Ctrls, Alts, etc.)
Event flags for the type of the mouse event

This method will return undef on error.

Note that the events returned depend on the input mode of the console; for example, mouse events are not intercepted unless ENABLE_MOUSE_INPUT is specified.

InputChar

$cons->InputChar(number)

Reads and returns number characters from the console input buffer, or returns undef on error.

InputCP

$cons->InputCP([codepage])

Gets or sets the input code page used by the console. Note that this doesn't apply to a console object, but to the standard input console. This attribute is used by the Write method.

MaxWindow

$cons->MaxWindow

Returns the size of the largest possible console window, based on the current font and the size of the display. The result is undef on error; otherwise, a two-element list containing the number of columns and rows is returned.

Mode

$cons->Mode([flags])

Gets or sets the input or output mode of a console. flags can be a combination of the following constants:

ENABLE_LINE_INPUT
ENABLE_ECHO_INPUT
ENABLE_PROCESSED_INPUT
ENABLE_WINDOW_INPUT
ENABLE_MOUSE_INPUT
ENABLE_PROCESSED_OUTPUT
ENABLE_WRAP_AT_EOL_OUTPUT

MouseButtons

$cons->MouseButtons

Returns the number of the buttons on your mouse, or undef on error.

OutputCP

$cons->OutputCP([codepage])

Gets or sets the output code page used by the console. Note that this doesn't apply to a console object, but to the standard output console. You may want to use the noninstantiated form to avoid confusion:

$codepage = Win32::Console::OutputCP( );
Win32::Console::OutputCP(437);

PeekInput

$cons->PeekInput

Does exactly the same as Input, except that the event read is not removed from the input buffer.

ReadAttr

$cons->ReadAttr([number, col, row])

Reads the specified number of consecutive attributes from the console, beginning at col, row. Returns the attributes read (a variable containing one character for each attribute), or undef on error. You can then pass the returned variable to WriteAttr to restore the saved attributes on screen.

ReadChar

$cons->ReadChar([number, col, row])

Reads the specified number of consecutive characters from the console, beginning at col, row. Returns a string containing the characters read, or undef on error. You can then pass the returned variable to WriteChar to restore the saved characters on screen.

ReadRect

$cons->ReadRect(left, top, right, bottom)

Reads the content (characters and attributes) of the rectangle specified by left, top, right, and bottom from the console. Returns a string containing the rectangle read, or undef on error. You can then pass the returned variable to WriteRect to restore the saved rectangle on screen (or on another console).

Scroll

$cons->Scroll(left, top, right, bottom, col, row, char, attr, [cleft, ctop, cright, cbottom])

Moves a block of data in a console buffer; the block is identified by the left, top, right, and bottom positions.

row and colidentify the new location of the block. The cells left empty as a result of the move are filled with the character char and attribute attr.

Optionally, you can specify a clipping region with cleft, ctop, cright, and cbottom so that the contents of the console outside this rectangle are unchanged. Returns undef on error or a nonzero value on success.

# Scrolls the screen 10 lines down, filling with black spaces
$CONSOLE->Scroll(0, 0, 80, 25, 0, 10, " ", $FG_BLACK | $BG_BLACK);

Select

$cons->Select(standard_handle)

Redirects a standard handle to the specified console. standard_handlecan have one of the following values:

STD_INPUT_HANDLE
STD_OUTPUT_HANDLE
STD_ERROR_HANDLE

Returns undef on error or a nonzero value on success.

Size

$cons->Size([col, row])

Gets or sets the console buffer size.

Title

$cons->Title([title])

Gets or sets the title bar string of the current console window.

Window

$cons->Window([flag, left, top, right, bottom])

Gets or sets the current console window size. If called without arguments, returns a four-element list containing the current window coordinates in the form of (left, top, right, bottom). To set the window size, you have to specify an additional flag parameter. If it is 0, coordinates are considered relative to the current coordinates; if it is nonzero, coordinates are absolute.

Write

$cons->Write(string)

Writes stringon the console, using the current attribute, which you can set with Attr, and advances the cursor as needed. This isn't that different from Perl's print statement. Returns the number of characters written, or undef on error.

WriteAttr

$cons->WriteAttr(attrs, col, row)

Writes the attributes contained in the string <attrs>, beginning at col, row, without affecting the characters that are on screen. The string attrs can be the result of a ReadAttr function, or you can build your own attribute string; in this case, keep in mind that every attribute is treated as a character, not a number (see example). Returns the number of attributes written, or undef on error.

$CONSOLE->WriteAttr($attrs, 0, 0);
# note the use of chr( )...
$attrs = chr($FG_BLACK | $BG_WHITE) x 80; 
$CONSOLE->WriteAttr($attrs, 0, 0);

WriteChar

$cons->WriteChar(chars, col, row)

Writes the characters in the string attr, beginning at col, row, without affecting the attributes that are onscreen. The string characters can be the result of a ReadChar function or a normal string. Returns the number of characters written, or undef on error.

WriteInput

$cons->WriteInput(event)

Pushes data in the console input buffer. event is a list of values (for more information, see Input). The string characters can be the result of a ReadChar function or a normal string. Returns the number of characters written, or undef on error.

WriteRect

$cons->WriteRect(rect, left, top, right, bottom)

Writes a rectangle of characters and attributes (contained in rect) on the console at the coordinates specified by left, top, right, and bottom. rectcan be the result of a ReadRect function. Returns undef on error; otherwise, returns a four-element list containing the coordinates of the affected rectangle, in the format (left, top, right, bottom).

22.2.1. Constants

The following constants are exported in the main namespace of your script using Win32::Console:

BACKGROUND_BLUE                 BACKGROUND_GREEN
BACKGROUND_INTENSITY            BACKGROUND_RED
CAPSLOCK_ON                     CONSOLE_TEXTMODE_BUFFER    
ENABLE_ECHO_INPUT               ENABLE_LINE_INPUT
ENABLE_MOUSE_INPUT              ENABLE_PROCESSED_INPUT
ENABLE_PROCESSED_OUTPUT         ENABLE_WINDOW_INPUT
ENABLE_WRAP_AT_EOL_OUTPUT       ENHANCED_KEY
FILE_SHARE_READ                 FILE_SHARE_WRITE
FOREGROUND_BLUE                 FOREGROUND_GREEN
FOREGROUND_INTENSITY            FOREGROUND_RED
LEFT_ALT_PRESSED                LEFT_CTRL_PRESSED
NUMLOCK_ON                      GENERIC_READ
GENERIC_WRITE                   RIGHT_ALT_PRESSED
RIGHT_CTRL_PRESSED              SCROLLLOCK_ON
SHIFT_PRESSED                   STD_INPUT_HANDLE
STD_OUTPUT_HANDLE               STD_ERROR_HANDLE

Additionally, the following variables can be used:

$FG_BLACK                       $FG_BLUE
$FG_LIGHTBLUE                   $FG_RED
$FG_LIGHTRED                    $FG_GREEN
$FG_LIGHTGREEN                  $FG_MAGENTA
$FG_LIGHTMAGENTA                $FG_CYAN
$FG_LIGHTCYAN                   $FG_BROWN
$FG_YELLOW                      $FG_GRAY
$FG_WHITE                       $BG_BLACK
$BG_BLUE                        $BG_LIGHTBLUE
$BG_RED                         $BG_LIGHTRED
$BG_GREEN                       $BG_LIGHTGREEN
$BG_MAGENTA                     $BG_LIGHTMAGENTA
$BG_CYAN                        $BG_LIGHTCYAN
$BG_BROWN                       $BG_YELLOW
$BG_GRAY                        $BG_WHITE
$ATTR_NORMAL                    $ATTR_INVERSE

ATTR_NORMAL is set to gray foreground on black background (DOS's standard colors).