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: ctrlsub.tex 41905 2006-10-10 17:46:49Z JS $ 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 being 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 377