Commit | Line | Data |
---|---|---|
243dbf1a | 1 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
bed5584e VZ |
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 | |
8795498c | 9 | %% License: wxWindows license |
243dbf1a | 10 | %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% |
bed5584e VZ |
11 | |
12 | \section{\class{wxControlWithItems}}\label{wxcontrolwithitems} | |
13 | ||
fc2171bd | 14 | This class is an abstract base class for some wxWidgets controls which contain |
bed5584e VZ |
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 | ||
f7c40316 | 110 | \func{int}{FindString}{\param{const wxString\& }{string}, \param{bool}{ caseSensitive = false}} |
bed5584e VZ |
111 | |
112 | Finds an item whose label matches the given string. | |
113 | ||
114 | \wxheading{Parameters} | |
115 | ||
116 | \docparam{string}{String to find.} | |
117 | ||
f7c40316 WS |
118 | \docparam{caseSensitive}{Whether search is case sensitive (default is not).} |
119 | ||
bed5584e VZ |
120 | \wxheading{Return value} |
121 | ||
122 | The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was | |
123 | not found. | |
124 | ||
125 | ||
126 | \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata} | |
127 | ||
128 | \constfunc{void *}{GetClientData}{\param{int}{ n}} | |
129 | ||
130 | Returns a pointer to the client data associated with the given item (if any). | |
131 | It is an error to call this function for a control which doesn't have untyped | |
132 | client data at all although it is ok to call it even if the given item doesn't | |
133 | have 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 | ||
141 | A 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{int}{ n}} | |
147 | ||
148 | Returns a pointer to the client data associated with the given item (if any). | |
149 | It is an error to call this function for a control which doesn't have typed | |
150 | client data at all although it is ok to call it even if the given item doesn't | |
151 | have 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 | ||
159 | A pointer to the client data, or {\tt NULL} if not present. | |
160 | ||
161 | ||
162 | \membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount} | |
163 | ||
164 | \constfunc{int}{GetCount}{\void} | |
165 | ||
166 | Returns 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 | ||
177 | Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is | |
178 | selected. | |
179 | ||
180 | \wxheading{Return value} | |
181 | ||
182 | The position of the current selection. | |
183 | ||
184 | \wxheading{Remarks} | |
185 | ||
186 | This method can be used with single selection list boxes only, you should use | |
187 | \helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes | |
188 | with {\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{int}{ n}} | |
199 | ||
200 | Returns 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 | ||
208 | The label of the item or an empty string if the position was invalid. | |
209 | ||
210 | ||
211 | \membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection} | |
212 | ||
213 | \constfunc{wxString}{GetStringSelection}{\void} | |
214 | ||
215 | Returns the label of the selected item or an empty string if no item is | |
216 | selected. | |
217 | ||
218 | \wxheading{See also} | |
219 | ||
220 | \helpref{GetSelection}{wxcontrolwithitemsgetselection} | |
221 | ||
222 | ||
243dbf1a VZ |
223 | \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert} |
224 | ||
225 | \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}} | |
226 | ||
227 | Inserts the item into the list before pos. | |
228 | Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead. | |
229 | ||
230 | \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{void *}{clientData}} | |
231 | ||
232 | \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{clientData}} | |
233 | ||
234 | Inserts the item into the list before pos, associating the given, typed or | |
235 | untyped, client data pointer with the item. | |
236 | Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead. | |
237 | ||
238 | \wxheading{Parameters} | |
239 | ||
240 | \docparam{item}{String to add.} | |
241 | ||
242 | \docparam{pos}{Position to insert item before, zero based.} | |
243 | ||
244 | \docparam{clientData}{Client data to associate with the item.} | |
245 | ||
246 | \wxheading{Return value} | |
247 | ||
248 | The return value is the index of the newly inserted item. If the insertion failed | |
249 | for some reason, -1 is returned. | |
250 | ||
251 | ||
bed5584e VZ |
252 | \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty} |
253 | ||
254 | \constfunc{bool}{IsEmpty}{\void} | |
255 | ||
cc81d32f | 256 | Returns {\tt true} if the control is empty or {\tt false} if it has some items. |
bed5584e VZ |
257 | |
258 | \wxheading{See also} | |
259 | ||
260 | \helpref{GetCount}{wxcontrolwithitemsgetcount} | |
261 | ||
262 | ||
263 | \membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber} | |
264 | ||
265 | \constfunc{int}{Number}{\void} | |
266 | ||
267 | {\bf Obsolescence note:} This method is obsolete and was replaced with | |
268 | \helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in | |
fc2171bd | 269 | the new code. This method is only available if wxWidgets was compiled with |
bed5584e VZ |
270 | {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in |
271 | future versions. | |
272 | ||
273 | ||
c6179a84 VZ |
274 | \membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect} |
275 | ||
276 | \func{void}{Select}{\param{int}{ n}} | |
277 | ||
278 | This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and | |
279 | exists only because it is slightly more natural for controls which support | |
280 | multiple selection. | |
281 | ||
282 | ||
bed5584e VZ |
283 | \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata} |
284 | ||
285 | \func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}} | |
286 | ||
287 | Associates the given untyped client data pointer with the given item. Note that | |
288 | it is an error to call this function if any typed client data pointers had been | |
289 | associated with the control items before. | |
290 | ||
291 | \wxheading{Parameters} | |
292 | ||
293 | \docparam{n}{The zero-based item index.} | |
294 | ||
295 | \docparam{data}{The client data to associate with the item.} | |
296 | ||
297 | ||
298 | \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject} | |
299 | ||
300 | \func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}} | |
301 | ||
302 | Associates the given typed client data pointer with the given item: the | |
303 | {\it data} object will be deleted when the item is deleted (either explicitly | |
304 | by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the | |
305 | control itself is destroyed). | |
306 | ||
307 | Note that it is an error to call this function if any untyped client data | |
308 | pointers had been associated with the control items before. | |
309 | ||
310 | \wxheading{Parameters} | |
311 | ||
312 | \docparam{n}{The zero-based item index.} | |
313 | ||
314 | \docparam{data}{The client data to associate with the item.} | |
315 | ||
316 | ||
317 | \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection} | |
318 | ||
319 | \func{void}{SetSelection}{\param{int}{ n}} | |
320 | ||
26f2b058 | 321 | Sets the selection to the given item \arg{n} or removes the selection entirely |
a8d08dbd | 322 | if \arg{n} $==$ {\tt wxNOT\_FOUND}. |
26f2b058 | 323 | |
c6179a84 VZ |
324 | Note that this does not cause any command events to be emitted nor does it |
325 | deselect any other items in the controls which support multiple selections. | |
bed5584e VZ |
326 | |
327 | \wxheading{Parameters} | |
328 | ||
329 | \docparam{n}{The string position to select, starting from zero.} | |
330 | ||
331 | \wxheading{See also} | |
332 | ||
333 | \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp | |
334 | \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection} | |
335 | ||
336 | ||
337 | \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring} | |
338 | ||
339 | \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}} | |
340 | ||
341 | Sets the label for the given item. | |
342 | ||
343 | \wxheading{Parameters} | |
344 | ||
345 | \docparam{n}{The zero-based item index.} | |
346 | ||
347 | \docparam{string}{The label to set.} | |
348 | ||
349 | ||
350 | \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection} | |
351 | ||
64fa6f16 | 352 | \func{bool}{SetStringSelection}{\param{const wxString\& }{ string}} |
bed5584e VZ |
353 | |
354 | Selects the item with the specified string in the control. This doesn't cause | |
355 | any command events being emitted. | |
356 | ||
357 | \wxheading{Parameters} | |
358 | ||
359 | \docparam{string}{The string to select.} | |
360 | ||
64fa6f16 VZ |
361 | \wxheading{Return value} |
362 | ||
363 | \true if the specified string has been selected, \false if it wasn't found in | |
364 | the control. | |
365 | ||
bed5584e VZ |
366 | \wxheading{See also} |
367 | ||
368 | \helpref{SetSelection}{wxcontrolwithitemssetselection} | |
369 | ||
370 |