win32console 1.2.0-x86-mingw32

data/doc/Console.rdoc

@@ -0,0 +1,690 @@
+#
+#  = NAME
+#
+#  Win32::Console - Win32 Console and Character Mode Functions
+#
+#
+#  = DESCRIPTION
+#
+#  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)
+#
+#    - reading and writing of characters, attributes and whole portions of
+#      the screen
+#
+#    - complete processing of keyboard and mouse events
+#
+#    - some very funny additional features :)
+#
+#
+#  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.
+#
+#
+#  = REFERENCE
+#
+#
+#  == Methods
+#
+#  - Alloc
+#
+#    Allocates a new console for the process.  Returns C<nil> 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: C<Free>
+#
+#    Example:
+#
+#      Win32::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 I<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 C<nil> on
+#    errors, or a 4-element list containing: I<x>, I<y>, I<size>,
+#    I<visible>.  I<x> and I<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 C<nil> on errors,
+#    a nonzero value on success.
+#
+#    Example:
+#
+#      console.Display()
+#
+#  - FillAttr [attribute, number, col, row]
+#
+#    Fills the specified number of consecutive attributes, beginning at
+#    I<col>, I<row>, with the value specified in I<attribute>.  Returns the
+#    number of attributes filled, or C<nil> on errors.  See also:
+#    C<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
+#    I<col>, I<row>, with the character specified in I<char>.  Returns the
+#    number of characters filled, or C<nil> on errors.  See also:
+#    C<FillAttr>.
+#
+#    Example:
+#
+#      console.FillChar("X", 80*25, 0, 0)
+#
+#  - Flush
+#
+#    Flushes the console input buffer.  All the events in the buffer are
+#    discarded.  Returns C<nil> on errors, a nonzero value on success.
+#
+#    Example:
+#
+#     console.Flush()
+#
+#  - Free
+#
+#    Detaches the process from the console.  Returns C<nil> on errors, a
+#    nonzero value on success.  See also: C<Alloc>.
+#
+#    Example:
+#
+#      Win32::Console::Free()
+#
+#  - GenerateCtrlEvent [type, processgroup]
+#
+#    Sends a break signal of the specified I<type> to the specified
+#    I<processgroup>.  I<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.
+#    I<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
+#    C<nil> on errors, a nonzero value on success.
+#
+#    Example:
+#
+#      # break this script now
+#      Win32::Console::GenerateCtrlEvent()
+#
+#  - GetEvents
+#
+#    Returns the number of unread input events in the console's input
+#    buffer, or C<nil> on errors.  See also: C<Input>, C<InputChar>,
+#    C<PeekInput>, C<WriteInput>.
+#
+#    Example:
+#
+#      events = console.GetEvents()
+#
+#  - Info
+#
+#    Returns an array of informations about the console (or C<nil> 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 C<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: <b>Attr</b>, <b>Cursor</b>, <b>Size</b>, <b>Window</b>, <b>MaxWindow</b>.
+#
+#    Example:
+#
+#      info = console.Info()
+#      puts "Cursor at #{info[3]}, #{info[4]}."
+#
+#  - Input
+#
+#    Reads an event from the input buffer.  Returns an array of values, which
+#    depending on the event's nature are:
+#
+#    - keyboard event
+#
+#       The array 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 array 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 <b>nil</b> on errors.  Note that the events
+#    returned are depending on the input <b>Mode</b> of the console; for example,
+#    mouse events are not intercepted unless ENABLE_MOUSE_INPUT is
+#    specified.  See also: <b>GetEvents</b>, <b>InputChar</b>, <b>Mode</b>,
+#    <b>PeekInput</b>, <b>WriteInput</b>.
+#
+#    Example:
+#
+#      event = console.Input()
+#
+#  - InputChar number
+#
+#    Reads and returns I<number> characters from the console input buffer,
+#    or <b>nil</b> on errors.  See also: <b>Input</b>, <b>Mode</b>.
+#
+#    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:
+#    <b>OutputCP</b>.
+#
+#    Example:
+#
+#      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 <b>nil</b> 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.  I<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 L<"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 <b>nil</b> on errors.
+#
+#    Example:
+#
+#      puts "Your mouse has #{Win32::Console::MouseButtons()} buttons."
+#
+#  - Win32::Console.new standard_handle
+#
+#  - Win32::Console.new [accessmode, sharemode]
+#
+#    Creates a new console object.  The first form creates a handle to a
+#    standard channel, I<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 <b>Display</b>.  In
+#    this case, you can specify one or both of the following values for
+#    I<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 I<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 = Win32::Console.new(STD_OUTPUT_HANDLE)
+#      stderr = Win32::Console.new(STD_ERROR_HANDLE)
+#      stdin  = Win32::Console.new(STD_INPUT_HANDLE)
+#
+#      buffer = Win32::Console.new()
+#      buffer = Win32::Console.new(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: <b>InputCP</b>.
+#
+#    Example:
+#
+#      codepage = Win32::Console::OutputCP()
+#      Win32::Console::OutputCP(437)
+#
+#  - PeekInput
+#
+#    Does exactly the same as <b>Input</b>, except that the event read is not
+#    removed from the input buffer.  See also: <b>GetEvents</b>, <b>Input</b>,
+#    <b>InputChar</b>, <b>Mode</b>, <b>WriteInput</b>.
+#
+#    Example:
+#
+#      event = console.PeekInput()
+#
+#  - ReadAttr [number, col, row]
+#
+#    Reads the specified I<number> of consecutive attributes, beginning at
+#    I<col>, I<row>, from the console.  Returns the attributes read (a
+#    variable containing one character for each attribute), or <b>nil</b> on
+#    errors.  You can then pass the returned variable to <b>WriteAttr</b> to
+#    restore the saved attributes on screen.  See also: <b>ReadChar</b>,
+#    <b>ReadRect</b>.
+#
+#    Example:
+#
+#      colors = console.ReadAttr(80*25, 0, 0)
+#
+#  - ReadChar [number, col, row]
+#
+#    Reads the specified I<number> of consecutive characters, beginning at
+#    I<col>, I<row>, from the console.  Returns a string containing the
+#    characters read, or <b>nil</b> on errors.  You can then pass the
+#    returned variable to <b>WriteChar</b> to restore the saved characters on
+#    screen.  See also: <b>ReadAttr</b>, <b>ReadRect</b>.
+#
+#    Example:
+#
+#      chars = console.ReadChar(80*25, 0, 0)
+#
+#  - ReadRect left, top, right, bottom
+#
+#    Reads the content (characters and attributes) of the rectangle
+#    specified by I<left>, I<top>, I<right>, I<bottom> from the console.
+#    Returns a string containing the rectangle read, or <b>nil</b> on errors.
+#    You can then pass the returned variable to <b>WriteRect</b> to restore the
+#    saved rectangle on screen (or on another console).  See also:
+#    <b>ReadAttr</b>, <b>ReadChar</b>.
+#
+#    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
+#    I<left>, I<top>, I<right>, I<bottom>, while I<row>, I<col> identify
+#    the new location of the block.  The cells left empty as a result of
+#    the move are filled with the character I<char> and attribute I<attr>.
+#    Optionally you can specify a clipping region with I<cleft>, I<ctop>,
+#    I<cright>, I<cbottom>, so that the content of the console outside this
+#    rectangle are unchanged.  Returns <b>nil</b> 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.
+#    I<standard_handle> can have one of the following values:
+#
+#      STD_INPUT_HANDLE
+#      STD_OUTPUT_HANDLE
+#      STD_ERROR_HANDLE
+#
+#    Returns <b>nil</b> 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 I<left>, I<top>, I<right>, I<bottom>.  To
+#    set the window size, you have to specify an additional I<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 I<string> on the console, using the current attribute, that you
+#    can set with <b>Attr</b>, and advancing the cursor as needed.  This isn't
+#    so different from Perl's "print" statement.  Returns the number of
+#    characters written or <b>nil</b> on errors.  See also: <b>WriteAttr</b>,
+#    <b>WriteChar</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.Write("Hello, world!")
+#
+#  - WriteAttr attrs, col, row
+#
+#    Writes the attributes in the string I<attrs>, beginning at I<col>,
+#    I<row>, without affecting the characters that are on screen.  The
+#    string attrs can be the result of a <b>ReadAttr</b> 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 <b>nil</b> on errors.  See
+#    also: <b>Write</b>, <b>WriteChar</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteAttr($attrs, 0, 0)
+#
+#      # note the use of chr()...
+#      attrs = (FG_BLACK | BG_WHITE).chr() * 80
+#      console.WriteAttr(attrs, 0, 0)
+#
+#  - WriteChar chars, col, row
+#
+#    Writes the characters in the string <i>attr</i>, beginning at <i>col</i>, <i>row</i>,
+#    without affecting the attributes that are on screen.  The string <i>chars</i>
+#    can be the result of a <b>ReadChar</b> function, or a normal string.  Returns
+#    the number of characters written or <b>nil</b> on errors.  See also:
+#    <b>Write</b>, <b>WriteAttr</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteChar("Hello, worlds!", 0, 0)
+#
+#  - WriteInput (event)
+#
+#    Pushes data in the console input buffer.  I<(event)> is a list of values,
+#    for more information see <b>Input</b>.  The string chars can be the result of
+#    a <b>ReadChar</b> function, or a normal string.  Returns the number of
+#    characters written or <b>nil</b> on errors.  See also: <b>Write</b>,
+#    <b>WriteAttr</b>, <b>WriteRect</b>.
+#
+#    Example:
+#
+#      console.WriteInput(event)
+#
+#  - WriteRect rect, left, top, right, bottom
+#
+#    Writes a rectangle of characters and attributes (contained in <i>rect</i>)
+#    on the console at the coordinates specified by <i>left</i>, <i>top</i>,
+#    <i>right</i>, <i>bottom</i>.  <i>rect</i> can be the result of a <b>ReadRect</b>
+#    function.  Returns <b>nil</b> on errors, otherwise a 4-element list
+#    containing the coordinates of the affected rectangle, in the format
+#    <i>left</i>, <i>top</i>, <i>right</i>, <i>bottom</i>.  See also: <b>Write</b>,
+#    <b>WriteAttr</b>, <b>WriteChar</b>.
+#
+#    Example:
+#
+#      console.WriteRect(rect, 0, 0, 80, 25)
+#
+#
+#  == Constants
+#
+#  The following constants are defined in the namespace of 
+#  Win32::Console::Constants and are brought into the current
+#  namespace when the module is required:
+#
+#      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, these other constants are also added to your current
+#  namespace when requiring the module:
+#
+#      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
+#
+#
+#  = VERSION HISTORY
+#
+#   * 0.031 (24 Sep 1999)
+#
+#     * Fixed typo in GenerateCtrlEvent().
+#
+#     * Converted and added pod documentation (from Jan Dubois <jand@activestate.com>).
+#
+#   * 0.03 (07 Apr 1997)
+#
+#     * Added "GenerateCtrlEvent" method.
+#
+#     * The PLL file now comes in 2 versions, one for Perl version 5.001
+#       (build 110) and one for Perl version 5.003 (build 300 and higher,
+#       EXCEPT 304).
+#
+#     * added an installation program that will automatically copy the right
+#       version in the right place.
+#
+#  * 0.01 (09 Feb 1997)
+#
+#      * First public release.
+#
+#  = AUTHORS
+#
+#  Aldo Calpini <a.calpini@romagiubileo.it> Perl module
+#
+#  Gonzalo Garramu�o <GGarramuno@aol.com>   Ruby Port
+#
+#  = CREDITS
+#
+#  Thanks to: Jesse Dougherty, Dave Roth, ActiveWare, and the
+#  Perl-Win32-Users community.
+#
+#
+#  = DISCLAIMER
+#
+#  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.
+#