| 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::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{unsigned 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{unsigned int }{pos}, \param{void *}{clientData}} |
| 231 | |
| 232 | \func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned 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{unsigned 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{unsigned 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{unsigned 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} |