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 \wxheading{Library}
  48
  49 \helpref{wxCore}{librarieslist}
  50
  51 \latexignore{\rtfignore{\wxheading{Members}}}
  52
  53 \membersection{wxControlWithItems::Append}\label{wxcontrolwithitemsappend}
  54
  55 \func{int}{Append}{\param{const wxString\& }{ item}}
  56
  57 Adds the item to the end of the list box.
  58
  59 \func{int}{Append}{\param{const wxString\& }{ item}, \param{void *}{clientData}}
  60
  61 \func{int}{Append}{\param{const wxString\& }{ item}, \param{wxClientData *}{clientData}}
  62
  63 Adds the item to the end of the list box, associating the given, typed or
  64 untyped, client data pointer with the item.
  65
  66 \func{void}{Append}{\param{const wxArrayString\& }{strings}}
  67
  68 \func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}}
  69
  70 \func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{void **}{clientData}}
  71
  72 \func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{wxClientData **}{clientData}}
  73
  74 Appends several items at once to the control. Notice that calling this method
  75 is usually much faster than appending them one by one if you need to add a lot
  76 of items.
  77
  78 \wxheading{Parameters}
  79
  80 \docparam{item}{String to add.}
  81
  82 \docparam{stringsArray}{Contains items to append to the control.}
  83
  84 \docparam{strings}{Array of strings of size \arg{n}.}
  85
  86 \docparam{n}{Number of items in the \arg{strings} array.}
  87
  88 \docparam{clientData}{Array of client data pointers of size \arg{n} to associate with the new items.}
  89
  90 \wxheading{Return value}
  91
  92 When appending a single item, the return value is the index of the newly added
  93 item which may be different from the last one if the control is sorted (e.g.
  94 has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style).
  95
  96 \membersection{wxControlWithItems::Clear}\label{wxcontrolwithitemsclear}
  97
  98 \func{void}{Clear}{\void}
  99
 100 Removes all items from the control.
 101
 102 {\it Clear()} also deletes the client data of the existing items if it is owned
 103 by the control.
 104
 105 \membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}
 106
 107 \func{void}{Delete}{\param{unsigned int}{ n}}
 108
 109 Deletes an item from the control. The client data associated with the item
 110 will be also deleted if it is owned by the control.
 111
 112 Note that it is an error (signalled by an assert failure in debug builds) to
 113 remove an item with the index negative or greater or equal than the number of
 114 items in the control.
 115
 116 \wxheading{Parameters}
 117
 118 \docparam{n}{The zero-based item index.}
 119
 120 \wxheading{See also}
 121
 122 \helpref{Clear}{wxcontrolwithitemsclear}
 123
 124 \membersection{wxControlWithItems::FindString}\label{wxcontrolwithitemsfindstring}
 125
 126 \func{int}{FindString}{\param{const wxString\& }{string}, \param{bool}{ caseSensitive = false}}
 127
 128 Finds an item whose label matches the given string.
 129
 130 \wxheading{Parameters}
 131
 132 \docparam{string}{String to find.}
 133
 134 \docparam{caseSensitive}{Whether search is case sensitive (default is not).}
 135
 136 \wxheading{Return value}
 137
 138 The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
 139 not found.
 140
 141
 142 \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
 143
 144 \constfunc{void *}{GetClientData}{\param{unsigned 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 untyped
 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::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
 161
 162 \constfunc{wxClientData *}{GetClientObject}{\param{unsigned int}{ n}}
 163
 164 Returns a pointer to the client data associated with the given item (if any).
 165 It is an error to call this function for a control which doesn't have typed
 166 client data at all although it is ok to call it even if the given item doesn't
 167 have any client data associated with it (but other items do).
 168
 169 \wxheading{Parameters}
 170
 171 \docparam{n}{The zero-based position of the item.}
 172
 173 \wxheading{Return value}
 174
 175 A pointer to the client data, or {\tt NULL} if not present.
 176
 177
 178 \membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}
 179
 180 \constfunc{unsigned int}{GetCount}{\void}
 181
 182 Returns the number of items in the control.
 183
 184 \wxheading{See also}
 185
 186 \helpref{IsEmpty}{wxcontrolwithitemsisempty}
 187
 188
 189 \membersection{wxControlWithItems::GetSelection}\label{wxcontrolwithitemsgetselection}
 190
 191 \constfunc{int}{GetSelection}{\void}
 192
 193 Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
 194 selected.
 195
 196 \wxheading{Return value}
 197
 198 The position of the current selection.
 199
 200 \wxheading{Remarks}
 201
 202 This method can be used with single selection list boxes only, you should use
 203 \helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
 204 with {\tt wxLB\_MULTIPLE} style.
 205
 206 \wxheading{See also}
 207
 208 \helpref{SetSelection}{wxcontrolwithitemssetselection},\rtfsp
 209 \helpref{GetStringSelection}{wxcontrolwithitemsgetstringselection}
 210
 211
 212 \membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
 213
 214 \constfunc{wxString}{GetString}{\param{unsigned int}{ n}}
 215
 216 Returns the label of the item with the given index.
 217
 218 \wxheading{Parameters}
 219
 220 \docparam{n}{The zero-based index.}
 221
 222 \wxheading{Return value}
 223
 224 The label of the item or an empty string if the position was invalid.
 225
 226
 227 \membersection{wxControlWithItems::GetStrings}\label{wxcontrolwithitemsgetstrings}
 228
 229 \constfunc{wxArrayString}{GetStrings}{\void}
 230
 231 Returns the array of the labels of all items in the control.
 232
 233
 234 \membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
 235
 236 \constfunc{wxString}{GetStringSelection}{\void}
 237
 238 Returns the label of the selected item or an empty string if no item is
 239 selected.
 240
 241 \wxheading{See also}
 242
 243 \helpref{GetSelection}{wxcontrolwithitemsgetselection}
 244
 245
 246 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
 247
 248 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}}
 249
 250 Inserts the item into the list before pos.
 251 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 252
 253 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}, \param{void *}{clientData}}
 254
 255 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned int }{pos}, \param{wxClientData *}{clientData}}
 256
 257 Inserts the item into the list before pos, associating the given, typed or
 258 untyped, client data pointer with the item.
 259 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 260
 261 \func{void}{Insert}{\param{const wxArrayString\& }{strings}, \param{unsigned int }{pos}}
 262
 263 \func{void}{Insert}{\param{const wxArrayString\& }{strings}, \param{unsigned int }{pos}}
 264
 265 \func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}}
 266
 267 \func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}, \param{void **}{clientData}}
 268
 269 \func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}, \param{wxClientData **}{clientData}}
 270
 271 Inserts several items at once into the control. Notice that calling this method
 272 is usually much faster than inserting them one by one if you need to insert a lot
 273 of items.
 274
 275
 276 \wxheading{Parameters}
 277
 278 \docparam{item}{String to add.}
 279
 280 \docparam{pos}{Position to insert item before, zero based.}
 281
 282 \docparam{stringsArray}{Contains items to insert into the control content}
 283
 284 \docparam{strings}{Array of strings of size \arg{n}.}
 285
 286 \docparam{n}{Number of items in the \arg{strings} array.}
 287
 288 \docparam{clientData}{Array of client data pointers of size \arg{n} to associate with the new items.}
 289
 290 \wxheading{Return value}
 291
 292 The return value is the index of the newly inserted item. If the insertion failed
 293 for some reason, -1 is returned.
 294
 295
 296 \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
 297
 298 \constfunc{bool}{IsEmpty}{\void}
 299
 300 Returns {\tt true} if the control is empty or {\tt false} if it has some items.
 301
 302 \wxheading{See also}
 303
 304 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 305
 306
 307 \membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
 308
 309 \func{void}{Select}{\param{int}{ n}}
 310
 311 This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
 312 exists only because it is slightly more natural for controls which support
 313 multiple selection.
 314
 315
 316 \membersection{wxControlWithItems::Set}\label{wxcontrolwithitemsset}
 317
 318 \func{int}{Set}{\param{const wxString\& }{ item}}
 319
 320 \func{int}{Set}{\param{const wxString\& }{ item}, \param{void *}{clientData}}
 321
 322 \func{int}{Set}{\param{const wxString\& }{ item}, \param{wxClientData *}{clientData}}
 323
 324 Replace control items with the (only) item specified, associating the typed or
 325 untyped client data pointer with it if given.
 326
 327 \func{void}{Set}{\param{const wxArrayString\& }{stringsArray}}
 328
 329 \func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}}
 330
 331 \func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{void **}{clientData}}
 332
 333 \func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{wxClientData **}{clientData}}
 334
 335 Replaces the current control contents with the given items. Notice that calling
 336 this method is much faster than appending the items one by one if you need to
 337 append a lot of them.
 338
 339 \wxheading{Parameters}
 340
 341 \docparam{item}{The single item to insert into the control.}
 342
 343 \docparam{stringsArray}{Contains items to set as control content.}
 344
 345 \docparam{strings}{Raw C++ array of strings. Only used in conjunction with 'n'.}
 346
 347 \docparam{n}{Number of items passed in 'strings'. Only used in conjunction with 'strings'.}
 348
 349 \docparam{clientData}{Client data to associate with the item(s).}
 350
 351 \wxheading{Return value}
 352
 353 When the control is sorted (e.g. has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style)
 354 the return value could be different from (GetCount() - 1).
 355 When setting a single item to the container, the return value is the index of the
 356 newly added item which may be different from the last one if the control is sorted
 357 (e.g. has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style).
 358
 359 By default this method subsequently calls \helpref{Clear}{wxcontrolwithitemsclear}
 360 and \helpref{Append}{wxcontrolwithitemsappend}.
 361
 362
 363 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 364
 365 \func{void}{SetClientData}{\param{unsigned int}{ n}, \param{void *}{data}}
 366
 367 Associates the given untyped client data pointer with the given item. Note that
 368 it is an error to call this function if any typed client data pointers had been
 369 associated with the control items before.
 370
 371 \wxheading{Parameters}
 372
 373 \docparam{n}{The zero-based item index.}
 374
 375 \docparam{data}{The client data to associate with the item.}
 376
 377
 378 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 379
 380 \func{void}{SetClientObject}{\param{unsigned int}{ n}, \param{wxClientData *}{data}}
 381
 382 Associates the given typed client data pointer with the given item: the
 383 {\it data} object will be deleted when the item is deleted (either explicitly
 384 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 385 control itself is destroyed).
 386
 387 Note that it is an error to call this function if any untyped client data
 388 pointers had been associated with the control items before.
 389
 390 \wxheading{Parameters}
 391
 392 \docparam{n}{The zero-based item index.}
 393
 394 \docparam{data}{The client data to associate with the item.}
 395
 396
 397 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
 398
 399 \func{void}{SetSelection}{\param{int}{ n}}
 400
 401 Sets the selection to the given item \arg{n} or removes the selection entirely
 402 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 403
 404 Note that this does not cause any command events to be emitted nor does it
 405 deselect any other items in the controls which support multiple selections.
 406
 407 \wxheading{Parameters}
 408
 409 \docparam{n}{The string position to select, starting from zero.}
 410
 411 \wxheading{See also}
 412
 413 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
 414 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
 415
 416
 417 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 418
 419 \func{void}{SetString}{\param{unsigned int}{ n}, \param{const wxString\& }{ string}}
 420
 421 Sets the label for the given item.
 422
 423 \wxheading{Parameters}
 424
 425 \docparam{n}{The zero-based item index.}
 426
 427 \docparam{string}{The label to set.}
 428
 429
 430 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 431
 432 \func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}
 433
 434 Selects the item with the specified string in the control. This doesn't cause
 435 any command events to be emitted.
 436
 437 \wxheading{Parameters}
 438
 439 \docparam{string}{The string to select.}
 440
 441 \wxheading{Return value}
 442
 443 \true if the specified string has been selected, \false if it wasn't found in
 444 the control.
 445
 446 \wxheading{See also}
 447
 448 \helpref{SetSelection}{wxcontrolwithitemssetselection}
 449