]>
Commit | Line | Data |
---|---|---|
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 selection to the given item \arg{n} or removes the selection entirely | |
311 | if \arg{n} $==$ {\tt wxNOT\_FOUND}. | |
312 | ||
313 | Note that this does not cause any command events to be emitted. | |
314 | ||
315 | \wxheading{Parameters} | |
316 | ||
317 | \docparam{n}{The string position to select, starting from zero.} | |
318 | ||
319 | \wxheading{See also} | |
320 | ||
321 | \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp | |
322 | \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection} | |
323 | ||
324 | ||
325 | \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring} | |
326 | ||
327 | \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}} | |
328 | ||
329 | Sets the label for the given item. | |
330 | ||
331 | \wxheading{Parameters} | |
332 | ||
333 | \docparam{n}{The zero-based item index.} | |
334 | ||
335 | \docparam{string}{The label to set.} | |
336 | ||
337 | ||
338 | \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection} | |
339 | ||
340 | \func{void}{SetStringSelection}{\param{const wxString\& }{ string}} | |
341 | ||
342 | Selects the item with the specified string in the control. This doesn't cause | |
343 | any command events being emitted. | |
344 | ||
345 | \wxheading{Parameters} | |
346 | ||
347 | \docparam{string}{The string to select.} | |
348 | ||
349 | \wxheading{See also} | |
350 | ||
351 | \helpref{SetSelection}{wxcontrolwithitemssetselection} | |
352 | ||
353 |