Curses::UI::Listbox(3)User Contributed Perl DocumentatioCurses::UI::Listbox(3)NAMECurses::UI::Listbox - Create and manipulate listbox widgets
CLASS HIERARCHY
Curses::UI::Widget
Curses::UI::Searchable
|
+----Curses::UI::Listbox
SYNOPSIS
use Curses::UI;
my $cui = new Curses::UI;
my $win = $cui->add('window_id', 'Window');
my $listbox = $win->add(
'mylistbox', 'Listbox',
-values => [1, 2, 3],
-labels => { 1 => 'One',
2 => 'Two',
3 => 'Three' },
-radio => 1,
);
$listbox->focus();
my $selected = $listbox->get();
DESCRIPTIONCurses::UI::Listbox is a widget that can be used to create a couple of
different kinds of listboxes. These are:
· default listbox
A list of values through which can be browsed. One of these values
can be selected. The selected value will be highlighted. This kind
of listbox looks somewhat like this:
+------+
|One |
|Two |
|Three |
+------+
· multi-select listbox
This is also a list of values, but now more than one value can be
selected at once. This kind of listbox looks somewhat like this:
+----------+
|[X] One |
|[ ] Two |
|[X] Three |
+----------+
· radiobutton listbox
This looks a lot like the default listbox (only one value can be
selected), but now there is clear visual feedback on which value is
selected. Before each value "< >" is printed. If a value is
selected, "<o>" is printed instead. This kind of listbox looks
somewhat like this:
+----------+
|< > One |
|<o> Two |
|< > Three |
+----------+
· Listbox Markup
The listbox supports a primitive markup language to emphasize
entries:
<reverse>reverse text</reverse>
<bold>bold text</bold>
<underline>underlined text</underline>
<blink>blinking text</blink>
<dim>dim text</dim> By using this markup tokens in the values
array, you can make the listbox draw the text in the according way.
To enable the parser, you have to create the listbox with the
-htmltext option.
STANDARD OPTIONS-parent, -x, -y, -width, -height, -pad, -padleft, -padright, -padtop,
-padbottom, -ipad, -ipadleft, -ipadright, -ipadtop, -ipadbottom,
-title, -titlefullwidth, -titlereverse, -onfocus, -onblur
For an explanation of these standard options, see Curses::UI::Widget.
WIDGET-SPECIFIC OPTIONS
· -values < ARRAYREF >
This option sets the values to use. Unless a label is set for the
value (see -labels), this value will be shown in the list.
· -labels < HASHREF >
The keys of this hash reference correspond to the values of the
listbox (see -values). The values of the hash are the labels to
show in the listbox. It's not obligatory to have a label defined
for each value. You may even omit -labels completely.
· -selected < INDEX >
In case the -multi option is not set, INDEX is the index of the
value that should be selected.
In case the -multi option is set, INDEX is a hash reference in
which the keys are the indices of the -values which are selected
and the values are any true value.
· -multi < BOOLEAN >
If BOOLEAN has a true value, the listbox will be a multi-select
listbox (see DESCRIPTION).
· -radio < BOOLEAN >
If BOOLEAN has a true value, the listbox will be a radiobutton
listbox (see DESCRIPTION).
· -wraparound < BOOLEAN >
If BOOLEAN has a true value, wraparound is enabled. This means that
if the listbox is on its last value and a key is pressed to go to
the next value, the first value will be selected. Also the last
value will be selected if this first value is selected and "goto
previous value" is pressed.
· -onchange < CODEREF >
This sets the onChange event handler for the listbox widget. If a
new item is selected, the code in CODEREF will be executed. It
will get the widget reference as its argument.
· -onselchange < CODEREF >
This sets the onSelectionChange event handler for the listbox
widget. If a new item is marked as active CODEREF will be
executed. It will get the widget reference as its argument.
· -htmltext < BOOLEAN >
Make the Listbox parse primitive markup to change the items
appearance. See above.
METHODS
· new ( OPTIONS )
· layout ( )
· draw ( BOOLEAN )
· intellidraw ( )
· focus ( )
· onFocus ( CODEREF )
· onBlur ( CODEREF )
These are standard methods. See Curses::UI::Widget for an
explanation of these.
· get ( )
This method will return the values of the currently selected items
in the list. If the listbox is not a multi-select listbox only one
value will be returned of course.
· id ( )
This method will return the index of the currently selected items
in the list. If the listboy is not a multi-select listbox it will
only return one value.
· get_active_value ( )
This method will return the value of the currently active (i.e
highlighted line).
· get_active_id ( )
This method will return the index of the currently active (i.e
highlighted line).
· set_active_id ( INDEX )
This method will set the currently active (i.e highlighted line).
· set_selection ( LIST )
This method marks the items at the positions specified in LIST as
selected. In a multi-select listbox you can set multiple items with
giving multiple values, in a single-select listbox only the last
item in LIST will be selected
· clear_selection ( )
This method clears the selected objects of a multi and radiobutton
listbox.
· values ( ARRAYREF )
This method sets the values to use.
· insert_at < POS, ARRAYREF|SCALAR >
This method adds ARRAYREF or SCALAR into the list of values at pos.
· labels [ HASHREF ]
This method sets the labels to use.
· add_labels [ HASHREF ]
This method adds the given labels to the already defined ones.
· onChange ( CODEREF )
This method can be used to set the -onchange event handler (see
above) after initialization of the listbox.
· onSelectionChange ( CODEREF )
This method can be used to set the -onselchange event handler (see
above) after initialization of the listbox.
DEFAULT BINDINGS
· <cursor-left>, <h>, <tab>
Call the 'loose-focus' routine. This will have the widget loose its
focus.
· <cursor-right, <l>, <enter>, <space>
Call the 'option-select' routine. This will select the active item
in the listbox.
· <1>, <y>
Call the 'option-check' routine. If the listbox is a multi-select
listbox, the active item will become checked and the next item will
become active.
· <0>, <n>
Call the 'option-uncheck' routine. If the listbox is a multi-select
listbox, the active item will become unchecked and the next item
will become active.
· <cursor-down>, <j>
Call the 'option-next' routine. This will make the next item of the
list active.
· <cursor-up>, <k>
Call the 'option-prev' routine. This will make the previous item of
the list active.
· <page-up>
Call the 'option-prevpage' routine. This will make the item on the
previous page active.
· <page-down>
Call the 'option-nextpage' routine. This will make the item on the
next page active.
· <home>, <CTRL+A>
Call the 'option-first' routine. This will make the first item of
the list active.
· <end>, <CTRL+E>
Call the 'option-last' routine. This will make the last item of the
list active.
· </>
Call the 'search-forward' routine. This will make a 'less'-like
search system appear in the listbox. A searchstring can be entered.
After that the user can search for the next occurance using the 'n'
key or the previous occurance using the 'N' key.
· <?>
Call the 'search-backward' routine. This will do the same as the
'search-forward' routine, only it will search in the opposite
direction.
SEE ALSO
Curses::UI, Curses::UI::Widget, Curses::UI::Common
AUTHOR
Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.
Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
This package is free software and is provided "as is" without express
or implied warranty. It may be used, redistributed and/or modified
under the same terms as perl itself.
perl v5.18.1 2013-10-18 Curses::UI::Listbox(3)