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:     wxWindows 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{unsigned 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}, \param{bool}{ caseSensitive = false}}
 111
 112 Finds 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
 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{unsigned 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{unsigned 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{unsigned 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{unsigned 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::GetStrings}\label{wxcontrolwithitemsgetstrings}
 212
 213 \constfunc{wxArrayString}{GetStrings}{\void}
 214
 215 Returns 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
 222 Returns the label of the selected item or an empty string if no item is
 223 selected.
 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
 234 Inserts the item into the list before pos.
 235 Not 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
 241 Inserts the item into the list before pos, associating the given, typed or
 242 untyped, client data pointer with the item.
 243 Not 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
 255 The return value is the index of the newly inserted item. If the insertion failed
 256 for some reason, -1 is returned.
 257
 258
 259 \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
 260
 261 \constfunc{bool}{IsEmpty}{\void}
 262
 263 Returns {\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
 276 the new code. This method is only available if wxWidgets was compiled with
 277 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
 278 future versions.
 279
 280
 281 \membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
 282
 283 \func{void}{Select}{\param{int}{ n}}
 284
 285 This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
 286 exists only because it is slightly more natural for controls which support
 287 multiple selection.
 288
 289
 290 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 291
 292 \func{void}{SetClientData}{\param{unsigned int}{ n}, \param{void *}{data}}
 293
 294 Associates the given untyped client data pointer with the given item. Note that
 295 it is an error to call this function if any typed client data pointers had been
 296 associated 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
 309 Associates 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
 311 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 312 control itself is destroyed).
 313
 314 Note that it is an error to call this function if any untyped client data
 315 pointers 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
 328 Sets the selection to the given item \arg{n} or removes the selection entirely
 329 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 330
 331 Note that this does not cause any command events to be emitted nor does it
 332 deselect 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
 348 Sets 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
 361 Selects the item with the specified string in the control. This doesn't cause
 362 any 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
 371 the control.
 372
 373 \wxheading{See also}
 374
 375 \helpref{SetSelection}{wxcontrolwithitemssetselection}