1Curses::UI::Listbox(3)User Contributed Perl DocumentationCurses::UI::Listbox(3)
2
3
4
6 Curses::UI::Listbox - Create and manipulate listbox widgets
7
9 Curses::UI::Widget
10 Curses::UI::Searchable
11 |
12 +----Curses::UI::Listbox
13
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
32 Curses::UI::Listbox is a widget that can be used to create a couple of
33 different kinds of listboxes. These are:
34
35 • default 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
47 • multi-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
58 • radiobutton 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
72 • Listbox 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
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
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
150 • new ( OPTIONS )
151
152 • layout ( )
153
154 • draw ( BOOLEAN )
155
156 • intellidraw ( )
157
158 • focus ( )
159
160 • onFocus ( CODEREF )
161
162 • onBlur ( CODEREF )
163
164 These are standard methods. See Curses::UI::Widget for an
165 explanation of these.
166
167 • get ( )
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
173 • id ( )
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
179 • get_active_value ( )
180
181 This method will return the value of the currently active (i.e
182 highlighted line).
183
184 • get_active_id ( )
185
186 This method will return the index of the currently active (i.e
187 highlighted line).
188
189 • set_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
196 • clear_selection ( )
197
198 This method clears the selected objects of a multi and radiobutton
199 listbox.
200
201 • values ( ARRAYREF )
202
203 This method sets the values to use.
204
205 • insert_at < POS, ARRAYREF|SCALAR >
206
207 This method adds ARRAYREF or SCALAR into the list of values at pos.
208
209 • labels [ HASHREF ]
210
211 This method sets the labels to use.
212
213 • add_labels [ HASHREF ]
214
215 This method adds the given labels to the already defined ones.
216
217 • onChange ( CODEREF )
218
219 This method can be used to set the -onchange event handler (see
220 above) after initialization of the listbox.
221
222 • onSelectionChange ( CODEREF )
223
224 This method can be used to set the -onselchange event handler (see
225 above) after initialization of the listbox.
226
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
294 Curses::UI, Curses::UI::Widget, Curses::UI::Common
295
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.36.0 2022-07-22 Curses::UI::Listbox(3)