]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/ctrlsub.tex
documented return value of wxListCtrl::HitTest
[wxWidgets.git] / docs / latex / wx / ctrlsub.tex
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: wxWidgets license
10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
11
12 \section{\class{wxControlWithItems}}\label{wxcontrolwithitems}
13
14 This class is an abstract base class for some wxWidgets controls which contain
15 several items, such as \helpref{wxListBox}{wxlistbox} and
16 \helpref{wxCheckListBox}{wxchecklistbox} derived from it,
17 \helpref{wxChoice}{wxchoice} and \helpref{wxComboBox}{wxcombobox}.
18
19 It defines the methods for accessing the controls items and although each of
20 the derived classes implements them differently, they still all conform to the
21 same interface.
22
23 The items in a wxControlWithItems have (non empty) string labels and,
24 optionally, client data associated with them. Client data may be of two
25 different kinds: either simple untyped ({\tt void *}) pointers which are simply
26 stored 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
28 client 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
31 destroyed). Finally note that in the same control all items must have client
32 data of the same type (typed or untyped), if any. This type is determined by
33 the first call to \helpref{Append}{wxcontrolwithitemsappend} (the version with
34 client 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
53 Adds 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
59 Adds the item to the end of the list box, associating the given, typed or
60 untyped, client data pointer with the item.
61
62 \func{void}{Append}{\param{const wxArrayString\& }{strings}}
63
64 Appends several items at once to the control. Notice that calling this method
65 may be much faster than appending the items one by one if you need to add a lot
66 of 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
76 When appending a single item, the return value is the index of the newly added
77 item which may be different from the last one if the control is sorted (e.g.
78 has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style).
79
80 \membersection{wxControlWithItems::Clear}\label{wxcontrolwithitemsclear}
81
82 \func{void}{Clear}{\void}
83
84 Removes all items from the control.
85
86 {\it Clear()} also deletes the client data of the existing items if it is owned
87 by the control.
88
89 \membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}
90
91 \func{void}{Delete}{\param{int}{ n}}
92
93 Deletes an item from the control. The client data associated with the item
94 will be also deleted if it is owned by the control.
95
96 Note that it is an error (signalled by an assert failure in debug builds) to
97 remove an item with the index negative or greater or equal than the number of
98 items 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}}
111
112 Finds an item whose label matches the given string.
113
114 \wxheading{Parameters}
115
116 \docparam{string}{String to find.}
117
118 \wxheading{Return value}
119
120 The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
121 not found.
122
123
124 \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
125
126 \constfunc{void *}{GetClientData}{\param{int}{ n}}
127
128 Returns a pointer to the client data associated with the given item (if any).
129 It is an error to call this function for a control which doesn't have untyped
130 client data at all although it is ok to call it even if the given item doesn't
131 have any client data associated with it (but other items do).
132
133 \wxheading{Parameters}
134
135 \docparam{n}{The zero-based position of the item.}
136
137 \wxheading{Return value}
138
139 A pointer to the client data, or {\tt NULL} if not present.
140
141
142 \membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
143
144 \constfunc{wxClientData *}{GetClientObject}{\param{int}{ n}}
145
146 Returns a pointer to the client data associated with the given item (if any).
147 It is an error to call this function for a control which doesn't have typed
148 client data at all although it is ok to call it even if the given item doesn't
149 have any client data associated with it (but other items do).
150
151 \wxheading{Parameters}
152
153 \docparam{n}{The zero-based position of the item.}
154
155 \wxheading{Return value}
156
157 A pointer to the client data, or {\tt NULL} if not present.
158
159
160 \membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}
161
162 \constfunc{int}{GetCount}{\void}
163
164 Returns the number of items in the control.
165
166 \wxheading{See also}
167
168 \helpref{IsEmpty}{wxcontrolwithitemsisempty}
169
170
171 \membersection{wxControlWithItems::GetSelection}\label{wxcontrolwithitemsgetselection}
172
173 \constfunc{int}{GetSelection}{\void}
174
175 Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
176 selected.
177
178 \wxheading{Return value}
179
180 The position of the current selection.
181
182 \wxheading{Remarks}
183
184 This method can be used with single selection list boxes only, you should use
185 \helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
186 with {\tt wxLB\_MULTIPLE} style.
187
188 \wxheading{See also}
189
190 \helpref{SetSelection}{wxcontrolwithitemssetselection},\rtfsp
191 \helpref{GetStringSelection}{wxcontrolwithitemsgetstringselection}
192
193
194 \membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
195
196 \constfunc{wxString}{GetString}{\param{int}{ n}}
197
198 Returns the label of the item with the given index.
199
200 \wxheading{Parameters}
201
202 \docparam{n}{The zero-based index.}
203
204 \wxheading{Return value}
205
206 The label of the item or an empty string if the position was invalid.
207
208
209 \membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
210
211 \constfunc{wxString}{GetStringSelection}{\void}
212
213 Returns the label of the selected item or an empty string if no item is
214 selected.
215
216 \wxheading{See also}
217
218 \helpref{GetSelection}{wxcontrolwithitemsgetselection}
219
220
221 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
222
223 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}}
224
225 Inserts the item into the list before pos.
226 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
227
228 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{void *}{clientData}}
229
230 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{clientData}}
231
232 Inserts the item into the list before pos, associating the given, typed or
233 untyped, client data pointer with the item.
234 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
235
236 \wxheading{Parameters}
237
238 \docparam{item}{String to add.}
239
240 \docparam{pos}{Position to insert item before, zero based.}
241
242 \docparam{clientData}{Client data to associate with the item.}
243
244 \wxheading{Return value}
245
246 The return value is the index of the newly inserted item. If the insertion failed
247 for some reason, -1 is returned.
248
249
250 \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
251
252 \constfunc{bool}{IsEmpty}{\void}
253
254 Returns {\tt true} if the control is empty or {\tt false} if it has some items.
255
256 \wxheading{See also}
257
258 \helpref{GetCount}{wxcontrolwithitemsgetcount}
259
260
261 \membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
262
263 \constfunc{int}{Number}{\void}
264
265 {\bf Obsolescence note:} This method is obsolete and was replaced with
266 \helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
267 the new code. This method is only available if wxWidgets was compiled with
268 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
269 future versions.
270
271
272 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
273
274 \func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
275
276 Associates the given untyped client data pointer with the given item. Note that
277 it is an error to call this function if any typed client data pointers had been
278 associated with the control items before.
279
280 \wxheading{Parameters}
281
282 \docparam{n}{The zero-based item index.}
283
284 \docparam{data}{The client data to associate with the item.}
285
286
287 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
288
289 \func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}}
290
291 Associates the given typed client data pointer with the given item: the
292 {\it data} object will be deleted when the item is deleted (either explicitly
293 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
294 control itself is destroyed).
295
296 Note that it is an error to call this function if any untyped client data
297 pointers had been associated with the control items before.
298
299 \wxheading{Parameters}
300
301 \docparam{n}{The zero-based item index.}
302
303 \docparam{data}{The client data to associate with the item.}
304
305
306 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
307
308 \func{void}{SetSelection}{\param{int}{ n}}
309
310 Sets the choice by passing the desired string position. This does not cause
311 any command events to get emitted.
312
313 \wxheading{Parameters}
314
315 \docparam{n}{The string position to select, starting from zero.}
316
317 \wxheading{See also}
318
319 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
320 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
321
322
323 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
324
325 \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}
326
327 Sets the label for the given item.
328
329 \wxheading{Parameters}
330
331 \docparam{n}{The zero-based item index.}
332
333 \docparam{string}{The label to set.}
334
335
336 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
337
338 \func{void}{SetStringSelection}{\param{const wxString\& }{ string}}
339
340 Selects the item with the specified string in the control. This doesn't cause
341 any command events being emitted.
342
343 \wxheading{Parameters}
344
345 \docparam{string}{The string to select.}
346
347 \wxheading{See also}
348
349 \helpref{SetSelection}{wxcontrolwithitemssetselection}
350
351