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 wxWindows 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::IsEmpty}\label{wxcontrolwithitemsisempty}
 222
 223 \constfunc{bool}{IsEmpty}{\void}
 224
 225 Returns {\tt true} if the control is empty or {\tt false} if it has some items.
 226
 227 \wxheading{See also}
 228
 229 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 230
 231
 232 \membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
 233
 234 \constfunc{int}{Number}{\void}
 235
 236 {\bf Obsolescence note:} This method is obsolete and was replaced with
 237 \helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
 238 the new code. This method is only available if wxWindows was compiled with
 239 {\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
 240 future versions.
 241
 242
 243 \membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}
 244
 245 \func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
 246
 247 Associates the given untyped client data pointer with the given item. Note that
 248 it is an error to call this function if any typed client data pointers had been
 249 associated with the control items before.
 250
 251 \wxheading{Parameters}
 252
 253 \docparam{n}{The zero-based item index.}
 254
 255 \docparam{data}{The client data to associate with the item.}
 256
 257
 258 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 259
 260 \func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}}
 261
 262 Associates the given typed client data pointer with the given item: the
 263 {\it data} object will be deleted when the item is deleted (either explicitly
 264 by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
 265 control itself is destroyed).
 266
 267 Note that it is an error to call this function if any untyped client data
 268 pointers had been associated with the control items before.
 269
 270 \wxheading{Parameters}
 271
 272 \docparam{n}{The zero-based item index.}
 273
 274 \docparam{data}{The client data to associate with the item.}
 275
 276
 277 \membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}
 278
 279 \func{void}{SetSelection}{\param{int}{ n}}
 280
 281 Sets the choice by passing the desired string position. This does not cause
 282 any command events to get emitted.
 283
 284 \wxheading{Parameters}
 285
 286 \docparam{n}{The string position to select, starting from zero.}
 287
 288 \wxheading{See also}
 289
 290 \helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
 291 \helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}
 292
 293
 294 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 295
 296 \func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}
 297
 298 Sets the label for the given item.
 299
 300 \wxheading{Parameters}
 301
 302 \docparam{n}{The zero-based item index.}
 303
 304 \docparam{string}{The label to set.}
 305
 306
 307 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 308
 309 \func{void}{SetStringSelection}{\param{const wxString\& }{ string}}
 310
 311 Selects the item with the specified string in the control. This doesn't cause
 312 any command events being emitted.
 313
 314 \wxheading{Parameters}
 315
 316 \docparam{string}{The string to select.}
 317
 318 \wxheading{See also}
 319
 320 \helpref{SetSelection}{wxcontrolwithitemssetselection}
 321
 322