NAME
Curses::Widgets -- Curses-based widgets and functions
Doc/Module Version info
$Id: Widgets.pod,v 0.8 1999/06/17 23:55:36 corliss Exp corliss $
REQUIREMENTS
Requires the Curses module, Curses or nCurses libraries, and the Unix 'cal' command.
DESCRIPTION
This module provides a standard library of functions and widgets for use in creating Curses-based interfaces. Should work reliably with both Curses and nCurses libraries.
Current widgets include:
Text field (txt_field)
List box (list_box)
Button sets (buttons)
Calendar (calendar)Extra functions include:
init_colours
select_colour
line_counNote that all of the widgets strictly use named parameters, while the functions use unamed arguments. All of the either return values, or modify references that were passed as arguments.
EXPORTED
Default
txt_field
buttons
init_colours
list_box
calendar
select_colour
OK
line_count
WIDGETS
Text field
The text field widget creates a derived window (which uses coordinates relative to the passed window) with a border surrounding the text. When used interactively, it handles its own input, passing back only the keys it doesn't know how to handle, as well as the final content string.
The widget provides an arrow superimposed on the border to indicate whether there is content that can be scrolled to in that direction. The arrow only appears when the content exceeds the display area.
Currently, this widget will handle any normal characters to be inserted into the content string, and the following keys:
Key Curses Constant
-------------------------------
backspace KEY_BACKSPACE
left arrow KEY_LEFT
right arrow KEY_RIGHT
up arrow KEY_UP
down arrow KEY_DOWN
page up KEY_PPAGE
home KEY_HOME
end KEY_ENDAll parameters are passed as named parameters:
Parameter Commments
-----------------------------------
window reference
ypos integer, optional,
default is 1
xpos integer, optional,
default is 1
lines integer, optional,
default is 1
cols integer, optional,
default is $COLS - 2
content string, optional,
default is "\n"
pos integer, optional
default is 1
border named colour, optional
default is 'red'
function reference, optional
draw_only integer, optional
default is 0
l_limit integer, optional
c_limit integer, optional
title string, optional
regex string, optional,
default is "\t"'window' is a scalar reference to a predefined window or subwindow. A quick tip for debugging: if either 'xpos', 'ypos', 'lines', or 'cols' cause any portion of the window to extend passed the boundaries of the parent window, your code will die, claiming that you can't call any operations on an undefined window, assuming you're using the w flag.
'pos' refers to the cursor position for use in interactive mode, so that input can be inserted or appended to the content string. This is ignored if passed in conjunction with the draw_only parameter, if set to any value that evaluates to a true value, as per Perl.
'function' is a scalar reference to a subroutine that can be called by the widget when it times out, waiting for input. For this to work, it assumes a halfdelay(10) has been called, or on some other interval.
'l_limit' and 'c_limit' are completely optional, and can be used together, if desired. Both are integers, and can limit the content in the text field. Which ever limit is hit first will be honoured.
'title' is an optional string that will be superimposed over the top-left border in reverse video.
'regex' is a string of all the characters that you wish to use to shift focus off the text field, and return the contents. By default, the tab character is used ("\t"). This string is interpolated inside of character class brackets, so don't include regex specific punctuation. If you wish both new lines and tabs to shift focus, you would use "\t\n".
The memory allocated for the window is released when the widget routine exits.
B<Example (non-Interactive)>
txt_field( 'window' => \$window,
'ypos' => 2,
'xpos' => $COLS - 5,
'lines' => $LINES - 10,
'cols' => $COLS - 10,
'content' => $note,
'border' => 'red',
'draw_only' => 1);
B<(Interactive)>
($key, $rtrnd_note) = txt_field( 'window' => \$window,
'ypos' => 2,
'xpos' => $COLS - 5,
'lines' => $LINES - 10,
'cols' => $COLS - 10,
'content' => $note,
'border' => 'green',
'pos' => length($note),
'function' => \&clock);List box
The list box widget creates a derived window that holds a scrollable list of items, surounded by a border. When called interactively, it handles it's own input for navigation. Any keys not used for navigation are returned, as well as the currently selected item.
Key Curses Constant
-------------------------------
left arrow KEY_LEFT
right arrow KEY_RIGHTThe widget provides an arrow superimposed on the border to indicate whether there is content that can be scrolled to in that direction. The arrow only appears when the content exceeds the display area.
All parameters are passed as named parameters:
Parameter Commments
-----------------------------------
window reference
ypos integer, optional,
default is 1
xpos integer, optional,
default is 1
lines integer, optional,
default is 1
cols integer, optional,
default is $COLS - 2
list reference, optional
border named colour, optional
default is 'red'
selected integer, optional,
default is 1
function reference, optional
draw_only integer, optional
default is 0
title string, optionalAll previously described parameters maintain their same use and warnings.
'list' is a hash reference, and a numeric sort is done on the keys, while the associated values are what are actually displayed. The keys must be a sequential sequence of numbers. It doesn't care what number you start with, but it must be sequential.
B<Example (non-Interactive)>
list_box( 'window' => \$main,
'ypos' => 2,
'lines' => 10,
'cols' => 25,
'list' => \%list,
'border' => 'red',
'selected' => 1,
'draw_only' => 1);
b<(Interactive)>
($input, $selected) = list_box( 'window' => \$main,
'ypos' => 2,
'xpos' => 5,
'lines' => 10,
'cols' => 25,
'list' => \%list,
'border' => 'green',
'selected' => $last,
'function' => \&clock);Button set
The button function does not produce a derived window, but instead just prints the passed buttons, and handles the key strokes to navigate amongst them, while passing any other keystrokes and the currently selected button. The button set can be rendered either vertically or horizontally, and the keystrokes that can be used for navigation depend upon that.
Key Curses Constant
-------------------------------
left arrow KEY_LEFT
right arrow KEY_RIGHT
up arrow KEY_UP
down arrow KEY_DOWNAll parameters are passed as named parameters:
Parameter Commments
-----------------------------------
window reference
buttons reference
ypos integer, optional,
default is 1
xpos integer, optional,
default is 1
active_button integer, optional
function reference, optional
vertical integer, optional
draw_only integer, optional
default is 0Again, all previously described parameters remain the same.
'buttons' is an array reference with each element a separate button. 'active_button' is the element's positional reference.
If 'vertical' is passed at all, ie., if the key exists, the button set will be rendered as a vertical set.
B<Example (non-Interactive)>
buttons( 'window' => \$win_bar,
'buttons' => \@buttons,
'active_button'=> 2,
'draw_only' => 1);
b<(Interactive)>
($input, $selected) = buttons( 'windows' => \$win_bar,
'buttons' => \@buttons,
'active_button' => $last,
'function' => \&clock);Calendar
The calendar widget creates a fully navigable calendar in a derived, bordered window. The calendar controls its own input until it captures a keystroke it doesn't explicitly handle. In that case, it returns the key.
Key Curses Constant
-------------------------------
left arrow KEY_LEFT
right arrow KEY_RIGHT
up arrow KEY_UP
down arrow KEY_DOWN
home KEY_HOME
page up KEY_PPAGE
page down KEY_NPAGEThe home key, in this case, moves the selected date to the the current date. I've also reserved 't' to do this as well. The page up and down keys move the calendar from month to month.
All parameters are passed as named parameters:
Parameter Commments
-----------------------------------
window reference
ypos integer, optional,
default is 1
xpos integer, optional,
default is 1
date_disp reference
border named colour, optional
default is 'red'
function reference, optional
draw_only integer, optional
default is 0'date_disp' is an array reference that holds the desired date to display. This parameter is required, since this determines the month to display. Should the widget be called in interactive mode, the reference will be modified to display the last date navigated to by the user. The first element, [0], is the day, the second, [1], the month, and the third, [2], the year.
B<Example (non-Interactive)>
calendar( 'window' => \$main,
'date_disp' => \@date,
'border' => 'red',
'draw_only' => 1);
B<(Interactive)>
$input = calendar( 'window' => \$main,
'date_disp' => \@date,
'border' => 'blue',
'function' => \&clock);FUNCTIONS
init_colours
Usage: init_colours()
This function returns nothing but checks first to see if the TERM entry in the termcap database supports colour, and if so, calls the Curses start_color function. After that, it declares a basic colour pair set.
Currently, the colour pairs declared are:
Pair # Foreground, Background
--------------------------------------
1 Blue, Black
2 Cyan, Black
3 Magenta, Black
4 Green, Black
5 Red, Black
6 White, Black
7 Yellow (using A_BOLD), Black
B<Example>
init_colours();select_colour
Usage: select_colour(\$window, colour)
This function sets the character attributes for all subsequent characters to the specified colour, for the specified window. All arguments are required, the first being a scalar reference to the window, and the second a string denoting the desired colour.
Currently, only 'red', 'green', 'blue', and 'yellow' are recognised. These attributes stay in effect until another set is declared, or all attributes are reset via attrset(0).
B<Example>
select_colour(\$main, 'yellow');line_split (not exported by default)
Usage: line_split(string, line_length)
This function returns the submitted string as a list, each element being a separate line. It accounts for not only column limits, but whitespace as well, splitting a sentence by whitespace, so as to not break words.
B<Example>
@lines = line_split($note, 80);HISTORY
See the Changelog for in depth change history. So far, I haven't broken any of the default exported functions, so most scripts should run unmodified.
Significant changes:
line_count deprecated in favour of line_split. The function does less, but runs much more quickly, and now splits text according to white space, as well as column limits.
txt_field functionality expanded, as well as performance improvements, especially with longer text.
AUTHOR
All bug reports, gripes, adulations, and comments can be sent to Arthur Corliss, at corliss@odinicfoundation.org.