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. Another way of intercepting
14 double clicks is to override
\helpref{wxWindow::OnDefaultAction
}{wxwindowondefaultaction
}.
16 \wxheading{Derived from
}
18 \helpref{wxControl
}{wxcontrol
}\\
19 \helpref{wxWindow
}{wxwindow
}\\
20 \helpref{wxEvtHandler
}{wxevthandler
}\\
21 \helpref{wxObject
}{wxobject
}
23 \wxheading{Window styles
}
26 \begin{twocollist
}\itemsep=
0pt
27 \twocolitem{\windowstyle{wxLB
\_SINGLE}}{Single-selection list.
}
28 \twocolitem{\windowstyle{wxLB
\_MULTIPLE}}{Multiple-selection list: the user can toggle multiple
30 \twocolitem{\windowstyle{wxLB
\_EXTENDED}}{Extended-selection list: the user can
31 select multiple items using the SHIFT key and the mouse or special key combinations.
}
32 \twocolitem{\windowstyle{wxLB
\_HSCROLL}}{Create horizontal scrollbar if contents are too wide (Windows only).
}
33 \twocolitem{\windowstyle{wxLB
\_ALWAYS\_SB}}{Always show a vertical scrollbar.
}
34 \twocolitem{\windowstyle{wxLB
\_NEEDED\_SB}}{Only create a vertical scrollbar if needed.
}
35 \twocolitem{\windowstyle{wxLB
\_SORT}}{The listbox contents are sorted in alphabetical order.
}
38 See also
\helpref{window styles overview
}{windowstyles
}.
42 \helpref{wxChoice
}{wxchoice
},
\helpref{wxComboBox
}{wxcombobox
},
\helpref{wxListCtrl
}{wxlistctrl
}
44 \latexignore{\rtfignore{\wxheading{Members
}}}
46 \membersection{wxListBox::wxListBox
}\label{wxlistboxconstr
}
48 \func{}{wxListBox
}{\void}
52 \func{}{wxListBox
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
53 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
54 \param{int
}{ n
},
\param{const wxString
}{choices
[] = NULL
},
\rtfsp
55 \param{long
}{ style =
0},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listBox"
}}
57 Constructor, creating and showing a list box.
59 \wxheading{Parameters
}
61 \docparam{parent
}{Parent window. Must not be NULL.
}
63 \docparam{id
}{Window identifier. A value of -
1 indicates a default value.
}
65 \docparam{pos
}{Window position.
}
67 \docparam{size
}{Window size. If the default size (-
1, -
1) is specified then the window is sized
70 \docparam{n
}{Number of strings with which to initialise the control.
}
72 \docparam{choices
}{An array of strings with which to initialise the control.
}
74 \docparam{style
}{Window style. See
\helpref{wxListBox
}{wxlistbox
}.
}
76 \docparam{validator
}{Window validator.
}
78 \docparam{name
}{Window name.
}
82 \helpref{wxListBox::Create
}{wxlistboxcreate
},
\helpref{wxValidator
}{wxvalidator
}
84 \membersection{wxListBox::
\destruct{wxListBox
}}
86 \func{void
}{\destruct{wxListBox
}}{\void}
88 Destructor, destroying the list box.
90 \membersection{wxListBox::Append
}\label{wxlistboxappend
}
92 \func{void
}{Append
}{\param{const wxString\&
}{ item
}}
94 Adds the item to the end of the list box.
96 \func{void
}{Append
}{\param{const wxString\&
}{ item
},
\param{char*
}{clientData
}}
98 Adds the item to the end of the list box, associating the given data
101 \wxheading{Parameters
}
103 \docparam{item
}{String to add.
}
105 \docparam{clientData
}{Client data to associate with the item.
}
107 \membersection{wxListBox::Clear
}\label{wxlistboxclear
}
109 \func{void
}{Clear
}{\void}
111 Clears all strings from the list box.
113 \membersection{wxListBox::Create
}\label{wxlistboxcreate
}
115 \func{bool
}{Create
}{\param{wxWindow*
}{ parent
},
\param{wxWindowID
}{ id
},
\rtfsp
116 \param{const wxPoint\&
}{ pos = wxDefaultPosition
},
\param{const wxSize\&
}{ size = wxDefaultSize
},
\rtfsp
117 \param{int
}{ n
},
\param{const wxString
}{choices
[] = NULL
},
\rtfsp
118 \param{long
}{ style =
0},
\param{const wxValidator\&
}{validator = wxDefaultValidator
},
\param{const wxString\&
}{name = ``listBox"
}}
120 Creates the listbox for two-step construction. See
\helpref{wxListBox::wxListBox
}{wxlistboxconstr
}\rtfsp
123 \membersection{wxListBox::Delete
}\label{wxlistboxdelete
}
125 \func{void
}{Delete
}{\param{int
}{ n
}}
127 Deletes an item from the listbox.
129 \wxheading{Parameters
}
131 \docparam{n
}{The zero-based item index.
}
133 \membersection{wxListBox::Deselect
}\label{wxlistboxdeselect
}
135 \func{void
}{Deselect
}{\param{int
}{ n
}}
137 Deselects an item in the list box.
139 \wxheading{Parameters
}
141 \docparam{n
}{The zero-based item to deselect.
}
145 This applies to multiple selection listboxes only.
147 \membersection{wxListBox::FindString
}\label{wxlistboxfindstring
}
149 \func{int
}{FindString
}{\param{const wxString\&
}{string
}}
151 Finds an item matching the given string.
153 \wxheading{Parameters
}
155 \docparam{string
}{String to find.
}
157 \wxheading{Return value
}
159 The zero-based position of the item, or -
1 if the string was not found.
161 \membersection{wxListBox::GetClientData
}\label{wxlistboxgetclientdata
}
163 \constfunc{char*
}{GetClientData
}{\param{int
}{ n
}}
165 Returns a pointer to the client data associated with the given item (if any).
167 \wxheading{Parameters
}
169 \docparam{n
}{The zero-based position of the item.
}
171 \wxheading{Return value
}
173 A pointer to the client data, or NULL if not present.
175 \membersection{wxListBox::GetSelection
}\label{wxlistboxgetselection
}
177 \constfunc{int
}{GetSelection
}{\void}
179 Gets the position of the selected item.
181 \wxheading{Return value
}
183 The position of the current selection.
187 Applicable to single selection list boxes only.
191 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
},
\rtfsp
192 \helpref{wxListBox::GetStringSelection
}{wxlistboxgetstringselection
},
\rtfsp
193 \helpref{wxListBox::GetSelections
}{wxlistboxgetselections
}
195 \membersection{wxListBox::GetSelections
}\label{wxlistboxgetselections
}
197 \constfunc{int
}{GetSelections
}{\param{int **
}{selections
}}
199 Gets an array containing the positions of the selected strings.
201 \wxheading{Parameters
}
203 \docparam{selections
}{A pointer to an integer array, which will be allocated by the function if
204 selects are present. Do not deallocate the returned array - it will be deallocated by the listbox.
}
206 \wxheading{Return value
}
208 The number of selections.
212 Use this with a multiple selection listbox.
216 \helpref{wxListBox::GetSelection
}{wxlistboxgetselection
},
\rtfsp
217 \helpref{wxListBox::GetStringSelection
}{wxlistboxgetstringselection
},
\rtfsp
218 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
}
220 \membersection{wxListBox::GetString
}\label{wxlistboxgetstring
}
222 \constfunc{wxString
}{GetString
}{\param{int
}{ n
}}
224 Returns the string at the given position.
226 \wxheading{Parameters
}
228 \docparam{n
}{The zero-based position.
}
230 \wxheading{Return value
}
232 The string, or an empty string if the position was invalid.
234 \membersection{wxListBox::GetStringSelection
}\label{wxlistboxgetstringselection
}
236 \constfunc{wxString
}{GetStringSelection
}{\void}
238 Gets the selected string - for single selection list boxes only. This
239 must be copied by the calling program if long term use is to be made of
244 \helpref{wxListBox::GetSelection
}{wxlistboxgetselection
},
\rtfsp
245 \helpref{wxListBox::GetSelections
}{wxlistboxgetselections
},
\rtfsp
246 \helpref{wxListBox::SetSelection
}{wxlistboxsetselection
}
248 \membersection{wxListBox::Number
}\label{wxlistboxnumber
}
250 \constfunc{int
}{Number
}{\void}
252 Returns the number of items in the listbox.
254 \membersection{wxListBox::Selected
}\label{wxlistboxselected
}
256 \constfunc{bool
}{Selected
}{\param{int
}{ n
}}
258 Determines whether an item is selected.
260 \wxheading{Parameters
}
262 \docparam{n
}{The zero-based item index.
}
264 \wxheading{Return value
}
266 TRUE if the given item is selected, FALSE otherwise.
268 \membersection{wxListBox::Set
}\label{wxlistboxset
}
270 \func{void
}{Set
}{\param{int
}{ n
},
\param{const wxString*
}{ choices
}}
272 Clears the list box and adds the given strings.
274 \wxheading{Parameters
}
276 \docparam{n
}{The number of strings to set.
}
278 \docparam{choices
}{An array of strings to set.
}
282 Deallocate the array from the calling program
283 after this function has been called.
285 \membersection{wxListBox::SetClientData
}\label{wxlistboxsetclientdata
}
287 \func{void
}{SetClientData
}{\param{int
}{ n
},
\param{char*
}{data
}}
289 Associates the given client data pointer with the given item.
291 \wxheading{Parameters
}
293 \docparam{n
}{The zero-based item index.
}
295 \docparam{data
}{The client data to associate with the item.
}
297 \membersection{wxListBox::SetFirstItem
}\label{wxlistboxsetfirstitem
}
299 \func{void
}{SetFirstItem
}{\param{int
}{ n
}}
301 \func{void
}{SetFirstItem
}{\param{const wxString\&
}{string
}}
303 Set the specified item to be the first visible item.
305 \wxheading{Parameters
}
307 \docparam{n
}{The zero-based item index.
}
309 \docparam{string
}{The string that should be visible.
}
311 \membersection{wxListBox::SetSelection
}\label{wxlistboxsetselection
}
313 \func{void
}{SetSelection
}{\param{int
}{ n
},
\param{const bool
}{select = TRUE
}}
315 Selects or deselects the given item.
317 \wxheading{Parameters
}
319 \docparam{n
}{The zero-based item index.
}
321 \docparam{select
}{If TRUE, will select the item. If FALSE, will deselect it.
}
323 \membersection{wxListBox::SetString
}\label{wxlistboxsetstring
}
325 \func{void
}{SetString
}{\param{int
}{ n
},
\param{const wxString\&
}{ string
}}
327 Sets the string value of an item.
329 \wxheading{Parameters
}
331 \docparam{n
}{The zero-based item index.
}
333 \docparam{string
}{The string to set.
}
335 \membersection{wxListBox::SetStringSelection
}\label{wxlistboxsetstringselection
}
337 \func{void
}{SetStringSelection
}{\param{const wxString\&
}{ string
},
\param{const bool
}{ select = TRUE
}}
339 Sets the current selection.
341 \wxheading{Parameters
}
343 \docparam{string
}{The item to select.
}
345 \docparam{select
}{If TRUE, will select the item. If FALSE, will deselect it.
}