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}}
 111
 112 Finds an item whose label matches the given string.
 113
 114 \wxheading{Parameters}
 115
 116 \docparam{string}{String to find.}
 117
 118 \wxheading{Return value}
 119
 120 The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
 121 not found.
 122
 123
 124 \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
 125
 126 \constfunc{void *}{GetClientData}{\param{int}{ n}}
 127
 128 Returns a pointer to the client data associated with the given item (if any).
 129 It is an error to call this function for a control which doesn't have untyped
 130 client data at all although it is ok to call it even if the given item doesn't
 131 have any client data associated with it (but other items do).
 132
 133 \wxheading{Parameters}
 134
 135 \docparam{n}{The zero-based position of the item.}
 136
 137 \wxheading{Return value}
 138
 139 A pointer to the client data, or {\tt NULL} if not present.
 140
 141
 142 \membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
 143
 144 \constfunc{wxClientData *}{GetClientObject}{\param{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 typed
 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::GetCount}\label{wxcontrolwithitemsgetcount}
 161
 162 \constfunc{int}{GetCount}{\void}
 163
 164 Returns the number of items in the control.
 165
 166 \wxheading{See also}
 167
 168 \helpref{IsEmpty}{wxcontrolwithitemsisempty}
 169
 170
 171 \membersection{wxControlWithItems::GetSelection}\label{wxcontrolwithitemsgetselection}
 172
 173 \constfunc{int}{GetSelection}{\void}
 174
 175 Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
 176 selected.
 177
 178 \wxheading{Return value}
 179
 180 The position of the current selection.
 181
 182 \wxheading{Remarks}
 183
 184 This method can be used with single selection list boxes only, you should use
 185 \helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
 186 with {\tt wxLB\_MULTIPLE} style.
 187
 188 \wxheading{See also}
 189
 190 \helpref{SetSelection}{wxcontrolwithitemssetselection},\rtfsp
 191 \helpref{GetStringSelection}{wxcontrolwithitemsgetstringselection}
 192
 193
 194 \membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
 195
 196 \constfunc{wxString}{GetString}{\param{int}{ n}}
 197
 198 Returns the label of the item with the given index.
 199
 200 \wxheading{Parameters}
 201
 202 \docparam{n}{The zero-based index.}
 203
 204 \wxheading{Return value}
 205
 206 The label of the item or an empty string if the position was invalid.
 207
 208
 209 \membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
 210
 211 \constfunc{wxString}{GetStringSelection}{\void}
 212
 213 Returns the label of the selected item or an empty string if no item is
 214 selected.
 215
 216 \wxheading{See also}
 217
 218 \helpref{GetSelection}{wxcontrolwithitemsgetselection}
 219
 220
 221 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
 222
 223 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}}
 224
 225 Inserts the item into the list before pos.
 226 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 227
 228 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{void *}{clientData}}
 229
 230 \func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{clientData}}
 231
 232 Inserts the item into the list before pos, associating the given, typed or
 233 untyped, client data pointer with the item.
 234 Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.
 235
 236 \wxheading{Parameters}
 237
 238 \docparam{item}{String to add.}
 239
 240 \docparam{pos}{Position to insert item before, zero based.}
 241
 242 \docparam{clientData}{Client data to associate with the item.}
 243
 244 \wxheading{Return value}
 245
 246 The return value is the index of the newly inserted item. If the insertion failed
 247 for some reason, -1 is returned.
 248
 249
 250 \membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}
 251
 252 \constfunc{bool}{IsEmpty}{\void}
 253
 254 Returns {\tt true} if the control is empty or {\tt false} if it has some items.
 255
 256 \wxheading{See also}
 257
 258 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 259
 260
 261 \membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
 262
 263 \constfunc{int}{Number}{\void}
 264
 265 {\bf Obsolescence note:} This method is obsolete and was replaced with
 266 \helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
 267 the new code. This method is only available if wxWidgets was compiled with
 268 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
 269 future versions.
 270
 271
 272 \membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
 273
 274 \func{void}{Select}{\param{int}{ n}}
 275
 276 This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
 277 exists only because it is slightly more natural for controls which support
 278 multiple selection.
 279
 280
 281 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 282
 283 \func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
 284
 285 Associates the given untyped client data pointer with the given item. Note that
 286 it is an error to call this function if any typed client data pointers had been
 287 associated with the control items before.
 288
 289 \wxheading{Parameters}
 290
 291 \docparam{n}{The zero-based item index.}
 292
 293 \docparam{data}{The client data to associate with the item.}
 294
 295
 296 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 297
 298 \func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}}
 299
 300 Associates the given typed client data pointer with the given item: the
 301 {\it data} object will be deleted when the item is deleted (either explicitly
 302 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 303 control itself is destroyed).
 304
 305 Note that it is an error to call this function if any untyped client data
 306 pointers had been associated with the control items before.
 307
 308 \wxheading{Parameters}
 309
 310 \docparam{n}{The zero-based item index.}
 311
 312 \docparam{data}{The client data to associate with the item.}
 313
 314
 315 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
 316
 317 \func{void}{SetSelection}{\param{int}{ n}}
 318
 319 Sets the selection to the given item \arg{n} or removes the selection entirely
 320 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 321
 322 Note that this does not cause any command events to be emitted nor does it
 323 deselect any other items in the controls which support multiple selections.
 324
 325 \wxheading{Parameters}
 326
 327 \docparam{n}{The string position to select, starting from zero.}
 328
 329 \wxheading{See also}
 330
 331 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
 332 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
 333
 334
 335 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 336
 337 \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}
 338
 339 Sets the label for the given item.
 340
 341 \wxheading{Parameters}
 342
 343 \docparam{n}{The zero-based item index.}
 344
 345 \docparam{string}{The label to set.}
 346
 347
 348 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 349
 350 \func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}
 351
 352 Selects the item with the specified string in the control. This doesn't cause
 353 any command events being emitted.
 354
 355 \wxheading{Parameters}
 356
 357 \docparam{string}{The string to select.}
 358
 359 \wxheading{Return value}
 360
 361 \true if the specified string has been selected, \false if it wasn't found in
 362 the control.
 363
 364 \wxheading{See also}
 365
 366 \helpref{SetSelection}{wxcontrolwithitemssetselection}
 367
 368