Those functions should also make possible a port of the Unix's curses
library; if there is anyone interested (and/or willing to contribute)
to this project, e-mail me. Thank you.
- 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:
-
- 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.)
-
- mouse event
-
The list will contain:
-
- *
-
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, while 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);