1 \section{\class{wxListBox
}}\label{wxlistbox
}
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
10 List box elements are numbered from zero.
12 A listbox callback gets an event wxEVT
\_COMMAND\_LISTBOX\_SELECT for single clicks, and
13 wxEVT
\_COMMAND\_LISTBOX\_DOUBLE\_CLICKED for double clicks.
15 \wxheading{Derived from
}
17 \helpref{wxControl
}{wxcontrol
}\\
18 \helpref{wxWindow
}{wxwindow
}\\
19 \helpref{wxEvtHandler
}{wxevthandler
}\\
20 \helpref{wxObject
}{wxobject
}
22 \wxheading{Include files
}
26 \wxheading{Window styles
}
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
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.
}
38 \twocolitem{\windowstyle{wxLB
\_SORT}}{The listbox contents are sorted in alphabetical order.
}
41 See also
\helpref{window styles overview
}{windowstyles
}.
43 \wxheading{Event handling
}
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.
}
49 \twocolitem{{\bf EVT
\_LISTBOX\_DCLICK(id, func)
}}{Process a wxEVT
\_COMMAND\_LISTBOX\_DOUBLECLICKED event,
50 when the listbox is doubleclicked.
}
55 \helpref{wxChoice
}{wxchoice
},
\helpref{wxComboBox
}{wxcombobox
},
\helpref{wxListCtrl
}{wxlistctrl
},
56 \rtfsp\helpref{wxCommandEvent
}{wxcommandevent
}
58 \latexignore{\rtfignore{\wxheading{Members
}}}
60 \membersection{wxListBox::wxListBox
}\label{wxlistboxconstr
}
62 \func{}{wxListBox
}{\void}
66 \func{}{wxListBox
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
67 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
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"
}}
71 Constructor, creating and showing a list box.
73 \wxheading{Parameters
}
75 \docparam{parent
}{Parent window. Must not be NULL.
}
77 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
79 \docparam{pos
}{Window position.
}
81 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
84 \docparam{n
}{Number of strings with which to initialise the control.
}
86 \docparam{choices
}{An array of strings with which to initialise the control.
}
88 \docparam{style
}{Window style. See
\helpref{wxListBox
}{wxlistbox
}.
}
90 \docparam{validator
}{Window validator.
}
92 \docparam{name
}{Window name.
}
96 \helpref{wxListBox::Create
}{wxlistboxcreate
},
\helpref{wxValidator
}{wxvalidator
}
98 \membersection{wxListBox::
\destruct{wxListBox
}}
100 \func{void
}{\destruct{wxListBox
}}{\void}
102 Destructor, destroying the list box.
104 \membersection{wxListBox::Append
}\label{wxlistboxappend
}
106 \func{void
}{Append
}{\param{const wxString\&
}{ item
}}
108 Adds the item to the end of the list box.
110 \func{void
}{Append
}{\param{const wxString\&
}{ item
},
\param{char*
}{clientData
}}
112 Adds the item to the end of the list box, associating the given data
115 \wxheading{Parameters
}
117 \docparam{item
}{String to add.
}
119 \docparam{clientData
}{Client data to associate with the item.
}
121 \membersection{wxListBox::Clear
}\label{wxlistboxclear
}
123 \func{void
}{Clear
}{\void}
125 Clears all strings from the list box.
127 \membersection{wxListBox::Create
}\label{wxlistboxcreate
}
129 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
130 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
131 \param{int
}{ n
},
\param{const wxString
}{choices
[] = NULL
},
\rtfsp
132 \param{long
}{ style =
0},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listBox"
}}
134 Creates the listbox for two-step construction. See
\helpref{wxListBox::wxListBox
}{wxlistboxconstr
}\rtfsp
137 \membersection{wxListBox::Delete
}\label{wxlistboxdelete
}
139 \func{void
}{Delete
}{\param{int
}{ n
}}
141 Deletes an item from the listbox.
143 \wxheading{Parameters
}
145 \docparam{n
}{The zero-based item index.
}
147 \membersection{wxListBox::Deselect
}\label{wxlistboxdeselect
}
149 \func{void
}{Deselect
}{\param{int
}{ n
}}
151 Deselects an item in the list box.
153 \wxheading{Parameters
}
155 \docparam{n
}{The zero-based item to deselect.
}
159 This applies to multiple selection listboxes only.
161 \membersection{wxListBox::FindString
}\label{wxlistboxfindstring
}
163 \func{int
}{FindString
}{\param{const wxString\&
}{string
}}
165 Finds an item matching the given string.
167 \wxheading{Parameters
}
169 \docparam{string
}{String to find.
}
171 \wxheading{Return value
}
173 The zero-based position of the item, or -
1 if the string was not found.
175 \membersection{wxListBox::GetClientData
}\label{wxlistboxgetclientdata
}
177 \constfunc{char*
}{GetClientData
}{\param{int
}{ n
}}
179 Returns a pointer to the client data associated with the given item (if any).
181 \wxheading{Parameters
}
183 \docparam{n
}{The zero-based position of the item.
}
185 \wxheading{Return value
}
187 A pointer to the client data, or NULL if not present.
189 \membersection{wxListBox::GetSelection
}\label{wxlistboxgetselection
}
191 \constfunc{int
}{GetSelection
}{\void}
193 Gets the position of the selected item.
195 \wxheading{Return value
}
197 The position of the current selection.
201 Applicable to single selection list boxes only.
205 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
},
\rtfsp
206 \helpref{wxListBox::GetStringSelection
}{wxlistboxgetstringselection
},
\rtfsp
207 \helpref{wxListBox::GetSelections
}{wxlistboxgetselections
}
209 \membersection{wxListBox::GetSelections
}\label{wxlistboxgetselections
}
211 \constfunc{int
}{GetSelections
}{\param{int **
}{selections
}}
213 Gets an array containing the positions of the selected strings.
215 \wxheading{Parameters
}
217 \docparam{selections
}{A pointer to an integer array, which will be allocated by the function if
218 selects are present. Do not deallocate the returned array - it will be deallocated by the listbox.
}
220 \wxheading{Return value
}
222 The number of selections.
226 Use this with a multiple selection listbox.
230 \helpref{wxListBox::GetSelection
}{wxlistboxgetselection
},
\rtfsp
231 \helpref{wxListBox::GetStringSelection
}{wxlistboxgetstringselection
},
\rtfsp
232 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
}
234 \membersection{wxListBox::GetString
}\label{wxlistboxgetstring
}
236 \constfunc{wxString
}{GetString
}{\param{int
}{ n
}}
238 Returns the string at the given position.
240 \wxheading{Parameters
}
242 \docparam{n
}{The zero-based position.
}
244 \wxheading{Return value
}
246 The string, or an empty string if the position was invalid.
248 \membersection{wxListBox::GetStringSelection
}\label{wxlistboxgetstringselection
}
250 \constfunc{wxString
}{GetStringSelection
}{\void}
252 Gets the selected string - for single selection list boxes only. This
253 must be copied by the calling program if long term use is to be made of
258 \helpref{wxListBox::GetSelection
}{wxlistboxgetselection
},
\rtfsp
259 \helpref{wxListBox::GetSelections
}{wxlistboxgetselections
},
\rtfsp
260 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
}
262 \membersection{wxListBox::Number
}\label{wxlistboxnumber
}
264 \constfunc{int
}{Number
}{\void}
266 Returns the number of items in the listbox.
268 \membersection{wxListBox::Selected
}\label{wxlistboxselected
}
270 \constfunc{bool
}{Selected
}{\param{int
}{ n
}}
272 Determines whether an item is selected.
274 \wxheading{Parameters
}
276 \docparam{n
}{The zero-based item index.
}
278 \wxheading{Return value
}
280 TRUE if the given item is selected, FALSE otherwise.
282 \membersection{wxListBox::Set
}\label{wxlistboxset
}
284 \func{void
}{Set
}{\param{int
}{ n
},
\param{const wxString*
}{ choices
}}
286 Clears the list box and adds the given strings.
288 \wxheading{Parameters
}
290 \docparam{n
}{The number of strings to set.
}
292 \docparam{choices
}{An array of strings to set.
}
296 Deallocate the array from the calling program
297 after this function has been called.
299 \membersection{wxListBox::SetClientData
}\label{wxlistboxsetclientdata
}
301 \func{void
}{SetClientData
}{\param{int
}{ n
},
\param{char*
}{data
}}
303 Associates the given client data pointer with the given item.
305 \wxheading{Parameters
}
307 \docparam{n
}{The zero-based item index.
}
309 \docparam{data
}{The client data to associate with the item.
}
311 \membersection{wxListBox::SetFirstItem
}\label{wxlistboxsetfirstitem
}
313 \func{void
}{SetFirstItem
}{\param{int
}{ n
}}
315 \func{void
}{SetFirstItem
}{\param{const wxString\&
}{string
}}
317 Set the specified item to be the first visible item.
319 \wxheading{Parameters
}
321 \docparam{n
}{The zero-based item index.
}
323 \docparam{string
}{The string that should be visible.
}
325 \membersection{wxListBox::SetSelection
}\label{wxlistboxsetselection
}
327 \func{void
}{SetSelection
}{\param{int
}{ n
},
\param{const bool
}{select = TRUE
}}
329 Selects or deselects the given item.
331 \wxheading{Parameters
}
333 \docparam{n
}{The zero-based item index.
}
335 \docparam{select
}{If TRUE, will select the item. If FALSE, will deselect it.
}
337 \membersection{wxListBox::SetString
}\label{wxlistboxsetstring
}
339 \func{void
}{SetString
}{\param{int
}{ n
},
\param{const wxString\&
}{ string
}}
341 Sets the string value of an item.
343 \wxheading{Parameters
}
345 \docparam{n
}{The zero-based item index.
}
347 \docparam{string
}{The string to set.
}
349 \membersection{wxListBox::SetStringSelection
}\label{wxlistboxsetstringselection
}
351 \func{void
}{SetStringSelection
}{\param{const wxString\&
}{ string
},
\param{const bool
}{ select = TRUE
}}
353 Sets the current selection.
355 \wxheading{Parameters
}
357 \docparam{string
}{The item to select.
}
359 \docparam{select
}{If TRUE, will select the item. If FALSE, will deselect it.
}