]>
Commit | Line | Data |
---|---|---|
a660d684 KB |
1 | \section{\class{wxListBox}}\label{wxlistbox} |
2 | ||
3 | A listbox is used to select one or more of a list of strings. The | |
4 | strings are displayed in a scrolling box, with the selected string(s) | |
5 | marked in reverse video. A listbox can be single selection (if an item | |
6 | is selected, the previous selection is removed) or multiple selection | |
7 | (clicking an item toggles the item on or off independently of other | |
8 | selections). | |
9 | ||
10 | List box elements are numbered from zero. | |
11 | ||
12 | A listbox callback gets an event wxEVT\_COMMAND\_LISTBOX\_SELECT for single clicks, and | |
debe6624 | 13 | wxEVT\_COMMAND\_LISTBOX\_DOUBLE\_CLICKED for double clicks. |
a660d684 KB |
14 | |
15 | \wxheading{Derived from} | |
16 | ||
17 | \helpref{wxControl}{wxcontrol}\\ | |
18 | \helpref{wxWindow}{wxwindow}\\ | |
19 | \helpref{wxEvtHandler}{wxevthandler}\\ | |
20 | \helpref{wxObject}{wxobject} | |
21 | ||
954b8ae6 JS |
22 | \wxheading{Include files} |
23 | ||
24 | <wx/listbox.h> | |
25 | ||
a660d684 KB |
26 | \wxheading{Window styles} |
27 | ||
28 | \twocolwidtha{5cm}% | |
29 | \begin{twocollist}\itemsep=0pt | |
30 | \twocolitem{\windowstyle{wxLB\_SINGLE}}{Single-selection list.} | |
31 | \twocolitem{\windowstyle{wxLB\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple | |
32 | items on and off.} | |
33 | \twocolitem{\windowstyle{wxLB\_EXTENDED}}{Extended-selection list: the user can | |
34 | select multiple items using the SHIFT key and the mouse or special key combinations.} | |
35 | \twocolitem{\windowstyle{wxLB\_HSCROLL}}{Create horizontal scrollbar if contents are too wide (Windows only).} | |
36 | \twocolitem{\windowstyle{wxLB\_ALWAYS\_SB}}{Always show a vertical scrollbar.} | |
37 | \twocolitem{\windowstyle{wxLB\_NEEDED\_SB}}{Only create a vertical scrollbar if needed.} | |
9c884972 | 38 | \twocolitem{\windowstyle{wxLB\_SORT}}{The listbox contents are sorted in alphabetical order. No effect for GTK.} |
a660d684 KB |
39 | \end{twocollist} |
40 | ||
41 | See also \helpref{window styles overview}{windowstyles}. | |
42 | ||
5de76427 JS |
43 | \wxheading{Event handling} |
44 | ||
45 | \twocolwidtha{7cm} | |
46 | \begin{twocollist}\itemsep=0pt | |
47 | \twocolitem{{\bf EVT\_LISTBOX(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_SELECTED event, | |
48 | when an item on the list is selected.} | |
def172b2 | 49 | \twocolitem{{\bf EVT\_LISTBOX\_DCLICK(id, func)}}{Process a wxEVT\_COMMAND\_LISTBOX\_DOUBLECLICKED event, |
5de76427 JS |
50 | when the listbox is doubleclicked.} |
51 | \end{twocollist} | |
52 | ||
a660d684 KB |
53 | \wxheading{See also} |
54 | ||
5de76427 JS |
55 | \helpref{wxChoice}{wxchoice}, \helpref{wxComboBox}{wxcombobox}, \helpref{wxListCtrl}{wxlistctrl}, |
56 | \rtfsp\helpref{wxCommandEvent}{wxcommandevent} | |
a660d684 KB |
57 | |
58 | \latexignore{\rtfignore{\wxheading{Members}}} | |
59 | ||
60 | \membersection{wxListBox::wxListBox}\label{wxlistboxconstr} | |
61 | ||
62 | \func{}{wxListBox}{\void} | |
63 | ||
64 | Default constructor. | |
65 | ||
eaaa6a06 | 66 | \func{}{wxListBox}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
a660d684 | 67 | \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp |
eaaa6a06 JS |
68 | \param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp |
69 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} | |
a660d684 KB |
70 | |
71 | Constructor, creating and showing a list box. | |
72 | ||
73 | \wxheading{Parameters} | |
74 | ||
75 | \docparam{parent}{Parent window. Must not be NULL.} | |
76 | ||
77 | \docparam{id}{Window identifier. A value of -1 indicates a default value.} | |
78 | ||
79 | \docparam{pos}{Window position.} | |
80 | ||
81 | \docparam{size}{Window size. If the default size (-1, -1) is specified then the window is sized | |
82 | appropriately.} | |
83 | ||
84 | \docparam{n}{Number of strings with which to initialise the control.} | |
85 | ||
86 | \docparam{choices}{An array of strings with which to initialise the control.} | |
87 | ||
88 | \docparam{style}{Window style. See \helpref{wxListBox}{wxlistbox}.} | |
89 | ||
90 | \docparam{validator}{Window validator.} | |
91 | ||
92 | \docparam{name}{Window name.} | |
93 | ||
94 | \wxheading{See also} | |
95 | ||
96 | \helpref{wxListBox::Create}{wxlistboxcreate}, \helpref{wxValidator}{wxvalidator} | |
97 | ||
06d20283 RD |
98 | \pythonnote{The wxListBox constructor in wxPython reduces the \tt{n} |
99 | and \tt{choices} arguments are to a single argument, which is | |
100 | a list of strings.} | |
101 | ||
102 | ||
103 | ||
a660d684 KB |
104 | \membersection{wxListBox::\destruct{wxListBox}} |
105 | ||
106 | \func{void}{\destruct{wxListBox}}{\void} | |
107 | ||
108 | Destructor, destroying the list box. | |
109 | ||
110 | \membersection{wxListBox::Append}\label{wxlistboxappend} | |
111 | ||
112 | \func{void}{Append}{\param{const wxString\& }{ item}} | |
113 | ||
114 | Adds the item to the end of the list box. | |
115 | ||
9c884972 | 116 | \func{void}{Append}{\param{const wxString\& }{ item}, \param{void* }{clientData}} |
a660d684 KB |
117 | |
118 | Adds the item to the end of the list box, associating the given data | |
119 | with the item. | |
120 | ||
121 | \wxheading{Parameters} | |
122 | ||
123 | \docparam{item}{String to add.} | |
124 | ||
125 | \docparam{clientData}{Client data to associate with the item.} | |
126 | ||
127 | \membersection{wxListBox::Clear}\label{wxlistboxclear} | |
128 | ||
129 | \func{void}{Clear}{\void} | |
130 | ||
131 | Clears all strings from the list box. | |
132 | ||
133 | \membersection{wxListBox::Create}\label{wxlistboxcreate} | |
134 | ||
eaaa6a06 | 135 | \func{bool}{Create}{\param{wxWindow*}{ parent}, \param{wxWindowID}{ id},\rtfsp |
a660d684 | 136 | \param{const wxPoint\&}{ pos = wxDefaultPosition}, \param{const wxSize\&}{ size = wxDefaultSize},\rtfsp |
eaaa6a06 JS |
137 | \param{int}{ n}, \param{const wxString }{choices[] = NULL},\rtfsp |
138 | \param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = ``listBox"}} | |
a660d684 KB |
139 | |
140 | Creates the listbox for two-step construction. See \helpref{wxListBox::wxListBox}{wxlistboxconstr}\rtfsp | |
141 | for further details. | |
142 | ||
143 | \membersection{wxListBox::Delete}\label{wxlistboxdelete} | |
144 | ||
145 | \func{void}{Delete}{\param{int}{ n}} | |
146 | ||
147 | Deletes an item from the listbox. | |
148 | ||
149 | \wxheading{Parameters} | |
150 | ||
151 | \docparam{n}{The zero-based item index.} | |
152 | ||
153 | \membersection{wxListBox::Deselect}\label{wxlistboxdeselect} | |
154 | ||
155 | \func{void}{Deselect}{\param{int}{ n}} | |
156 | ||
157 | Deselects an item in the list box. | |
158 | ||
159 | \wxheading{Parameters} | |
160 | ||
161 | \docparam{n}{The zero-based item to deselect.} | |
162 | ||
163 | \wxheading{Remarks} | |
164 | ||
165 | This applies to multiple selection listboxes only. | |
166 | ||
167 | \membersection{wxListBox::FindString}\label{wxlistboxfindstring} | |
168 | ||
169 | \func{int}{FindString}{\param{const wxString\& }{string}} | |
170 | ||
171 | Finds an item matching the given string. | |
172 | ||
173 | \wxheading{Parameters} | |
174 | ||
175 | \docparam{string}{String to find.} | |
176 | ||
177 | \wxheading{Return value} | |
178 | ||
179 | The zero-based position of the item, or -1 if the string was not found. | |
180 | ||
181 | \membersection{wxListBox::GetClientData}\label{wxlistboxgetclientdata} | |
182 | ||
9c884972 | 183 | \constfunc{void*}{GetClientData}{\param{int}{ n}} |
a660d684 KB |
184 | |
185 | Returns a pointer to the client data associated with the given item (if any). | |
186 | ||
187 | \wxheading{Parameters} | |
188 | ||
189 | \docparam{n}{The zero-based position of the item.} | |
190 | ||
191 | \wxheading{Return value} | |
192 | ||
193 | A pointer to the client data, or NULL if not present. | |
194 | ||
195 | \membersection{wxListBox::GetSelection}\label{wxlistboxgetselection} | |
196 | ||
197 | \constfunc{int}{GetSelection}{\void} | |
198 | ||
199 | Gets the position of the selected item. | |
200 | ||
201 | \wxheading{Return value} | |
202 | ||
203 | The position of the current selection. | |
204 | ||
205 | \wxheading{Remarks} | |
206 | ||
207 | Applicable to single selection list boxes only. | |
208 | ||
209 | \wxheading{See also} | |
210 | ||
211 | \helpref{wxListBox::SetSelection}{wxlistboxsetselection},\rtfsp | |
212 | \helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp | |
213 | \helpref{wxListBox::GetSelections}{wxlistboxgetselections} | |
214 | ||
215 | \membersection{wxListBox::GetSelections}\label{wxlistboxgetselections} | |
216 | ||
9c884972 | 217 | \constfunc{int}{GetSelections}{\param{wxArrayInt& }{selections}} |
a660d684 | 218 | |
fd9811b1 | 219 | Fill an array of ints with the positions of the currently selected items. |
a660d684 KB |
220 | |
221 | \wxheading{Parameters} | |
222 | ||
fd9811b1 | 223 | \docparam{selections}{A reference to an wxArrayInt instance that is used to store the result of the query.} |
a660d684 KB |
224 | |
225 | \wxheading{Return value} | |
226 | ||
227 | The number of selections. | |
228 | ||
229 | \wxheading{Remarks} | |
230 | ||
231 | Use this with a multiple selection listbox. | |
232 | ||
233 | \wxheading{See also} | |
234 | ||
235 | \helpref{wxListBox::GetSelection}{wxlistboxgetselection},\rtfsp | |
236 | \helpref{wxListBox::GetStringSelection}{wxlistboxgetstringselection},\rtfsp | |
237 | \helpref{wxListBox::SetSelection}{wxlistboxsetselection} | |
238 | ||
f899db6d RD |
239 | \pythonnote{The wxPython version of this method takes no parameters |
240 | and returns a tuple of the selected items.} | |
241 | ||
a660d684 KB |
242 | \membersection{wxListBox::GetString}\label{wxlistboxgetstring} |
243 | ||
eaaa6a06 | 244 | \constfunc{wxString}{GetString}{\param{int}{ n}} |
a660d684 KB |
245 | |
246 | Returns the string at the given position. | |
247 | ||
248 | \wxheading{Parameters} | |
249 | ||
250 | \docparam{n}{The zero-based position.} | |
251 | ||
252 | \wxheading{Return value} | |
253 | ||
254 | The string, or an empty string if the position was invalid. | |
255 | ||
256 | \membersection{wxListBox::GetStringSelection}\label{wxlistboxgetstringselection} | |
257 | ||
258 | \constfunc{wxString}{GetStringSelection}{\void} | |
259 | ||
260 | Gets the selected string - for single selection list boxes only. This | |
261 | must be copied by the calling program if long term use is to be made of | |
262 | it. | |
263 | ||
264 | \wxheading{See also} | |
265 | ||
266 | \helpref{wxListBox::GetSelection}{wxlistboxgetselection},\rtfsp | |
267 | \helpref{wxListBox::GetSelections}{wxlistboxgetselections},\rtfsp | |
268 | \helpref{wxListBox::SetSelection}{wxlistboxsetselection} | |
269 | ||
81108288 VZ |
270 | \membersection{wxListBox::InsertItems}\label{wxlistboxinsertitems} |
271 | ||
272 | \func{void}{InsertItems}{\param{int}{ nItems}, \param{const wxString}{ items}, \param{int}{ pos}} | |
273 | ||
274 | Insert the given number of strings before the specified position. | |
275 | ||
276 | \wxheading{Parameters} | |
277 | ||
278 | \docparam{nItems}{Number of items in the array {\it items}} | |
279 | ||
280 | \docparam{items}{Labels of items to be inserted} | |
281 | ||
282 | \docparam{pos}{Position before which to insert the items: for example, if {\it pos} is 0 the items | |
283 | will be inserted in the beginning of the listbox} | |
284 | ||
a660d684 KB |
285 | \membersection{wxListBox::Number}\label{wxlistboxnumber} |
286 | ||
287 | \constfunc{int}{Number}{\void} | |
288 | ||
289 | Returns the number of items in the listbox. | |
290 | ||
291 | \membersection{wxListBox::Selected}\label{wxlistboxselected} | |
292 | ||
eaaa6a06 | 293 | \constfunc{bool}{Selected}{\param{int}{ n}} |
a660d684 KB |
294 | |
295 | Determines whether an item is selected. | |
296 | ||
297 | \wxheading{Parameters} | |
298 | ||
299 | \docparam{n}{The zero-based item index.} | |
300 | ||
301 | \wxheading{Return value} | |
302 | ||
303 | TRUE if the given item is selected, FALSE otherwise. | |
304 | ||
305 | \membersection{wxListBox::Set}\label{wxlistboxset} | |
306 | ||
eaaa6a06 | 307 | \func{void}{Set}{\param{int}{ n}, \param{const wxString*}{ choices}} |
a660d684 | 308 | |
9c884972 | 309 | Clears the list box and adds the given strings. Not implemented for GTK. |
a660d684 KB |
310 | |
311 | \wxheading{Parameters} | |
312 | ||
313 | \docparam{n}{The number of strings to set.} | |
314 | ||
315 | \docparam{choices}{An array of strings to set.} | |
316 | ||
317 | \wxheading{Remarks} | |
318 | ||
319 | Deallocate the array from the calling program | |
320 | after this function has been called. | |
321 | ||
322 | \membersection{wxListBox::SetClientData}\label{wxlistboxsetclientdata} | |
323 | ||
9c884972 | 324 | \func{void}{SetClientData}{\param{int}{ n}, \param{void* }{data}} |
a660d684 KB |
325 | |
326 | Associates the given client data pointer with the given item. | |
327 | ||
328 | \wxheading{Parameters} | |
329 | ||
330 | \docparam{n}{The zero-based item index.} | |
331 | ||
332 | \docparam{data}{The client data to associate with the item.} | |
333 | ||
334 | \membersection{wxListBox::SetFirstItem}\label{wxlistboxsetfirstitem} | |
335 | ||
336 | \func{void}{SetFirstItem}{\param{int}{ n}} | |
337 | ||
338 | \func{void}{SetFirstItem}{\param{const wxString\& }{string}} | |
339 | ||
953704c1 | 340 | Set the specified item to be the first visible item. Windows only. |
a660d684 KB |
341 | |
342 | \wxheading{Parameters} | |
343 | ||
344 | \docparam{n}{The zero-based item index.} | |
345 | ||
346 | \docparam{string}{The string that should be visible.} | |
347 | ||
348 | \membersection{wxListBox::SetSelection}\label{wxlistboxsetselection} | |
349 | ||
eaaa6a06 | 350 | \func{void}{SetSelection}{\param{int}{ n}, \param{const bool }{select = TRUE}} |
a660d684 | 351 | |
953704c1 RR |
352 | Selects or deselects the given item. This does not cause a |
353 | wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted. | |
a660d684 KB |
354 | |
355 | \wxheading{Parameters} | |
356 | ||
357 | \docparam{n}{The zero-based item index.} | |
358 | ||
359 | \docparam{select}{If TRUE, will select the item. If FALSE, will deselect it.} | |
360 | ||
361 | \membersection{wxListBox::SetString}\label{wxlistboxsetstring} | |
362 | ||
eaaa6a06 | 363 | \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}} |
a660d684 KB |
364 | |
365 | Sets the string value of an item. | |
366 | ||
367 | \wxheading{Parameters} | |
368 | ||
369 | \docparam{n}{The zero-based item index.} | |
370 | ||
371 | \docparam{string}{The string to set.} | |
372 | ||
373 | \membersection{wxListBox::SetStringSelection}\label{wxlistboxsetstringselection} | |
374 | ||
375 | \func{void}{SetStringSelection}{\param{const wxString\& }{ string}, \param{const bool}{ select = TRUE}} | |
376 | ||
953704c1 RR |
377 | Sets the current selection. This does not cause a |
378 | wxEVT\_COMMAND\_LISTBOX\_SELECT event to get emitted. | |
a660d684 KB |
379 | |
380 | \wxheading{Parameters} | |
381 | ||
382 | \docparam{string}{The item to select.} | |
383 | ||
384 | \docparam{select}{If TRUE, will select the item. If FALSE, will deselect it.} | |
385 |