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{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{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{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{size\_t}{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{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::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
 212
 213 \constfunc{wxString}{GetStringSelection}{\void}
 214
 215 Returns the label of the selected item or an empty string if no item is
 216 selected.
 217
 218 \wxheading{See also}
 219
 220 \helpref{GetSelection}{wxcontrolwithitemsgetselection}
 221
 222
 223 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
 224
 225 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}}
 226
 227 Inserts the item into the list before pos.
 228 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 229
 230 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{void *}{clientData}}
 231
 232 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{clientData}}
 233
 234 Inserts the item into the list before pos, associating the given, typed or
 235 untyped, client data pointer with the item.
 236 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 237
 238 \wxheading{Parameters}
 239
 240 \docparam{item}{String to add.}
 241
 242 \docparam{pos}{Position to insert item before, zero based.}
 243
 244 \docparam{clientData}{Client data to associate with the item.}
 245
 246 \wxheading{Return value}
 247
 248 The return value is the index of the newly inserted item. If the insertion failed
 249 for some reason, -1 is returned.
 250
 251
 252 \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
 253
 254 \constfunc{bool}{IsEmpty}{\void}
 255
 256 Returns {\tt true} if the control is empty or {\tt false} if it has some items.
 257
 258 \wxheading{See also}
 259
 260 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 261
 262
 263 \membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
 264
 265 \constfunc{int}{Number}{\void}
 266
 267 {\bf Obsolescence note:} This method is obsolete and was replaced with
 268 \helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
 269 the new code. This method is only available if wxWidgets was compiled with
 270 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
 271 future versions.
 272
 273
 274 \membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
 275
 276 \func{void}{Select}{\param{int}{ n}}
 277
 278 This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
 279 exists only because it is slightly more natural for controls which support
 280 multiple selection.
 281
 282
 283 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 284
 285 \func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
 286
 287 Associates the given untyped client data pointer with the given item. Note that
 288 it is an error to call this function if any typed client data pointers had been
 289 associated with the control items before.
 290
 291 \wxheading{Parameters}
 292
 293 \docparam{n}{The zero-based item index.}
 294
 295 \docparam{data}{The client data to associate with the item.}
 296
 297
 298 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 299
 300 \func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}}
 301
 302 Associates the given typed client data pointer with the given item: the
 303 {\it data} object will be deleted when the item is deleted (either explicitly
 304 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 305 control itself is destroyed).
 306
 307 Note that it is an error to call this function if any untyped client data
 308 pointers had been associated with the control items before.
 309
 310 \wxheading{Parameters}
 311
 312 \docparam{n}{The zero-based item index.}
 313
 314 \docparam{data}{The client data to associate with the item.}
 315
 316
 317 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
 318
 319 \func{void}{SetSelection}{\param{int}{ n}}
 320
 321 Sets the selection to the given item \arg{n} or removes the selection entirely
 322 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 323
 324 Note that this does not cause any command events to be emitted nor does it
 325 deselect any other items in the controls which support multiple selections.
 326
 327 \wxheading{Parameters}
 328
 329 \docparam{n}{The string position to select, starting from zero.}
 330
 331 \wxheading{See also}
 332
 333 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
 334 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
 335
 336
 337 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 338
 339 \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}
 340
 341 Sets the label for the given item.
 342
 343 \wxheading{Parameters}
 344
 345 \docparam{n}{The zero-based item index.}
 346
 347 \docparam{string}{The label to set.}
 348
 349
 350 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 351
 352 \func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}
 353
 354 Selects the item with the specified string in the control. This doesn't cause
 355 any command events being emitted.
 356
 357 \wxheading{Parameters}
 358
 359 \docparam{string}{The string to select.}
 360
 361 \wxheading{Return value}
 362
 363 \true if the specified string has been selected, \false if it wasn't found in
 364 the control.
 365
 366 \wxheading{See also}
 367
 368 \helpref{SetSelection}{wxcontrolwithitemssetselection}