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::Select}\label{wxcontrolwithitemsselect}
 271
 272 \func{void}{Select}{\param{int}{ n}}
 273
 274 This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
 275 exists only because it is slightly more natural for controls which support
 276 multiple selection.
 277
 278
 279 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 280
 281 \func{void}{SetClientData}{\param{unsigned int}{ n}, \param{void *}{data}}
 282
 283 Associates the given untyped client data pointer with the given item. Note that
 284 it is an error to call this function if any typed client data pointers had been
 285 associated with the control items before.
 286
 287 \wxheading{Parameters}
 288
 289 \docparam{n}{The zero-based item index.}
 290
 291 \docparam{data}{The client data to associate with the item.}
 292
 293
 294 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 295
 296 \func{void}{SetClientObject}{\param{unsigned int}{ n}, \param{wxClientData *}{data}}
 297
 298 Associates the given typed client data pointer with the given item: the
 299 {\it data} object will be deleted when the item is deleted (either explicitly
 300 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 301 control itself is destroyed).
 302
 303 Note that it is an error to call this function if any untyped client data
 304 pointers had been associated with the control items before.
 305
 306 \wxheading{Parameters}
 307
 308 \docparam{n}{The zero-based item index.}
 309
 310 \docparam{data}{The client data to associate with the item.}
 311
 312
 313 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
 314
 315 \func{void}{SetSelection}{\param{int}{ n}}
 316
 317 Sets the selection to the given item \arg{n} or removes the selection entirely
 318 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 319
 320 Note that this does not cause any command events to be emitted nor does it
 321 deselect any other items in the controls which support multiple selections.
 322
 323 \wxheading{Parameters}
 324
 325 \docparam{n}{The string position to select, starting from zero.}
 326
 327 \wxheading{See also}
 328
 329 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
 330 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
 331
 332
 333 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 334
 335 \func{void}{SetString}{\param{unsigned int}{ n}, \param{const wxString\& }{ string}}
 336
 337 Sets the label for the given item.
 338
 339 \wxheading{Parameters}
 340
 341 \docparam{n}{The zero-based item index.}
 342
 343 \docparam{string}{The label to set.}
 344
 345
 346 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 347
 348 \func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}
 349
 350 Selects the item with the specified string in the control. This doesn't cause
 351 any command events to be emitted.
 352
 353 \wxheading{Parameters}
 354
 355 \docparam{string}{The string to select.}
 356
 357 \wxheading{Return value}
 358
 359 \true if the specified string has been selected, \false if it wasn't found in
 360 the control.
 361
 362 \wxheading{See also}
 363
 364 \helpref{SetSelection}{wxcontrolwithitemssetselection}
 365