 2AFBQB7 - Curses::Simp created by Pip@CPAN.Org to vastly simplify Perl
   text-mode application development
 Notz: Curses color names:
   COLOR_ BLACK,RED,GREEN,YELLOW,BLUE,MAGENTA,CYAN,WHITE 

NAME

Curses::Simp - a Simple Curses wrapper for easy application development

VERSION

This documentation refers to version 1.0.41V0L3a of 
Curses::Simp, which was released on Sat Jan 31 00:21:03:36 2004.

SYNOPSIS

  use Curses::Simp;
  my $simp = Curses::Simp->new('text' => ['1337', 'nachoz', 'w/',
                                     'cheese' x 7]);
  my $key = '';
  while($key ne 'x') {           # wait for 'x' to eXit
    $key = $simp->GetKey(-1);    # get a blocking keypress
    $simp->Text('push' => $key); # push new line for new key
  }

DESCRIPTION

Curses::Simp provides a curt mechanism for updating a console screen 
with any Perl array (or two to include color codes).  Most key strokes
can be simply obtained and tested for interface manipulation.  The goal
was ease-of-use first and efficient rendering second.  Of course, it 
could always benefit from being faster still.  Many Simp functions 
can accept rather cryptic parameters to do fancier things but the most
common case is meant to be as simple as possible (hence the name).
The more I learn about Curses, the more functionality I intend to add...
Feeping Creatures overcome.

2DO

- add styles && style/blockchar increment keys to CPik

- mk generic file/dir browse dialog window function: Brws

- add loop && scal flags w/ togl keys to CPik

- describe Simp objects sharing apps (pmix + ptok)
          mk OScr read Simp apps @_ param list && auto-handle --geom wxh+x+y

- add multi-line option to Prnt where text can split on /\n/

- add multi-line option to Prmt where dtxt can split on /\n/ && ^d
          accepts entry instead of RETURN

- handle ascii chars under 32 with escapes from Prnt

- optimize Draw more

- imp up/dn scrollbars either internally or w/ normal Curses funcs

- handle ascii chars under 32 better than current escapes if possible

        if detectable:

- handle xterm resize events

- handle mouse input (study any existent Curses apps that use mouse 
          input you can find ... probably in C)

- Learn how to read a Shift-Tab key press if in any way 
          distinguishable from Tab/Ctrl-I

-    What else does Simp need?

WHY?

Curses::Simp was created because I could hardly find dox or examples 
of Curses.pm usage so I fiddled until I could wrap the most important
stuff (AFAIC) in names and enhanced functions which streamline what I
want to do.

USAGE

B<new()> - Curses::Simp object constructor

new() opens a new Curses screen if one does not exist already and 
initializes useful default screen, color, and keys settings.  The
created Curses screen is automagically closed on program exit.

Available object methods are described in detail below.  Each of
the following four letter abbreviated or verbose method names
can be used as initialization parameters to new():

   Key       or  VerboseName                =>   Default Value
  -----         -------------                   ---------------
  'text'     or 'TextData'                  =>        [ ]
  'colr'     or 'ColorData'                 =>        [ ]
  'hite'     or 'WindowHeight'              =>         0
  'widt'     or 'WindowWidth'               =>         0
  'yoff'     or 'WindowYOffset'             =>         0
  'xoff'     or 'WindowXOffset'             =>         0
  'ycrs'     or 'CursorYOffset'             =>         0
  'xcrs'     or 'CursorXOffset'             =>         0
  'btyp'     or 'WindowBorderType'          =>         0
  'bclr'     or 'WindowBorderColor'         =>        '!w'
  'titl'     or 'WindowTitle'               =>         ''
  'tclr'     or 'WindowTitleColor'          =>        '!W'
  'dndx'     or 'DisplayStackIndex'         =>         0
  'flagaudr' or 'FlagAutoDraw'              =>         1
  'flagmaxi' or 'FlagMaximize'              =>         1
  'flagshrk' or 'FlagShrinkToFit'           =>         1
  'flagcntr' or 'FlagCenter'                =>         1
  'flagcvis' or 'FlagCursorVisible'         =>         0
  'flagscrl' or 'FlagScrollbar'             =>         0
  'flagsdlk' or 'FlagSDLKey'                =>         0
  'flagbkgr' or 'FlagBackground'            =>         0
  'flagfram' or 'FlagTimeFrame'             =>         0
  'flagmili' or 'FlagMillisecond'           =>         0
  'flagprin' or 'FlagPrintInto'             =>         1

An example of setting and updating 'WindowHeight':

  use Curses::Simp; 
  my $simp = Curses::Simp->new( 'WindowHeight' => 7 ); # set
     $simp->WindowHeight( 15 ); # update

See the individual sections in the L<"ACCESSOR AND FLAG METHODS"> 
section for more information on how to manipulate created 
Curses::Simp objects.

Most other Curses::Simp methods also accept hash key => value pairs as
parameters which loads the object fields the same way new() does
before performing their operation.  This gives you the ability to
update many Simp fields with a call to any particular 
accessor method.  The method name just designates where the lone
value will be assigned and which field will be returned.

ExpandCC or ExpandColorCodeString( $CompressedColorCodeString )

Returns the expanded form of the compressed color code string 
$CompressedColorCodeString.

$CompressedColorCodeString may contain any of the special formatting 
characters specified in the L<"COLOR NOTES"> 
(L<"Interpretation of Backgrounds and Repeats in Color Codes">) section.

ExpandColorCodeString() is primarily useful as an internal function
to the Curses::Simp package but I have exposed it because it can
be useful to test and see how a compressed color code string would
be expanded especially if expansion from PrintString() or DrawWindow()
is not what you're expecting.

ShokScrn or ShockScreen( [$FlagClear] )

ShockScreen() forces the screen and all created Simp objects
to be refreshed in order.

The $FlagClear (default is false) can be provided to specify that
the entire screen is to be cleared before everything refreshes.
Clearing the entire screen usually isn't necessary.

KNum or KeyNumbers()

Returns a hash with key    numbers  => "names".

CLet or ColorLetters()

Returns a hash with color "letters" => numbers.

NumC or NumColors()

Returns the number of available colors 
(last index: NumC() - 1)

Hite or Height

Returns the current Simp object's window height 
(last index: Height() - 1)

Widt or Width

Returns the current Simp object's window width  
(last index: Width() - 1)

Prnt or PrintString( $String )

Prints $String at current cursor position.  PrintString() can also accept
a hash of parameters (eg. PrintString('text' => $String)) where:

  'text' => [ "String to Print" ], # or can just be string without arrayref
  'colr' => [ "ColorCodes corresponding to text" ], # same just string optn
  'ycrs' =>  3, # Number to move the cursor's y to before printing
  'xcrs' =>  7, # Number to move the cursor's x to before printing
  'yoff' => 15, # same as ycrs except original ycrs is restored afterwards
  'xoff' => 31, # same as xcrs except original xcrs is restored afterwards
  'prin' =>  1, # flag to specify whether printed text should update the
                #   main Text() && Colr() data or just print to the screen
                #   temporarily.  Default is true (ie. Print Into Text/Colr)

The hash keys can also be the corresponding VerboseNames described in the
new() section instead of these 4-letter abbreviated key names.

PrintString() returns the number of characters printed.

Draw or DrawWindow()

Draws the current Simp object with the established TextData() and
ColorData() functions.

DrawWindow() accepts a hash of parameters like new() which will update
as many attributes of the Simp object as are specified by key => value
pairs.

DrawWindow() returns the number of lines printed (which is normally the
same as Height()).

Wait or WaitTime( $Time )

WaitTime() does nothing for $Time seconds.

$Time can be an integer or floating point number of seconds.
(eg. WaitTime(1.27) does nothing for just over one second).

WaitTime() (like GetKey()) can also use alternate waiting methods.
The default $Time format is integer or floating seconds.  It can
also be a Time::Frame object or an integer of milliseconds.
These modes can be set with the FlagTimeFrame(1) and 
FlagMillisecond(1) methods respectively.

GetK or GetKey( [$Timeout [,$FlagSDLKey]] )

Returns a keypress if one is made or -1 after waiting $Timeout seconds.

$Timeout can be an integer or floating point number of seconds.
(eg. GetKey(2.55) waits for two and one-half seconds before returning -1
if no key was pressed).

Default behavior is to not block (ie. GetKey(0)).  Use GetKey(-1) for a
blocking keypress (ie. to wait indefinitely).

GetKey() can use alternate waiting methods.  The default is integer or
floating seconds.  It can also utilize Time::Frame objects
or integer milliseconds if preferred.  These modes can be set with
the FlagTimeFrame(1) and FlagMillisecond(1) methods respectively.

Under normal mode (ie. when $FlagSDLKey is absent or false), GetKey()
returns a string describing the key pressed.  This will either be a
single character or the Curses name for the key if a special key was
pressed.  The list of special key names that can be returned from 
normal mode are described in the L<"CURSES KEY NOTES"> section.  This
means that the return value should be easy to test directly like:

  use Curses::Simp;
  my $simp = Curses::Simp->new();
  my $key  = $simp->GetKey(-1); # get a blocking keypress
  if     ($key eq 'a')         { # do 'a' stuff
  } elsif($key eq 'b')         { # do 'b' stuff
  } elsif($key eq 'A')         { # do 'A' stuff
  } elsif($key eq 'B')         { # do 'B' stuff
  } elsif($key eq 'KEY_LEFT')  { # do Left-Arrow-Key stuff
  } elsif($key eq 'KEY_NPAGE') { # do PageDown       stuff
  } elsif($key eq 'KEY_F1')    { # do F1 (Help)      stuff
  } elsif(ord($key) ==  9)     { # do Tab    stuff
  } elsif(ord($key) == 13)     { # do Return stuff
  } elsif(ord($key) == 27)     { # do Escape stuff
  }

$FlagSDLKey is a flag (default is false) which tells GetKey() to return
a verbose key string name from the list of SDLKeys in the L<"SDLKEY NOTES">
section instead of the normal Curses key value or name.  In SDLKey mode,
GetKey() also sets flags for Shift, Control, and Alt keys which are
testable through KeyMode().

The $FlagSDLKey parameter sets SDLKey mode temporarily (ie. only for a
single execution of GetKey()).  This mode can be turned on permanently
via the FlagSDLKey(1) function.

If the $Timeout for GetKey() is reached and no keypress has
occurred (in either normal mode or SDLKey mode), -1 is returned.

KMod or KeyMode( [$KeyName [,$NewValue]] )

Returns the key mode (state) of the key mode name $KeyName.  $KeyName
should be one of the KMOD_ names from the bottom of the L<"SDLKEY NOTES">
section.

If no parameters are provided, the state of KMOD_NONE is returned.

If $NewValue is provided, the state of $KeyName is set to $NewValue.

Move or MoveCursor( [$YCursor, $XCursor] )

MoveCursor() updates the current Simp object's cursor position
to the newly specified $YCursor, $XCursor.

By default, the cursor is not visible but this can be changed through
the FlagCursorVisible(1) function.

Returns ($YCursor, $XCursor) as the coordinates of the cursor.

Rsiz or ResizeWindow( $Height, $Width )

ResizeWindow() updates the current Simp object's window dimensions
to the newly specified $Height, $Width.

Think of ResizeWindow() as an easy way to call both Height() and
Width() at once.

Returns ($Height, $Width) as the dimensions of the window.

Mesg or MessageWindow( $Message )

MessageWindow() draws a Message Window in the center of the screen to 
display $Message.  MessageWindow() can also accept a hash of parameters 
(eg. MessageWindow('mesg' => $Message)) where:

  'mesg' => "Message to Print",
  'text' => [ "same as new \@text" ],
  'colr' => [ "ColorCodes corresponding to mesg or text" ],
  'titl' => "MessageWindow Title string",
  'tclr' => "ColorCodes corresponding to titl",
  'flagpres' => 1, # a flag specifying whether to "Press A Key"
  'pres' => "Press A Key...", # string to append if flagpres is true
  'pclr' => "ColorCodes corresponding to pres",
  'wait' => 1.0, # floating number of seconds to wait
                 #   if flagpres is true,  MessageWindow() waits this
                 #     long for a keypress before quitting
                 #   if flagpres is false, MessageWindow() waits this
                 #     long regardless of whether keys are pressed

The hash keys can also be the corresponding VerboseNames described in the
new() section instead of these 4-letter abbreviated key names.

Returns the value of the pressed key (if the "Press A Key" flag was true).
This can be used to make simple one-character prompt windows.  For example:

  use Curses::Simp;
  my $simp   = Curses::Simp->new();
  my $answer = $simp->MessageWindow('titl' => 'Is Simp useful?',
                                    'pres' => '(Yes/No)');
               $simp->MessageWindow('titl' => 'Answer:', $answer);

Prmt or PromptWindow( \$DefaultRef )

PromptWindow() draws a Prompt Window in the center of the screen to 
display and update the value of $DefaultRef.  \$DefaultRef should be 
a reference to a variable containing a string you want edited or
replaced.  PromptWindow() can also accept a hash of parameters 
(eg. PromptWindow('dref' => \$DefaultRef)) where:

  'dref' => \$dref, # Default Reference to variable to be read && edited
  'dtxt' => "Default Text string in place of dref",
  'dclr' => "ColorCodes corresponding to dref/dtxt",
  'hclr' => "ColorCodes corresponding to the highlighted (unedited) dref/dtxt",
  'text' => [ "same as new \@text" ],
  'colr' => [ "ColorCodes corresponding to mesg or text" ],
  'hite' =>  3, # height of the prompt window (including borders)
  'widt' => 63, # width  of the prompt window (including borders)
  'titl' => "MessageWindow Title string",
  'tclr' => "ColorCodes corresponding to titl",
  'flagcvis' => 1, # a flag specifying whether the cursor should be displayed

The hash keys can also be the corresponding VerboseNames described in the
new() section instead of these 4-letter abbreviated key names.

CPik or ColorPickWindow()

ColorPickWindow() is a simple Color Picker window.

It accepts arrow keys to highlight a particular color and enter to select.
The letter corresponding to the color or the number of the index can also
be pressed instead.

Returns the letter (ie. the Color Code) of the picked color.

DESTROY or DelW or DeleteWindow()

DeleteWindow() deletes all the components of the created Simp object
and calls ShockScreen() to cause the screen and all other created
objects to be redrawn.

ACCESSOR AND FLAG METHODS

Simp accessor and flag object methods have related interfaces as they
each access and update a single component field of Curses::Simp objects.  Each
one always returns the value of the field they access.  Thus if you want
to obtain a certain value from a Simp object, just call the accessor
method with no parameters.  If you provide parameters, the field will
be updated and will return its new value.

All of these methods accept a default parameter of their own type or
a hash of operations to perform on their field.

Some operations are only applicable to a subset of the methods as 
dictated by the field type.  The available operations are:

   Key   =>   Value Type  
    NormalName (if different) ... # Purpose
  -----      ------------ 
  'asin' =>  $scalar (number|string|arrayref)
   'assign' # asin is context-sensitive assignment to load the field
  'blnk' =>  $ignored         # blanks a string value
   'blank'
  'togl' =>  $ignored         # toggles    a flag value
   'toggle'
  'true' =>  $ignored         # trues      a flag value
  'fals' =>  $ignored         # falsifies  a flag value
   'false'
  'incr' =>  $numeric_amount  
   'increase' # increments if no $num is provided or increases by $num
  'decr' =>  $numeric_amount  
   'decrease' # decrements if no $num is provided or decreases by $num
  'nmrc' =>  $string          
   'numeric'
  # instead of an explicit 'nmrc' hash key, this means the
  #   key is an entirely numeric string like '1023'
  #   so the value gets assigned to that indexed element when
  #   the field is an array.  The key is assigned directly if
  #   the field is numeric or a string.
  # ARRAY-SPECIFIC operations:
  'size' => $ignored                # return the array size
  'push' => $scalar (number|string) # push new value
  'popp' => $ignored                # pop last value
   'pop'
  'apnd' => $scalar (number|string) # append to last element
   'append'
  'dupl' => $number                 # duplicate last line or
   'duplicate'                      #   $num line if provided
  'data' => $arrayref               # assigns the array if
                                    #   $arrayref provided &&
                                    #   returns ALL array data
  # LOOP-SPECIFIC operations:
  'next' => $ignored          # assign to next     in loop
  'prev' => $ignored          # assign to previous in loop
   'previous'

Array Accessors

  Text or TextData  # update the text  array
  Colr or ColorData # update the color array

Loop Accessors

  BTyp or WindowBorderType # loop through border types

Normal Accessors

  Name or VerboseName       # Description
  ----    -----------       -------------
  Hite or WindowHeight      # window height
  Widt or WindowWidth       # window width
  YOff or WindowYOffset     # window y-offset position
  XOff or WindowXOffset     # window x-offset position
  YCrs or CursorYOffset     # window y-cursor position
  XCrs or CursorXOffset     # window x-cursor position
  BClr or WindowBorderColor # border color code string
  Titl or WindowTitle       # title string
  TClr or WindowTitleColor  # title  color code string
  DNdx or DisplayStackIndex # global display index

Flag Accessors

  FlagName or VerboseFlagName Default # Description
  --------    --------------- ------- -------------
  FlagAuDr or FlagAutoDraw      1    # Automatic DrawWindow() call whenever 
                                     #   TextData or ColorData are updated
  FlagMaxi or FlagMaximize      1    # Maximize window
  FlagShrk or FlagShrinkToFit   1    # Shrink window to fit TextData
  FlagCntr or FlagCenter        1    # Center window within entire screen
  FlagCVis or FlagCursorVisible 0    # Cursor Visible
  FlagScrl or FlagScrollbar     0    # use Scrollbars (not implemented yet)
  FlagSDLK or FlagSDLKey        0    # use advanced SDLKey mode in GetKey()
  FlagBkgr or FlagBackground    0    # always expect background colors to be
                                     #   present in color codes
  FlagFram or FlagTimeFrame     0    # use Time::Frame objects  instead of
                                     #   float seconds for timing
  FlagMili or FlagMillisecond   0    # use integer milliseconds instead of
                                     #   float seconds for timing
  FlagPrin or FlagPrintInto     1    # PrintString() prints Into TextData
    # array.  If FlagPrintInto is false, then each call to PrintString()
    # only writes to the screen temporarily and will be wiped the next time
    # the window behind it is updated.

Accessor and Flag Method Usage Examples

  #!/usr/bin/perl -w
  use strict;
  use Curses::Simp;
  # create new object which gets auto-drawn with init params
  my $simp = Curses::Simp->new('text' => [ 'hmmm', 'haha', 'whoa', 'yeah' ],
                               'colr' => [ 'bbbB', 'bBBw', 'BwrR', 'ROYW' ],
                               'btyp' => 1,
                               'maxi' => 0); 
     $simp->GetK(-1);               # wait for a key press
     $simp->Text('push' => 'weee'); # add more to the Text
     $simp->Colr('push' => 'WwBb'); #              && Colr arrays
     $simp->Maxi('togl');           # toggle  the maximize flag
     $simp->GetK(-1);               # wait for a key press
     $simp->Text('2'    => 'cool'); # change index two elements of Text
     $simp->Colr('2'    => 'uUCW'); #                           && Colr
     $simp->Maxi('fals');           # falsify the maximize flag
     $simp->GetK(-1);               # wait for a key press
     $simp->Text('popp');           # pop the last elements off Text
     $simp->Colr('popp');           #                        && Colr
     $simp->BTyp('incr');           # increment the border type
     $simp->GetK(-1);               # wait for a key press
     $simp->Text('asin' => [ 'some', 'diff', 'rent', 'stuf' ]);
     $simp->Colr('asin' => [ 'GGYY', 'CCOO', 'UURR', 'WWPP' ]);
     $simp->BTyp('incr');           # increment the border type
     $simp->GetK(-1);               # wait for a key press before quitting

CURSES KEY NOTES

When the GetKey() function is in the normal default mode of input,
special keypress name strings will be returned when detected.  A
small set of the names below are found commonly (like the arrow 
keys, the function keys, HOME, END, PPAGE [PageUp], NPAGE [PageDown],
IC [Insert], and BACKSPACE) but they are all described here since
they are supported by L<Curses.pm> and therefore could arise.

The list of returnable Curses Key names are:

      KEY_F1                   KEY_F2                   KEY_F3                 
      KEY_F4                   KEY_F5                   KEY_F6                 
      KEY_F7                   KEY_F8                   KEY_F9                 
      KEY_F10                  KEY_F11                  KEY_F12                
      KEY_F13                  KEY_F14                  KEY_F15                
      KEY_A1                   KEY_A3                   KEY_B2                 
      KEY_BACKSPACE            KEY_BEG                  KEY_BREAK              
      KEY_BTAB                 KEY_C1                   KEY_C3                 
      KEY_CANCEL               KEY_CATAB                KEY_CLEAR              
      KEY_CLOSE                KEY_COMMAND              KEY_COPY               
      KEY_CREATE               KEY_CTAB                 KEY_DC                 
      KEY_DL                   KEY_DOWN                 KEY_EIC                
      KEY_END                  KEY_ENTER                KEY_EOL                
      KEY_EOS                  KEY_EXIT                 KEY_F0                 
      KEY_FIND                 KEY_HELP                 KEY_HOME               
      KEY_IC                   KEY_IL                   KEY_LEFT               
      KEY_LL                   KEY_MARK                 KEY_MAX                
      KEY_MESSAGE              KEY_MIN                  KEY_MOVE               
      KEY_NEXT                 KEY_NPAGE                KEY_OPEN               
      KEY_OPTIONS              KEY_PPAGE                KEY_PREVIOUS           
      KEY_PRINT                KEY_REDO                 KEY_REFERENCE          
      KEY_REFRESH              KEY_REPLACE              KEY_RESET              
      KEY_RESTART              KEY_RESUME               KEY_RIGHT              
      KEY_SAVE                 KEY_SBEG                 KEY_SCANCEL            
      KEY_SCOMMAND             KEY_SCOPY                KEY_SCREATE            
      KEY_SDC                  KEY_SDL                  KEY_SELECT             
      KEY_SEND                 KEY_SEOL                 KEY_SEXIT              
      KEY_SF                   KEY_SFIND                KEY_SHELP              
      KEY_SHOME                KEY_SIC                  KEY_SLEFT              
      KEY_SMESSAGE             KEY_SMOVE                KEY_SNEXT              
      KEY_SOPTIONS             KEY_SPREVIOUS            KEY_SPRINT             
      KEY_SR                   KEY_SREDO                KEY_SREPLACE           
      KEY_SRESET               KEY_SRIGHT               KEY_SRSUME             
      KEY_SSAVE                KEY_SSUSPEND             KEY_STAB               
      KEY_SUNDO                KEY_SUSPEND              KEY_UNDO               
      KEY_UP                   KEY_MOUSE                                       

SDLKEY NOTES

The GetKey() function has a special advanced mode of input.
Instead of returning the plain keypress (eg. 'a'), the $FlagSDLKey
parameter can be set to true for temporary SDLKey mode or with
FlagSDLKey(1) for permanence so that verbose strings of SDLKey names
(eg. 'SDLK_a') will be returned.

The list of returnable SDLKey names are:

   SDLKey           ASCII value    Common name
  ----------------  -----------   ------------
  'SDLK_BACKSPACE',      #'\b'    backspace
  'SDLK_TAB',            #'\t'    tab
  'SDLK_CLEAR',          #        clear
  'SDLK_RETURN',         #'\r'    return
  'SDLK_PAUSE',          #        pause
  'SDLK_ESCAPE',         #'^['    escape
  'SDLK_SPACE',          #' '     space
  'SDLK_EXCLAIM',        #'!'     exclaim
  'SDLK_QUOTEDBL',       #'"'     quotedbl
  'SDLK_HASH',           #'#'     hash
  'SDLK_DOLLAR',         #'$'     dollar
  'SDLK_AMPERSAND',      #'&'     ampersand
  'SDLK_QUOTE',          #'''     quote
  'SDLK_LEFTPAREN',      #'('     left parenthesis
  'SDLK_RIGHTPAREN',     #')'     right parenthesis
  'SDLK_ASTERISK',       #'*'     asterisk
  'SDLK_PLUS',           #'+'     plus sign
  'SDLK_COMMA',          #','     comma
  'SDLK_MINUS',          #'-'     minus sign
  'SDLK_PERIOD',         #'.'     period
  'SDLK_SLASH',          #'/'     forward slash
  'SDLK_0',              #'0'     0
  'SDLK_1',              #'1'     1
  'SDLK_2',              #'2'     2
  'SDLK_3',              #'3'     3
  'SDLK_4',              #'4'     4
  'SDLK_5',              #'5'     5
  'SDLK_6',              #'6'     6
  'SDLK_7',              #'7'     7
  'SDLK_8',              #'8'     8
  'SDLK_9',              #'9'     9
  'SDLK_COLON',          #':'     colon
  'SDLK_SEMICOLON',      #';'     semicolon
  'SDLK_LESS',           #'<'     less-than sign
  'SDLK_EQUALS',         #'='     equals sign
  'SDLK_GREATER',        #'>'     greater-than sign
  'SDLK_QUESTION',       #'?'     question mark
  'SDLK_AT',             #'@'     at
  'SDLK_LEFTBRACKET',    #'['     left bracket
  'SDLK_BACKSLASH',      #'\'     backslash
  'SDLK_RIGHTBRACKET',   #']'     right bracket
  'SDLK_CARET',          #'^'     caret
  'SDLK_UNDERSCORE',     #'_'     underscore
  'SDLK_BACKQUOTE',      #'`'     grave
  'SDLK_a',              #'a'     a
  'SDLK_b',              #'b'     b
  'SDLK_c',              #'c'     c
  'SDLK_d',              #'d'     d
  'SDLK_e',              #'e'     e
  'SDLK_f',              #'f'     f
  'SDLK_g',              #'g'     g
  'SDLK_h',              #'h'     h
  'SDLK_i',              #'i'     i
  'SDLK_j',              #'j'     j
  'SDLK_k',              #'k'     k
  'SDLK_l',              #'l'     l
  'SDLK_m',              #'m'     m
  'SDLK_n',              #'n'     n
  'SDLK_o',              #'o'     o
  'SDLK_p',              #'p'     p
  'SDLK_q',              #'q'     q
  'SDLK_r',              #'r'     r
  'SDLK_s',              #'s'     s
  'SDLK_t',              #'t'     t
  'SDLK_u',              #'u'     u
  'SDLK_v',              #'v'     v
  'SDLK_w',              #'w'     w
  'SDLK_x',              #'x'     x
  'SDLK_y',              #'y'     y
  'SDLK_z',              #'z'     z
  'SDLK_DELETE',         #'^?'    delete
  'SDLK_UP',             #        up arrow
  'SDLK_DOWN',           #        down arrow
  'SDLK_RIGHT',          #        right arrow
  'SDLK_LEFT',           #        left arrow
  'SDLK_INSERT',         #        insert
  'SDLK_HOME',           #        home
  'SDLK_END',            #        end
  'SDLK_PAGEUP',         #        page up
  'SDLK_PAGEDOWN',       #        page down
  'SDLK_F1',             #        F1
  'SDLK_F2',             #        F2
  'SDLK_F3',             #        F3
  'SDLK_F4',             #        F4
  'SDLK_F5',             #        F5
  'SDLK_F6',             #        F6
  'SDLK_F7',             #        F7
  'SDLK_F8',             #        F8
  'SDLK_F9',             #        F9
  'SDLK_F10',            #        F10
  'SDLK_F11',            #        F11
  'SDLK_F12',            #        F12
  'SDLK_F13',            #        F13
  'SDLK_F14',            #        F14
  'SDLK_F15',            #        F15
  # SDLKeys below aren't detected correctly yet
  'SDLK_KP0',            #        keypad 0
  'SDLK_KP1',            #        keypad 1
  'SDLK_KP2',            #        keypad 2
  'SDLK_KP3',            #        keypad 3
  'SDLK_KP4',            #        keypad 4
  'SDLK_KP5',            #        keypad 5
  'SDLK_KP6',            #        keypad 6
  'SDLK_KP7',            #        keypad 7
  'SDLK_KP8',            #        keypad 8
  'SDLK_KP9',            #        keypad 9
  'SDLK_KP_PERIOD',      #'.'     keypad period
  'SDLK_KP_DIVIDE',      #'/'     keypad divide
  'SDLK_KP_MULTIPLY',    #'*'     keypad multiply
  'SDLK_KP_MINUS',       #'-'     keypad minus
  'SDLK_KP_PLUS',        #'+'     keypad plus
  'SDLK_KP_ENTER',       #'\r'    keypad enter
  'SDLK_KP_EQUALS',      #'='     keypad equals
  'SDLK_NUMLOCK',        #        numlock
  'SDLK_CAPSLOCK',       #        capslock
  'SDLK_SCROLLOCK',      #        scrollock
  'SDLK_RSHIFT',         #        right shift
  'SDLK_LSHIFT',         #        left shift
  'SDLK_RCTRL',          #        right ctrl
  'SDLK_LCTRL',          #        left ctrl
  'SDLK_RALT',           #        right alt
  'SDLK_LALT',           #        left alt
  'SDLK_RMETA',          #        right meta
  'SDLK_LMETA',          #        left meta
  'SDLK_LSUPER',         #        left windows key
  'SDLK_RSUPER',         #        right windows key
  'SDLK_MODE',           #        mode shift
  'SDLK_HELP',           #        help
  'SDLK_PRINT',          #        print-screen
  'SDLK_SYSREQ',         #        SysRq
  'SDLK_BREAK',          #        break
  'SDLK_MENU',           #        menu
  'SDLK_POWER',          #        power
  'SDLK_EURO',           #        euro

SDLKey mode also sets flags in KeyMode() where:

   SDL Modifier                    Meaning
  --------------                  ---------
  'KMOD_NONE',           #        No modifiers applicable
  'KMOD_CTRL',           #        A  Control key is down
  'KMOD_SHIFT',          #        A  Shift   key is down
  'KMOD_ALT',            #        An Alt     key is down

COLOR NOTES

Colors can be encoded along with each text line to be printed.  
PrintString() and DrawWindow() each take hash parameters where the
key should be 'colr' or 'ColorData' and the value is a color code
string as described below.

A normal color code is simply a single character (typically just the
first letter of the color name and the case [upper or lower] 
designates high or low intensity [ie. Bold on or off]).  Simple 
single character color codes represent only the foreground color.
The default printing mode of color codes assumes black background
colors for everything.  There are special ways to specify non-black
background colors or to encode repeating color codes if you want to.
The default (which assumes no background colors are specified) can
be overridden object-wide by the FlagBackground(1) function.

Normal Color Code Reference

                          b(Black),  r(Red),    g(Green),  y(Yellow),
   (upper-case = bright)  u(Blue),   p(Purple), c(Cyan),   w(White)

Alternate Color Codes

                          o([Orange] *Yellow),   m([Magenta]  Purple),
   (upper-case = bright)  t([Teal]    Cyan),     l([Lavender] Purple)

*Upper-Case Bright Orange Exception

There is a special exception for Upper-Case 'O' (Orange).  Orange is
actually Dark Yellow but it is often much brighter than any of the 
other dark colors which leads to confusion.  Therefore, Upper-Case 'O'
breaks the (upper-case = bright) rule and is interpreted the same as
Lower-Case 'y'.  Every other color code is consistent with the rule.

Interpretation of Backgrounds and Repeats in Color Codes

The following mechanisms are available for changing the default color
code string interpretation to read background colors after foreground
and to specify abbreviations for code repeating:

The function FlagBackground(1) will specify that you wish to have all
color codes interpreted expecting both foreground and background
characters for each source text character.  Similarly,
FlagBackground(0) (which is the default setting of not expecting
Background characters) will turn off global background interpretation.

The base64 characters specified below are in the set [0-9A-Za-z._] and
are interpreted using the L<Math::BaseCnv> module available from the CPAN.

A space in a color code string is the same as 'b' (black).

When Background mode is OFF (ie. the default after FlagBackground(0)
or a code string following the '!' [Simp!] character):

   x - When this lowercase times character is used, it must be followed
         by a base64 character which specifies how many times the color
         code prior to the (x) times character should be repeated.
   X - When this uppercase times character is used, it must be followed
         by a base64 character which specifies how many times the color
         code prior to the (X) times character should be repeated.  The
         difference from the lowercase (x) times is that the code prior
         to the (X) is treated as a background color for that many
         following foreground color code characters.
         After that, backgrounds return to black.
   , - The comma character specifies that the next two characters are a
         foreground and background color pair.
         After that, backgrounds return to black.
   : - The colon character specifies that the following character is a
         (presumably non-black) background character to use instead of 
         the default black for the remainder of the line (or until another
         special character overrides this one).
   ; - The semicolon (Advanced;) character specifies that the remaining
         part of the current color code line should be interpreted as if
         full background interpretation were turned ON (as if
         FlagBackground(1) had been called just for this line) so
         further interpretation proceeds like the FlagBackground(1)
         section below.

   Each background specification character takes effect starting with the 
     next encountered foreground character so:
       'RgX2UU', 'R:gUU', and 'R;Ugx2' all expand to 'RbUgUg' not 'RgUgUb'
   Some Examples:
     PrintString('Hello World',  # the simplest 1-to-1 text/color printing
                 'WWWWW UUUUU'); # all characters printed on black background
     PrintString('Hello World',  # the same as above but...
                 'Wx5bUx5');     #   using repeat (x) times
       Both of the above PrintString() calls would print 'Hello' in Bright
         White and 'World' in Bright blUe both on the default black
         background.  The color strings would expand from:
           'WWWWW UUUUU' or 'Wx5bUx5' to 'WbWbWbWbWbbbUbUbUbUbUb';
     PrintString('Hello World', 
                 'Wx5b,Gu,Gu,Gu,Gu,Gu');
     PrintString('Hello World', 
                 'Wx5b:uGx5');
     PrintString('Hello World', 
                 'WWWWWbuX5GGGGG');
     PrintString('Hello World', 
                 'Wx5buX5Gx5');
       These PrintString() calls would print 'Hello' the same as before
         but now 'World' would be in Bright Green on a dark blUe
         background.  These color strings would all expand to:
           'WbWbWbWbWbbbGuGuGuGuGu'.

When Background mode is ON  (ie. after FlagBackground(1) or a code
string following the ';' [Advanced;] character):

   . - When the dot character is encountered in a color pair, it signifies
         that the other field (foreground or background) should be used
         for the remainder of the color code string (or until the next 
         (.) dot character is found).
   x - When this times character is used, it must be followed by a base64
         character which specifies how many times the color code pair 
         prior to the (x) times character should be repeated.
   X - When this upper-case times character is used, it specifies that
         whichever field value preceeded it, it should be repeated the 
         number of times specified in the base64 character which follows.
   ! - The bang (Simp!) character specifies that the remaining part of
         the current color code line should be interpreted as if
         background interpretation were turned OFF (as if
         FlagBackground(0) had been called just for this line) so further
         interpretation proceeds like the FlagBackground(0) section above.

   Some Examples:
     typical color pairs code string: 'WbWbWbGuGuGuGuGpGpGpYgYgYgYg'
       means 3 source characters should be Bright White  on black,
             4 source characters should be Bright Green  on blue,
             3 source characters should be Bright Green  on purple,
        and  4 source characters should be Bright Yellow on green.
     same result using (.)    : 'W.bbb.G.uuuuppp.Y.gggg'
     same result using (x)    : 'Wbx3Gux4Gpx3Ygx4'
     same result using (X)    : 'WX3bbbGX7uuuupppYX4gggg'
     same result using hybrid : 'WbWbWbG.uX4pX3.Ygx4'
         color code string:   =>      expands to:
      'W.brgo'                =>  'WbWrWgWo'  # W. -> brgo
      '.bWCPU'                =>  'WbCbPbUb'  # .b -> WCPU
      'Wbx4'                  =>  'WbWbWbWb'  # (Wb) x 4
      'WbRx3p'                =>  'WbRbRbRp'  # W + (bR) x 3 + p
      'WX4upcw'               =>  'WuWpWcWw'  # W X 4 -> upcw
      'WoX4RGU'               =>  'WoRoGoUo'  # Wo + o X 3 -> RGU

If a color code string is terminated with a dollar ($) character,
this tells PrintString() and DrawWindow() that the string is 
already fully expanded and to forego passing the string to 
ExpandColorCodeString().

I have tried to make Simp very simple to use yet still flexible &&
powerful.  Please feel free to e-mail me any suggestions || coding 
tips || notes of appreciation like "I appreciate you!  I like to say 
appreciate.  You can say it too.  Go on.  Say it.  Say 'I appreciate 
you!  I like to say appreciate.  You can say it too.  Go on.  Say it.
Say "..."'"  Thank you.  It's like app-ree-see-ate.  TTFN.

CHANGES

Revision history for Perl extension Curses::Simp:

- 1.0.41V0L3a  Sat Jan 31 00:21:03:36 2004

* made verbose accessor names like VerboseName instead of verbose_name,
    updated POD to use VerboseNames instead of 4-letter names &&
    removed most '&&', made Text('1' => 'new line') use Prnt nstd of
    Draw for efficiency, made ShokScrn not blank the screen so often,
    made GetK return detected KEY_ names in normal mode, added CURSES
    KEY MODE section && made both key modes return -1 if $tmot reached,
    fixed ShokScrn overlap && DelW bugs, wrote support for VerboseName
    hash keys, made flag accessors without ^Flag

- 1.0.41O4516  Sat Jan 24 04:05:01:06 2004

* updated POD && added Simp projects into bin/ && MANIFEST in preparation
    for release, made all but ptok && qbix non-executable for EXE_FILES

- 1.0.41O3SQK  Sat Jan 24 03:28:26:20 2004

* setup window border char sets, added SDLK advanced input option to GetK,
    made new Mesg, Prmt, && CPik utils, added PrntInto 'flagprin' ability,
    fixed weird char probs in Draw && removed weird char support from Prnt

- 1.0.4140asO  Sun Jan  4 00:36:54:24 2004

* CHANGES section && new objects created, refined Draw() && InitPair()

- 1.0.37VG26k  Thu Jul 31 16:02:06:46 2003

* original version

INSTALL

Please run:

    `perl -MCPAN -e "install Curses::Simp"`

or uncompress the package and run the standard:

    `perl Makefile.PL; make; make test; make install`

FILES

Curses::Simp requires:

  L<Carp>                to allow errors to croak() from calling sub
  L<Curses>              provides core screen and input handling
  L<Math::BaseCnv>       to handle number-base conversion

Curses::Simp uses (if available):

  L<Time::Frame>         to provide another mechanism for timing

LICENSE

Most source code should be Free!
  Code I have lawful authority over is and shall be!
Copyright: (c) 2003, Pip Stuart.  All rights reserved.
Copyleft :  I license this software under the GNU General Public
  License (version 2).  Please consult the Free Software Foundation
  (http://www.fsf.org) for important information about your freedom.

AUTHOR

Pip Stuart <Pip@CPAN.Org>

