Curses-Simp
view release on metacpan or search on metacpan
NAME
Curses::Simp - Curses Not Quite Simple
VERSION
This documentation refers to version 1.4.A8UG1gG of Curses::Simp, which
was released on Mon Aug 30 16:01:42:16 2010.
SYNOPSIS
use Curses::Simp;
my @text; my $keey = '';
my $simp = tie(@text, 'Curses::Simp');
@text =('1337', 'nachoz', 'w/', 'cheese' x 7);
while($keey ne 'x'){ # wait for 'x' to eXit
$keey = $simp->GetKey(-1); # get a blocking keypress
push(@text, $keey);
}
DESCRIPTION
Curses::Simp provides a curt mechanism for updating a console screen
with any Perl array (or multiple arrays to include color codes). Most
key events can be obtained and tested directly. The goal was ease-of-use
for the common cases first and efficient rendering second.
2DU
- mk proper scrollbars for all objects && use in Brws: view
- Brws: mk togl to pack files left && right in view
- mk ~/.simprc to save CPik && Brws cfg, OVERMAPP, etc.
- CPik: rewrite BildBlox to scale style to window dims if !flagshrk &&
mk sure no forg or bakg works for all styles... also add options for
only name or number options or common grid size defaults
- CPik: add styles to pick fgcl,bgcl color code at once
- 4NT: work on recognizing more keys the same as Curses (&& then SDL)
- 4NT: write custom window support? mk Mesg at least wrap MSGBOX
- describe Simp objects sharing apps (ptok above pmix) mk OScr read Simp
apps @_ param list && auto-handle --geom wxh+x+y
- Prmt: mk new 'cbls' type: as a ckbx list && use in BrwsCnfg
- Prmt: mk new 'rdls' type: as a radio list w/ auto (*) -
- Mesg: mk new 'slid' type: params for all overlay text, chars, ticks,
flags, etc. && updt pmix to use... maybe register sub fields,dims...
- Prnt: add multi-line option where text can split on /\n/ but each new
line prints relative to starting xcrs
- Prmt: add multi-line option where dtxt can split on /\n/ && ^d accepts
entry instead of RETURN
- Prnt: handle ASCII chars under 32 with escapes like Draw
- Draw: optimize rendering
- Prnt&&Draw: handle ASCII chars under 32 better than current escapes
- mk 'ceol' && 'ceos' params to clear text[n] from cursor on
- consider breaking sub (CPik|Brws|.+?) into own Curses::Simp::$1.pm
instead of letting Simp.pm remain so cluttered
if detectable:
- handle xterm resize events
- handle mouse input (study any existent Curses apps that use mouse
input you can find ... probably in C), read man for gpm(1), sysmouse(4),
&& sb(4) && study aumix mouse source
- 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 documentation or
examples of Curses usage so I fiddled until I could wrap the most
important behaviors in names and enhanced functions.
USAGE
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 automatically 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' => [ ]
'fclr' or 'ForegroundColorData' => [ ]
'bclr' or 'BackgroundColorData' => [ ]
'kque' or 'KeyQueue' => [ ]
'mque' or 'KeyModQueue' => [ ]
'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
'brfc' or 'WindowBorderForegroundColor'=> 'w'
'brbc' or 'WindowBorderBackgroundColor'=> 'k'
'titl' or 'WindowTitle' => ''
'ttfc' or 'WindowTitleForegroundColor' => 'W'
'ttbc' or 'WindowTitleBackgroundColor' => 'k'
'dndx' or 'DisplayStackIndex' => 0
'flagaudr' or 'FlagAutoDraw' => 1
'flagadtf' or 'FlagAutoDrawTiedForegroundData' => 1
'flagadtb' or 'FlagAutoDrawTiedBackgroundData' => 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
'flagfram' or 'FlagTimeFrame' => 0
'flagmili' or 'FlagMillisecond' => 0
tie(@bclr, 'Curses::Simp::BClr', $simp);
@text = ( '1337', 'nachoz', 'w/', 'cheese' x 7); $simp->GetK(1);
push(@fclr, 'GBRG' ); $simp->GetK(1);
push(@fclr, 'YWOPCY' ); $simp->GetK(1);
push(@fclr, 'wK' ); $simp->GetK(1);
push(@fclr, 'P' ); $simp->GetK(1);
push(@bclr, 'r' ); $simp->GetK(1);
push(@bclr, 'g' ); $simp->GetK(1);
push(@bclr, 'c' ); $simp->GetK(1);
push(@bclr, 'b' ); $simp->GetK(1);
Notice the three tie() lines near the top. The second and third must
provide the third parameter of the object which they also want to tie
to. If this is not provided, the program will exit.
The result of all this is an extremely simple way to immediately
manipulate any of the text or colors displayed on the console screen.
CnvAnsCC or ConvertAnsiColorCode( $AnsiColorCode )
Returns the Simp form of the ANSI color code $AnsiColorCode.
$AnsiColorCode may contain any of the typical ANSI attribute or color
codes:
Attribute codes:
00=none 01=bold 04=underscore 05=blink 07=reverse 08=concealed
Foreground color codes:
30=black 31=red 32=green 33=yellow 34=blue 35=magenta 36=cyan 37=white
Background color codes:
40=black 41=red 42=green 43=yellow 44=blue 45=magenta 46=cyan 47=white
ConvertAnsiColorCode() is primarily useful as an internal function to
the Curses::Simp package but I have exposed it because it could be
useful elsewhere.
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 and it slows drawing down.
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 (e.g., PrintString('text' => $String)) where:
'text' => [ "String to Print" ], # or can just be string without arrayref
'fclr' => [ "ForegroundColorCodes corresponding to text" ],
'bclr' => [ "BackgroundColorCodes corresponding to text" ],
'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(), FClr(), and BClr() data or just print to the
# screen temporarily. Default is true (i.e., Print Into all)
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. (e.g.,
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. (e.g.,
GetKey(2.55) waits for two and one-half seconds before returning -1 if
no key was pressed).
Default behavior is to not block (i.e., GetKey(0)). Use GetKey(-1) for a
blocking keypress (i.e., 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 (i.e., 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 "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 "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 (i.e., 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 "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.
GetS or GetString( [$YCursor, $XCursor[, $ResultLength]] )
GetString() returns the string found from the cursor (or the specified
coordinates) on to the end-of-line or to $ResultLength if provided.
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
(e.g., MessageWindow('mesg' => $Message)) where:
'mesg' => "Message to Print",
'text' => [ "same as new \@text" ],
'fclr' => [ "ForegroundColorCodes corresponding to mesg or text" ],
'bclr' => [ "BackgroundColorCodes corresponding to mesg or text" ],
'titl' => "MessageWindow Title string",
'ttfc' => "ColorCodes corresponding to titl foreground color",
'ttbc' => "ColorCodes corresponding to titl background color",
'flagprsk' => 1, # a flag specifying whether to "Press A Key"
'pres' => "Press A Key...", # string to append if flagprsk is true
'prfc' => "ColorCodes corresponding to pres foreground color",
'prbc' => "ColorCodes corresponding to pres background color",
'wait' => 1.0, # floating number of seconds to wait
# if flagprsk is true, MessageWindow() waits this
# long for a keypress before quitting
# if flagprsk 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 (e.g.,
PromptWindow('dref' => \$DefaultRef)) where:
'dref' => \$dref, # Default Reference to variable to be read && edited
'dtxt' => "Default Text string in place of dref",
'dtfc' => "ColorCodes corresponding to dref/dtxt foreground color",
'dtbc' => "ColorCodes corresponding to dref/dtxt background color",
'hifc' => "ColorCodes for highlighted (unedited) dref/dtxt foreground color",
'hibc' => "ColorCodes for highlighted (unedited) dref/dtxt background color",
'text' => [ "same as new \@text" ],
'fclr' => [ "ForegroundColorCodes corresponding to text" ],
'bclr' => [ "BackgroundColorCodes corresponding to text" ],
'hite' => 3, # height of the prompt window (including borders)
'widt' => 63, # width of the prompt window (including borders)
'titl' => "PromptWindow Title string",
'ttfc' => "ColorCodes corresponding to titl foreground color",
'ttbc' => "ColorCodes corresponding to titl background color",
'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 (i.e., Color Code) of the picked color.
Brws or BrowseWindow()
BrowseWindow() is a simple file browser.
It contains typical file browse dialog components which can be tabbed
between. The tilde (~) character opens and closes drop down boxes. Enter
presses highlighted buttons or selects a highlighted file. F1 brings up
the BrowseWindow() help text.
Returns the full filename chosen or -1 if dialog was canceled.
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
FClr or ForegroundColorData # update the color array for foregrounds
BClr or BackgroundColorData # update the color array for backgrounds
Instead of using the above Array Accessors and Array-Specific
operations, it is recommended that you employ the "Tied Array
Interfaces" since they accomplish the goal of screen manipulation in a
more Perl-friendly manner.
Text or TextData
FClr or ForegroundColorData
BClr or BackgroundColorData
Loop Accessors
BTyp or WindowBorderType # loop through border types
BTyp or WindowBorderType
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
BrFC or WindowBorderForegroundColor # border fg color code string
BrBC or WindowBorderBackgroundColor # border bg color code string
Titl or WindowTitle # title string
TtFC or WindowTitleForegroundColor # title fg color code string
TtBC or WindowTitleBackgroundColor # title bg color code string
DNdx or DisplayStackIndex # global display index
Hite or WindowHeight
Widt or WindowWidth
YOff or WindowYOffset
XOff or WindowXOffset
YCrs or CursorYOffset
XCrs or CursorXOffset
BrFC or WindowBorderForegroundColor
BrBC or WindowBorderBackgroundColor
Titl or WindowTitle
TtFC or WindowTitleForegroundColor
TtBC or WindowTitleBackgroundColor
DNdx or DisplayStackIndex
Flag Accessors
FlagName or VerboseFlagName Default # Description
-------- --------------- ------- -------------
FlagAuDr or FlagAutoDraw 1 # Automatic DrawWindow() call whenever
# TextData or Color*Data is updated
FlagADTF or FlagAutoDrawTiedForegroundData 1 # Automatic DrawWindow() call
# for arrays tied to Curses::Simp::FClr objects when FlagAuDr is already set
FlagADTB or FlagAutoDrawTiedBackgroundData 1 # Automatic DrawWindow() call
# for arrays tied to Curses::Simp::BClr objects when FlagAuDr is already set
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
FlagSDLK or FlagSDLKey 0 # use advanced SDLKey mode in GetKey()
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.
FlagClrU or FlagColorUsed 0 # ColorUsed gets set automatically
# when color codes are used and determines if internal dialogs have color
AuDr or FlagAuDr or FlagAutoDraw
ADTF or FlagADTF or FlagAutoDrawTiedForegroundData
ADTB or FlagADTB or FlagAutoDrawTiedBackgroundData
Down or FlagDown or FlagDropIsDown
Drop or FlagDrop or FlagDropDown
Insr or FlagInsr or FlagInsertMode
Maxi or FlagMaxi or FlagMaximize
Shrk or FlagShrk or FlagShrinkToFit
Cntr or FlagCntr or FlagCenter
CVis or FlagCVis or FlagCursorVisible
Scrl or FlagScrl or FlagScrollbar
SDLK or FlagSDLK or FlagSDLKey
Fram or FlagFram or FlagTimeFrame
Mili or FlagMili or FlagMillisecond
Prin or FlagPrin or FlagPrintInto
( run in 1.455 second using v1.01-cache-2.11-cpan-140bd7fdf52 )