NAME
Curses::Widgets -- Curses-based widgets and functions
Doc/Module Version info
$Id: Widgets.pod,v 0.6 1999/02/02 17:23:50 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_ENDI hope these keys act as one would expect. In addition, the enter key (trapped as "\n") ends the line, and places the cursor on the next line. The tab key (trapped as "\t") causes the widget to return control back to the calling routine, as does any other key not explicitly handled.
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
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'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.
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 0All 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 Red, Black
2 Green, Black
3 Blue, Black
4 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_count
Usage: line_count(string, line_length [, cur_pos] [, \@lines] [, \%ch_x_ln])
This function returns first the number of lines in the string, and secondly, the line that the cursor is one, if the cursor position was passed. The number of lines are determined by accounting for new line characters and the length limit of the lines, as passed in the second argument.
In addition, if passed, the function can modify an array and/or a hash. In the array would be passed the text of each line. In the hash would be passed the number of characters in each line, the key being the line number.
B<Example>
($n_lines, $c_line) = line_count($note, 80, 73, \@lines, \%chxln);HISTORY
This is the second developer's release. No show stopper bugs, everything now works as advertised, but more functionality could be added. And will be, don't worry. :-)
AUTHOR
All bug reports, gripes, adulations, and comments can be sent to Arthur Corliss, at corliss@odinicfoundation.org.