clio 0.0.1 → 0.2.0

data/vendor/Console/Console.rdoc

@@ -1,690 +0,0 @@
-#
-#  = 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.
-#