## Reference Manual

### Methods

Alloc
  Allocates a new console for the process. Returns undef on errors, 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.
  See also: Free
  Example:

       $CONSOLE->Alloc();

Attr [attr]
  Gets or sets the current console attribute. This attribute is used by the Write method.
  Example:

       $attr = $CONSOLE->Attr();
       $CONSOLE->Attr($FG_YELLOW | $BG_BLUE);

Close
  Closes a shortcut object. Note that it is not "strictly" required to close the objects you created, since the Win32::Shortcut objects are automatically closed when the program ends (or when you elsehow destroy such an object).
  Example:

       $LINK->Close();

Cls [attr]
  Clear the console, with the specified attr if given, or using ATTR_NORMAL otherwise.
  Example:

       $CONSOLE->Cls();
       $CONSOLE->Cls($FG_WHITE | $BG_GREEN);

Cursor [x, y, size, visible]
  Gets or sets cursor position and appearance. Returns undef on errors, or a 4-element list containing: x, y, size, visible. x and y are the current cursor position; ...
  Example:

       ($x, $y, $size, $visible) = $CONSOLE->Cursor();

       # Get position only
       ($x, $y) = $CONSOLE->Cursor();

       $CONSOLE->Cursor(40, 13, 50, 1);

       # Set position only
       $CONSOLE->Cursor(40, 13);

       # Set size and visibility without affecting position
       $CONSOLE->Cursor(-1, -1, 50, 1);

Display
  Displays the specified console on the screen. Returns undef on errors, a nonzero value on success.
  Example:

       $CONSOLE->Display();

FillAttr [attribute, number, col, row]
  Fills the specified number of consecutive attributes, beginning at col, row, with the value specified in attribute. Returns the number of attributes filled, or undef on errors.
  See also: FillChar.
  Example:

       $CONSOLE->FillAttr($FG_BLACK | $BG_BLACK, 80*25, 0, 0);

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 errors.
  See also: FillAttr.
  Example:

       $CONSOLE->FillChar("X", 80*25, 0, 0);

Flush
  Flushes the console input buffer. All the events in the buffer are discarded. Returns undef on errors, a nonzero value on success.
  Example:

       $CONSOLE->Flush();

Free
  Detaches the process from the console. Returns undef on errors, a nonzero value on success.
  See also: Alloc
  Example:

       $CONSOLE->Free();

GenerateCtrlEvent [type, processgroup]
  Sends a break signal of the specified type to the specified processgroup.
  type can be one of the following constants:

       CTRL_BREAK_EVENT
       CTRL_C_EVENT

  they signal, respectively, the pressing of Control + Break and of Control + C; if not specified, it 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 errors, a nonzero value on success.
  Example:

       # break this script now
       $CONSOLE->GenerateCtrlEvent();

GetEvents
  Returns the number of unread input events in the console's input buffer, or undef on errors.
  See also: Input, InputChar, PeekInput, WriteInput.
  Example:

       $events = $CONSOLE->GetEvents();

Info
  Returns an array of informations about the console (or undef on errors), which contains:
  - columns (X size) of the console buffer.
  - 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 the screen size.
  - maximum number of rows for the console window, given the current buffer size, font and the screen size.
  See also: Attr, Cursor, Size, Window, MaxWindow.
  Example:

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

Input
  Reads an event from the input buffer. Returns a list of values, which depending on the event's nature are:
  - a keyboard event, the list will contain:
    - event type: 1 for keyboard
    - key down: TRUE if the key is being pressed, FALSE if the key is being released
    - repeat count: the number of times the key is being held down
    - virtual keycode: the virtual key code of the key
    - virtual scancode: the virtual scan code of the key
    - char: the ASCII code of the character (if the key is a character key, 0 otherwise)
    - control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)
  - a mouse event:
    - event type: 2 for mouse
    - mouse pos. X: X coordinate (column) of the mouse location
    - mouse pos. Y: Y coordinate (row) of the mouse location
    - button state: the mouse button(s) which are pressed
    - control key state: the state of the control keys (SHIFTs, CTRLs, ALTs, etc.)
    - event flags: the type of the mouse event
  This method will return undef on errors.
  Note that the events returned are depending on the input Mode of the console; for example, mouse events are not intercepted unless `ENABLE_MOUSE_INPUT` is specified.

  See also: GetEvents, InputChar, Mode, PeekInput, WriteInput.
  Example:

       @event = $CONSOLE->Input();

InputChar number
  Reads and returns number characters from the console input buffer, or undef on errors.
  See also: Input, Mode.
  Example:

       $key = $CONSOLE->InputChar(1);

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.
  See also: OutputCP.
  Example:

       $codepage = $CONSOLE->InputCP();
       $CONSOLE->InputCP(437);

       # you may want to use the non-instanciated form to avoid confuzion :)
       $codepage = Win32::Console::InputCP();
       Win32::Console::InputCP(437);

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 errors, otherwise a 2-element list containing col, row.
  Example:

       ($maxCol, $maxRow) = $CONSOLE->MaxWindow();

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

  For more informations on the meaning of those flags, please refer to the Microsoft's Documentation.
  Example:

       $mode = $CONSOLE->Mode();
       $CONSOLE->Mode(ENABLE_MOUSE_INPUT | ENABLE_PROCESSED_INPUT);

MouseButtons
  Returns the number of the buttons on your mouse, or undef on errors.
  Example:

       print "Your mouse has ", $CONSOLE->MouseButtons(), " buttons.\n";

new Win32::Console standard_handle
new Win32::Console [accessmode, sharemode]
  Creates a new console object. The first form creates a handle to a standard channel, standard_handle can be one of the following:

       STD_OUTPUT_HANDLE
       STD_ERROR_HANDLE
       STD_INPUT_HANDLE

  The second form, instead, 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 one or both of the following values for accessmode:

       GENERIC_READ
       GENERIC_WRITE

  which are the permissions you will have on the created buffer, and one or both of the following values for sharemode:

       FILE_SHARE_READ
       FILE_SHARE_WRITE

  which affect the way the console can be shared. If you don't specify any of those parameters, all 4 flags will be used.
  Example:

       $STDOUT = new Win32::Console(STD_OUTPUT_HANDLE);
       $STDERR = new Win32::Console(STD_ERROR_HANDLE);
       $STDIN  = new Win32::Console(STD_INPUT_HANDLE);

       $BUFFER = new Win32::Console();
       $BUFFER = new Win32::Console(GENERIC_READ | GENERIC_WRITE);

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.
  See also: InputCP.
  Example:

       $codepage = $CONSOLE->OutputCP();
       $CONSOLE->OutputCP(437);

       # you may want to use the non-instanciated form to avoid confuzion :)
       $codepage = Win32::Console::OutputCP();
       Win32::Console::OutputCP(437);

PeekInput
  Does exactly the same as Input, except that the event read is not removed from the input buffer.
  See also: GetEvents, Input, InputChar, Mode, WriteInput.
  Example:

       @event = $CONSOLE->PeekInput();

ReadAttr [number, col, row]
  Reads the specified number of consecutive attributes, beginning at col, row, from the console. Returns the attributes read (a variable containing one character for each attribute), or undef on errors. You can then pass the returned variable to WriteAttr to restore the saved attributes on screen.
  See also: ReadChar, ReadRect.
  Example:

       $colors = $CONSOLE->ReadAttr(80*25, 0, 0);

ReadChar [number, col, row]
  Reads the specified number of consecutive characters, beginning at col, row, from the console. Returns a string containing the characters read, or undef on errors. You can then pass the returned variable to WriteChar to restore the saved characters on screen.
  See also: ReadAttr, ReadRect.
  Example:

       $chars = $CONSOLE->ReadChar(80*25, 0, 0);

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

       $rect = $CONSOLE->ReadRect(0, 0, 80, 25);

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 left, top, right, bottom, wile row, col identify 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, cbottom, so that the content of the console outside this rectangle are unchanged. Returns undef on errors, a nonzero value on success.
  Example:

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

Select standard_handle
  Redirects a standard handle to the specified console. standard_handle can have one of the following values:

       STD_INPUT_HANDLE
       STD_OUTPUT_HANDLE
       STD_ERROR_HANDLE

  Returns undef on errors, a nonzero value on success.
  Example:

       $CONSOLE->Select(STD_OUTPUT_HANDLE);

Size [col, row]
  Gets or sets the console buffer size.
  Example:

       ($x, $y) = $CONSOLE->Size();
       $CONSOLE->Size(80, 25);

Title [title]
  Gets or sets the title bar the string of the current console window.
  Example:

       $title = $CONSOLE->Title();
       $CONSOLE->Title("This is a title");

Window [flag, left, top, right, bottom]
  Gets or sets the current console window size. If called without arguments, returns a 4-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 (zero), coordinates are considered relative to the current coordinates; if it is non-zero, coordinates are absolute.
  Example:

       ($left, $top, $right, $bottom) = $CONSOLE->Window();
       $CONSOLE->Window(1, 0, 0, 80, 50);

Write string
  Writes string on the console, using the current attribute, that you can set with Attr, and advancing the cursor as needed. This isn't so different from Perl's "print" statement. Returns the number of characters written or undef on errors.
  See also: WriteAttr, WriteChar, WriteRect.
  Example:

       $CONSOLE->Write("Hello, world!");

WriteAttr attrs, col, row
  Writes the attributes 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 errors.
  See also: Write, WriteChar, WriteRect.
  Example:

       $CONSOLE->WriteAttr($attrs, 0, 0);

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

WriteChar chars, col, row
  Writes the characters in the string attr, beginning at col, row, without affecting the attributes that are on screen. The string chars can be the result of a ReadChar function, or a normal string. Returns the number of characters written or undef on errors.
  See also: Write, WriteAttr, WriteRect.
  Example:

       $CONSOLE->WriteChar("Hello, worlds!", 0, 0);

WriteInput (event)
  Pushes data in the console input buffer. (event) is a list of values, for more information see Input. The string chars can be the result of a ReadChar function, or a normal string. Returns the number of characters written or undef on errors.
  See also: Write, WriteAttr, WriteRect.
  Example:

       $CONSOLE->WriteInput(@event);

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, bottom. rect can be the result of a ReadRect function. Returns undef on errors, otherwise a 4-element list containing the coordinates of the affected rectangle, in the format left, top, right, bottom.
  See also: Write, WriteAttr, WriteChar.
  Example:

       $CONSOLE->WriteRect($rect, 0, 0, 80, 25);

### 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).

### Microsoft's Documentation

Documentation for the Win32 Console and Character mode Functions can be found on Microsoft's site at this URL:
http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar.htm

A reference of the available functions is at:
http://www.microsoft.com/msdn/sdk/platforms/doc/sdk/win32/sys/src/conchar_34.htm

07 Apr 1997, Aldo Calpini <dada@divinf.it>