]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/ctrlsub.tex
Fixed to work with the new wxMacControl system.
[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: wxWidgets 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{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}}
111
112Finds 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
120The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
121not found.
122
123
124\membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
125
126\constfunc{void *}{GetClientData}{\param{int}{ n}}
127
128Returns a pointer to the client data associated with the given item (if any).
129It is an error to call this function for a control which doesn't have untyped
130client data at all although it is ok to call it even if the given item doesn't
131have 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
139A 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
146Returns a pointer to the client data associated with the given item (if any).
147It is an error to call this function for a control which doesn't have typed
148client data at all although it is ok to call it even if the given item doesn't
149have 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
157A 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
164Returns 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
175Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
176selected.
177
178\wxheading{Return value}
179
180The position of the current selection.
181
182\wxheading{Remarks}
183
184This method can be used with single selection list boxes only, you should use
185\helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
186with {\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
198Returns 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
206The 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
213Returns the label of the selected item or an empty string if no item is
214selected.
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
225Inserts the item into the list before pos.
226Not 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
232Inserts the item into the list before pos, associating the given, typed or
233untyped, client data pointer with the item.
234Not 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
246The return value is the index of the newly inserted item. If the insertion failed
247for some reason, -1 is returned.
248
249
250\membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
251
252\constfunc{bool}{IsEmpty}{\void}
253
254Returns {\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
267the new code. This method is only available if wxWidgets was compiled with
268{\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
269future versions.
270
271
272\membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
273
274\func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
275
276Associates the given untyped client data pointer with the given item. Note that
277it is an error to call this function if any typed client data pointers had been
278associated 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
291Associates 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
293by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
294control itself is destroyed).
295
296Note that it is an error to call this function if any untyped client data
297pointers 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
310Sets the choice by passing the desired string position. This does not cause
311any 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
327Sets 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
340Selects the item with the specified string in the control. This doesn't cause
341any 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