]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/ctrlsub.tex
document GetAnimation() (patch 1695722)
[wxWidgets.git] / docs / latex / wx / ctrlsub.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2%% Name: ctrlsub.tex
3%% Purpose: wxControlWithItems documentation
4%% Author: Vadim Zeitlin
5%% Modified by:
6%% Created: 01.01.03
7%% RCS-ID: $Id$
8%% Copyright: (c) 2003 Vadim Zeitlin
9%% License: wxWindows license
10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12\section{\class{wxControlWithItems}}\label{wxcontrolwithitems}
13
14This class is an abstract base class for some wxWidgets controls which contain
15several items, such as \helpref{wxListBox}{wxlistbox} and
16\helpref{wxCheckListBox}{wxchecklistbox} derived from it,
17\helpref{wxChoice}{wxchoice} and \helpref{wxComboBox}{wxcombobox}.
18
19It defines the methods for accessing the controls items and although each of
20the derived classes implements them differently, they still all conform to the
21same interface.
22
23The items in a wxControlWithItems have (non-empty) string labels and,
24optionally, client data associated with them. Client data may be of two
25different kinds: either simple untyped ({\tt void *}) pointers which are simply
26stored by the control but not used in any way by it, or typed pointers
27({\tt wxClientData *}) which are owned by the control meaning that the typed
28client data (and only it) will be deleted when an item is
29\helpref{deleted}{wxcontrolwithitemsdelete} or the entire control is
30\helpref{cleared}{wxcontrolwithitemsclear} (which also happens when it is
31destroyed). Finally note that in the same control all items must have client
32data of the same type (typed or untyped), if any. This type is determined by
33the first call to \helpref{Append}{wxcontrolwithitemsappend} (the version with
34client data pointer) or \helpref{SetClientData}{wxcontrolwithitemssetclientdata}.
35
36\wxheading{Derived from}
37
38\helpref{wxControl}{wxcontrol}\\
39\helpref{wxWindow}{wxwindow}\\
40\helpref{wxEvtHandler}{wxevthandler}\\
41\helpref{wxObject}{wxobject}
42
43\wxheading{Include files}
44
45<wx/ctrlsub.h> but usually never included directly
46
47\latexignore{\rtfignore{\wxheading{Members}}}
48
49\membersection{wxControlWithItems::Append}\label{wxcontrolwithitemsappend}
50
51\func{int}{Append}{\param{const wxString\& }{ item}}
52
53Adds the item to the end of the list box.
54
55\func{int}{Append}{\param{const wxString\& }{ item}, \param{void *}{clientData}}
56
57\func{int}{Append}{\param{const wxString\& }{ item}, \param{wxClientData *}{clientData}}
58
59Adds the item to the end of the list box, associating the given, typed or
60untyped, client data pointer with the item.
61
62\func{void}{Append}{\param{const wxArrayString\& }{strings}}
63
64Appends several items at once to the control. Notice that calling this method
65may be much faster than appending the items one by one if you need to add a lot
66of items.
67
68\wxheading{Parameters}
69
70\docparam{item}{String to add.}
71
72\docparam{clientData}{Client data to associate with the item.}
73
74\wxheading{Return value}
75
76When appending a single item, the return value is the index of the newly added
77item which may be different from the last one if the control is sorted (e.g.
78has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style).
79
80\membersection{wxControlWithItems::Clear}\label{wxcontrolwithitemsclear}
81
82\func{void}{Clear}{\void}
83
84Removes all items from the control.
85
86{\it Clear()} also deletes the client data of the existing items if it is owned
87by the control.
88
89\membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}
90
91\func{void}{Delete}{\param{unsigned int}{ n}}
92
93Deletes an item from the control. The client data associated with the item
94will be also deleted if it is owned by the control.
95
96Note that it is an error (signalled by an assert failure in debug builds) to
97remove an item with the index negative or greater or equal than the number of
98items in the control.
99
100\wxheading{Parameters}
101
102\docparam{n}{The zero-based item index.}
103
104\wxheading{See also}
105
106\helpref{Clear}{wxcontrolwithitemsclear}
107
108\membersection{wxControlWithItems::FindString}\label{wxcontrolwithitemsfindstring}
109
110\func{int}{FindString}{\param{const wxString\& }{string}, \param{bool}{ caseSensitive = false}}
111
112Finds an item whose label matches the given string.
113
114\wxheading{Parameters}
115
116\docparam{string}{String to find.}
117
118\docparam{caseSensitive}{Whether search is case sensitive (default is not).}
119
120\wxheading{Return value}
121
122The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
123not found.
124
125
126\membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
127
128\constfunc{void *}{GetClientData}{\param{unsigned int}{ n}}
129
130Returns a pointer to the client data associated with the given item (if any).
131It is an error to call this function for a control which doesn't have untyped
132client data at all although it is ok to call it even if the given item doesn't
133have any client data associated with it (but other items do).
134
135\wxheading{Parameters}
136
137\docparam{n}{The zero-based position of the item.}
138
139\wxheading{Return value}
140
141A pointer to the client data, or {\tt NULL} if not present.
142
143
144\membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
145
146\constfunc{wxClientData *}{GetClientObject}{\param{unsigned int}{ n}}
147
148Returns a pointer to the client data associated with the given item (if any).
149It is an error to call this function for a control which doesn't have typed
150client data at all although it is ok to call it even if the given item doesn't
151have any client data associated with it (but other items do).
152
153\wxheading{Parameters}
154
155\docparam{n}{The zero-based position of the item.}
156
157\wxheading{Return value}
158
159A pointer to the client data, or {\tt NULL} if not present.
160
161
162\membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}
163
164\constfunc{unsigned int}{GetCount}{\void}
165
166Returns the number of items in the control.
167
168\wxheading{See also}
169
170\helpref{IsEmpty}{wxcontrolwithitemsisempty}
171
172
173\membersection{wxControlWithItems::GetSelection}\label{wxcontrolwithitemsgetselection}
174
175\constfunc{int}{GetSelection}{\void}
176
177Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
178selected.
179
180\wxheading{Return value}
181
182The position of the current selection.
183
184\wxheading{Remarks}
185
186This method can be used with single selection list boxes only, you should use
187\helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
188with {\tt wxLB\_MULTIPLE} style.
189
190\wxheading{See also}
191
192\helpref{SetSelection}{wxcontrolwithitemssetselection},\rtfsp
193\helpref{GetStringSelection}{wxcontrolwithitemsgetstringselection}
194
195
196\membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
197
198\constfunc{wxString}{GetString}{\param{unsigned int}{ n}}
199
200Returns the label of the item with the given index.
201
202\wxheading{Parameters}
203
204\docparam{n}{The zero-based index.}
205
206\wxheading{Return value}
207
208The label of the item or an empty string if the position was invalid.
209
210
211\membersection{wxControlWithItems::GetStrings}\label{wxcontrolwithitemsgetstrings}
212
213\constfunc{wxArrayString}{GetStrings}{\void}
214
215Returns the array of the labels of all items in the control.
216
217
218\membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
219
220\constfunc{wxString}{GetStringSelection}{\void}
221
222Returns the label of the selected item or an empty string if no item is
223selected.
224
225\wxheading{See also}
226
227\helpref{GetSelection}{wxcontrolwithitemsgetselection}
228
229
230\membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
231
232\func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}}
233
234Inserts the item into the list before pos.
235Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
236
237\func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}, \param{void *}{clientData}}
238
239\func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}, \param{wxClientData *}{clientData}}
240
241Inserts the item into the list before pos, associating the given, typed or
242untyped, client data pointer with the item.
243Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
244
245\wxheading{Parameters}
246
247\docparam{item}{String to add.}
248
249\docparam{pos}{Position to insert item before, zero based.}
250
251\docparam{clientData}{Client data to associate with the item.}
252
253\wxheading{Return value}
254
255The return value is the index of the newly inserted item. If the insertion failed
256for some reason, -1 is returned.
257
258
259\membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
260
261\constfunc{bool}{IsEmpty}{\void}
262
263Returns {\tt true} if the control is empty or {\tt false} if it has some items.
264
265\wxheading{See also}
266
267\helpref{GetCount}{wxcontrolwithitemsgetcount}
268
269
270\membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
271
272\constfunc{int}{Number}{\void}
273
274{\bf Obsolescence note:} This method is obsolete and was replaced with
275\helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
276the new code. This method is only available if wxWidgets was compiled with
277{\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
278future versions.
279
280
281\membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
282
283\func{void}{Select}{\param{int}{ n}}
284
285This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
286exists only because it is slightly more natural for controls which support
287multiple selection.
288
289
290\membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
291
292\func{void}{SetClientData}{\param{unsigned int}{ n}, \param{void *}{data}}
293
294Associates the given untyped client data pointer with the given item. Note that
295it is an error to call this function if any typed client data pointers had been
296associated with the control items before.
297
298\wxheading{Parameters}
299
300\docparam{n}{The zero-based item index.}
301
302\docparam{data}{The client data to associate with the item.}
303
304
305\membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
306
307\func{void}{SetClientObject}{\param{unsigned int}{ n}, \param{wxClientData *}{data}}
308
309Associates the given typed client data pointer with the given item: the
310{\it data} object will be deleted when the item is deleted (either explicitly
311by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
312control itself is destroyed).
313
314Note that it is an error to call this function if any untyped client data
315pointers had been associated with the control items before.
316
317\wxheading{Parameters}
318
319\docparam{n}{The zero-based item index.}
320
321\docparam{data}{The client data to associate with the item.}
322
323
324\membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
325
326\func{void}{SetSelection}{\param{int}{ n}}
327
328Sets the selection to the given item \arg{n} or removes the selection entirely
329if \arg{n} $==$ {\tt wxNOT\_FOUND}.
330
331Note that this does not cause any command events to be emitted nor does it
332deselect any other items in the controls which support multiple selections.
333
334\wxheading{Parameters}
335
336\docparam{n}{The string position to select, starting from zero.}
337
338\wxheading{See also}
339
340\helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
341\helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
342
343
344\membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
345
346\func{void}{SetString}{\param{unsigned int}{ n}, \param{const wxString\& }{ string}}
347
348Sets the label for the given item.
349
350\wxheading{Parameters}
351
352\docparam{n}{The zero-based item index.}
353
354\docparam{string}{The label to set.}
355
356
357\membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
358
359\func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}
360
361Selects the item with the specified string in the control. This doesn't cause
362any command events to be emitted.
363
364\wxheading{Parameters}
365
366\docparam{string}{The string to select.}
367
368\wxheading{Return value}
369
370\true if the specified string has been selected, \false if it wasn't found in
371the control.
372
373\wxheading{See also}
374
375\helpref{SetSelection}{wxcontrolwithitemssetselection}
376