Win32::Console - Win32 Console and Character Mode Functions |
Win32::Console - Win32 Console and Character Mode Functions
This module implements the Win32 console and character mode functions. They give you full control on the console input and output, including: support of off-screen console buffers (eg. multiple screen pages)
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.
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();
Example:
$attr = $CONSOLE->Attr(); $CONSOLE->Attr($FG_YELLOW | $BG_BLUE);
Example:
$LINK->Close();
Example:
$CONSOLE->Cls(); $CONSOLE->Cls($FG_WHITE | $BG_GREEN);
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);
undef
on errors,
a nonzero value on success.
Example:
$CONSOLE->Display();
undef
on errors. See also:
FillChar
.
Example:
$CONSOLE->FillAttr($FG_BLACK | $BG_BLACK, 80*25, 0, 0);
undef
on errors. See also:
FillAttr
.
Example:
$CONSOLE->FillChar("X", 80*25, 0, 0);
undef
on errors, a nonzero value on success.
Example:
$CONSOLE->Flush();
undef
on errors, a
nonzero value on success. See also: Alloc
.
Example:
$CONSOLE->Free();
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();
undef
on errors. See also: Input
, InputChar
,
PeekInput
, WriteInput
.
Example:
$events = $CONSOLE->GetEvents();
undef
on
errors), which contains:
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";
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();
undef
on errors. See also: Input
, Mode
.
Example:
$key = $CONSOLE->InputChar(1);
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);
undef
on
errors, otherwise a 2-element list containing col, row.
Example:
($maxCol, $maxRow) = $CONSOLE->MaxWindow();
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);
undef
on errors.
Example:
print "Your mouse has ", $CONSOLE->MouseButtons(), " buttons.\n";
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);
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);
Input
, except that the event read is not
removed from the input buffer. See also: GetEvents
, Input
,
InputChar
, Mode
, WriteInput
.
Example:
@event = $CONSOLE->PeekInput();
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);
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);
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);
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);
STD_INPUT_HANDLE STD_OUTPUT_HANDLE STD_ERROR_HANDLE
Returns undef
on errors, a nonzero value on success.
Example:
$CONSOLE->Select(STD_OUTPUT_HANDLE);
Example:
($x, $y) = $CONSOLE->Size(); $CONSOLE->Size(80, 25);
Example:
$title = $CONSOLE->Title(); $CONSOLE->Title("This is a title");
Example:
($left, $top, $right, $bottom) = $CONSOLE->Window(); $CONSOLE->Window(1, 0, 0, 80, 50);
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!");
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);
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);
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);
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);
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).
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
Aldo Calpini <a.calpini@romagiubileo.it>
Thanks to: Jesse Dougherty, Dave Roth, ActiveWare, and the Perl-Win32-Users community.
This program is FREE; you can redistribute, modify, disassemble, or even reverse engineer this software at your will. Keep in mind, however, that NOTHING IS GUARANTEED to work and everything you do is AT YOUR OWN RISK - I will not take responsibility for any damage, loss of money and/or health that may arise from the use of this program!
This is distributed under the terms of Larry Wall's Artistic License.
Win32::Console - Win32 Console and Character Mode Functions |