1Curses::UI::Listbox(3)User Contributed Perl DocumentationCurses::UI::Listbox(3)
2
3
4

NAME

6       Curses::UI::Listbox - Create and manipulate listbox widgets
7

CLASS HIERARCHY

9        Curses::UI::Widget
10        Curses::UI::Searchable
11           |
12           +----Curses::UI::Listbox
13

SYNOPSIS

15           use Curses::UI;
16           my $cui = new Curses::UI;
17           my $win = $cui->add('window_id', 'Window');
18
19           my $listbox = $win->add(
20               'mylistbox', 'Listbox',
21               -values    => [1, 2, 3],
22               -labels    => { 1 => 'One',
23                               2 => 'Two',
24                               3 => 'Three' },
25               -radio     => 1,
26           );
27
28           $listbox->focus();
29           my $selected = $listbox->get();
30

DESCRIPTION

32       Curses::UI::Listbox is a widget that can be used to create a couple of
33       different kinds of listboxes. These are:
34
35default listbox
36
37           A list of values through which can be browsed. One of these values
38           can be selected. The selected value will be highlighted. This kind
39           of listbox looks somewhat like this:
40
41            +------+
42            |One   |
43            |Two   |
44            |Three |
45            +------+
46
47multi-select listbox
48
49           This is also a list of values, but now more than one value can be
50           selected at once. This kind of listbox looks somewhat like this:
51
52            +----------+
53            |[X] One   |
54            |[ ] Two   |
55            |[X] Three |
56            +----------+
57
58radiobutton listbox
59
60           This looks a lot like the default listbox (only one value can be
61           selected), but now there is clear visual feedback on which value is
62           selected. Before each value "< >" is printed. If a value is
63           selected, "<o>" is printed instead. This kind of listbox looks
64           somewhat like this:
65
66            +----------+
67            |< > One   |
68            |<o> Two   |
69            |< > Three |
70            +----------+
71
72Listbox Markup
73
74           The listbox supports a primitive markup language to emphasize
75           entries:
76               <reverse>reverse text</reverse>
77               <bold>bold text</bold>
78               <underline>underlined text</underline>
79               <blink>blinking text</blink>
80               <dim>dim text</dim> By using this markup tokens in the values
81           array, you can make the listbox draw the text in the according way.
82           To enable the parser, you have to create the listbox with the
83           -htmltext option.
84

STANDARD OPTIONS

86       -parent, -x, -y, -width, -height, -pad, -padleft, -padright, -padtop,
87       -padbottom, -ipad, -ipadleft, -ipadright, -ipadtop, -ipadbottom,
88       -title, -titlefullwidth, -titlereverse, -onfocus, -onblur
89
90       For an explanation of these standard options, see Curses::UI::Widget.
91

WIDGET-SPECIFIC OPTIONS

93-values < ARRAYREF >
94
95           This option sets the values to use.  Unless a label is set for the
96           value (see -labels), this value will be shown in the list.
97
98-labels < HASHREF >
99
100           The keys of this hash reference correspond to the values of the
101           listbox (see -values). The values of the hash are the labels to
102           show in the listbox. It's not obligatory to have a label defined
103           for each value. You may even omit -labels completely.
104
105-selected < INDEX >
106
107           In case the -multi option is not set, INDEX is the index of the
108           value that should be selected.
109
110           In case the -multi option is set, INDEX is a hash reference in
111           which the keys are the indices of the -values which are selected
112           and the values are any true value.
113
114-multi < BOOLEAN >
115
116           If BOOLEAN has a true value, the listbox will be a multi-select
117           listbox (see DESCRIPTION).
118
119-radio < BOOLEAN >
120
121           If BOOLEAN has a true value, the listbox will be a radiobutton
122           listbox (see DESCRIPTION).
123
124-wraparound < BOOLEAN >
125
126           If BOOLEAN has a true value, wraparound is enabled. This means that
127           if the listbox is on its last value and a key is pressed to go to
128           the next value, the first value will be selected.  Also the last
129           value will be selected if this first value is selected and "goto
130           previous value" is pressed.
131
132-onchange < CODEREF >
133
134           This sets the onChange event handler for the listbox widget.  If a
135           new item is selected, the code in CODEREF will be executed.  It
136           will get the widget reference as its argument.
137
138-onselchange < CODEREF >
139
140           This sets the onSelectionChange event handler for the listbox
141           widget.  If a new item is marked as active CODEREF will be
142           executed.  It will get the widget reference as its argument.
143
144-htmltext < BOOLEAN >
145
146           Make the Listbox parse primitive markup to change the items
147           appearance. See above.
148

METHODS

150new ( OPTIONS )
151
152layout ( )
153
154draw ( BOOLEAN )
155
156intellidraw ( )
157
158focus ( )
159
160onFocus ( CODEREF )
161
162onBlur ( CODEREF )
163
164           These are standard methods. See Curses::UI::Widget for an
165           explanation of these.
166
167get ( )
168
169           This method will return the values of the currently selected items
170           in the list. If the listbox is not a multi-select listbox only one
171           value will be returned of course.
172
173id ( )
174
175           This method will return the index of the currently selected items
176           in the list. If the listboy is not a multi-select listbox it will
177           only return one value.
178
179get_active_value ( )
180
181           This method will return the value of the currently active (i.e
182           highlighted line).
183
184get_active_id ( )
185
186           This method will return the index of the currently active (i.e
187           highlighted line).
188
189set_selection ( LIST )
190
191           This method marks the items at the positions specified in LIST as
192           selected. In a multi-select listbox you can set multiple items with
193           giving multiple values, in a single-select listbox only the last
194           item in LIST will be selected
195
196clear_selection ( )
197
198           This method clears the selected objects of a multi and radiobutton
199           listbox.
200
201values ( ARRAYREF )
202
203           This method sets the values to use.
204
205insert_at < POS, ARRAYREF|SCALAR >
206
207           This method adds ARRAYREF or SCALAR into the list of values at pos.
208
209labels [ HASHREF ]
210
211           This method sets the labels to use.
212
213add_labels [ HASHREF ]
214
215           This method adds the given labels to the already defined ones.
216
217onChange ( CODEREF )
218
219           This method can be used to set the -onchange event handler (see
220           above) after initialization of the listbox.
221
222onSelectionChange ( CODEREF )
223
224           This method can be used to set the -onselchange event handler (see
225           above) after initialization of the listbox.
226

DEFAULT BINDINGS

228       •   <cursor-left>, <h>, <tab>
229
230           Call the 'loose-focus' routine. This will have the widget loose its
231           focus.
232
233       •   <cursor-right, <l>, <enter>, <space>
234
235           Call the 'option-select' routine. This will select the active item
236           in the listbox.
237
238       •   <1>, <y>
239
240           Call the 'option-check' routine. If the listbox is a multi-select
241           listbox, the active item will become checked and the next item will
242           become active.
243
244       •   <0>, <n>
245
246           Call the 'option-uncheck' routine. If the listbox is a multi-select
247           listbox, the active item will become unchecked and the next item
248           will become active.
249
250       •   <cursor-down>, <j>
251
252           Call the 'option-next' routine. This will make the next item of the
253           list active.
254
255       •   <cursor-up>, <k>
256
257           Call the 'option-prev' routine. This will make the previous item of
258           the list active.
259
260       •   <page-up>
261
262           Call the 'option-prevpage' routine. This will make the item on the
263           previous page active.
264
265       •   <page-down>
266
267           Call the 'option-nextpage' routine. This will make the item on the
268           next page active.
269
270       •   <home>, <CTRL+A>
271
272           Call the 'option-first' routine. This will make the first item of
273           the list active.
274
275       •   <end>, <CTRL+E>
276
277           Call the 'option-last' routine. This will make the last item of the
278           list active.
279
280       •   </>
281
282           Call the 'search-forward' routine. This will make a 'less'-like
283           search system appear in the listbox. A searchstring can be entered.
284           After that the user can search for the next occurance using the 'n'
285           key or the previous occurance using the 'N' key.
286
287       •   <?>
288
289           Call the 'search-backward' routine. This will do the same as the
290           'search-forward' routine, only it will search in the opposite
291           direction.
292

SEE ALSO

294       Curses::UI, Curses::UI::Widget, Curses::UI::Common
295

AUTHOR

297       Copyright (c) 2001-2002 Maurice Makaay. All rights reserved.
298
299       Maintained by Marcus Thiesen (marcus@cpan.thiesenweb.de)
300
301       This package is free software and is provided "as is" without express
302       or implied warranty. It may be used, redistributed and/or modified
303       under the same terms as perl itself.
304
305
306
307perl v5.38.0                      2023-07-20            Curses::UI::Listbox(3)
Impressum