interface/ctrlsub.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        ctrlsub.h
   3 // Purpose:     documentation for wxControlWithItems class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxControlWithItems
  11     @wxheader{ctrlsub.h}
  12
  13     This class is an abstract base class for some wxWidgets controls which contain
  14     several items, such as wxListBox and
  15     wxCheckListBox derived from it,
  16     wxChoice and wxComboBox.
  17
  18     It defines the methods for accessing the controls items and although each of
  19     the derived classes implements them differently, they still all conform to the
  20     same interface.
  21
  22     The items in a wxControlWithItems have (non-empty) string labels and,
  23     optionally, client data associated with them. Client data may be of two
  24     different kinds: either simple untyped (@c void *) pointers which are simply
  25     stored by the control but not used in any way by it, or typed pointers
  26     (@c wxClientData *) which are owned by the control meaning that the typed
  27     client data (and only it) will be deleted when an item is
  28     @ref wxControlWithItems::delete deleted or the entire control is
  29     @ref wxControlWithItems::clear cleared (which also happens when it is
  30     destroyed). Finally note that in the same control all items must have client
  31     data of the same type (typed or untyped), if any. This type is determined by
  32     the first call to wxControlWithItems::Append (the version with
  33     client data pointer) or wxControlWithItems::SetClientData.
  34
  35     @library{wxcore}
  36     @category{FIXME}
  37
  38     @seealso
  39     wxControlWithItems::Clear
  40 */
  41 class wxControlWithItems : public wxControl
  42 {
  43 public:
  44     //@{
  45     /**
  46         Appends several items at once to the control. Notice that calling this method
  47         is usually much faster than appending them one by one if you need to add a lot
  48         of items.
  49
  50         @param item
  51         String to add.
  52
  53         @param stringsArray
  54         Contains items to append to the control.
  55
  56         @param strings
  57         Array of strings of size n.
  58
  59         @param n
  60         Number of items in the strings array.
  61
  62         @param clientData
  63         Array of client data pointers of size n to associate with the new items.
  64
  65         @returns When appending a single item, the return value is the index of
  66                    the newly added item which may be different from the
  67                    last one if the control is sorted (e.g. has wxLB_SORT
  68                    or wxCB_SORT style).
  69     */
  70     int Append(const wxString& item);
  71     int Append(const wxString& item, void * clientData);
  72     int Append(const wxString& item, wxClientData * clientData);
  73     void Append(const wxArrayString& strings);
  74     void Append(unsigned int n, const wxString* strings);
  75     void Append(unsigned int n, const wxString* strings,
  76                 void ** clientData);
  77     void Append(unsigned int n, const wxString* strings,
  78                 wxClientData ** clientData);
  79     //@}
  80
  81     /**
  82         Removes all items from the control.
  83
  84         @e Clear() also deletes the client data of the existing items if it is owned
  85         by the control.
  86     */
  87     void Clear();
  88
  89     /**
  90         Deletes an item from the control. The client data associated with the item
  91         will be also deleted if it is owned by the control.
  92
  93         Note that it is an error (signalled by an assert failure in debug builds) to
  94         remove an item with the index negative or greater or equal than the number of
  95         items in the control.
  96
  97         @param n
  98         The zero-based item index.
  99
 100         @sa Clear()
 101     */
 102     void Delete(unsigned int n);
 103
 104     /**
 105         Finds an item whose label matches the given string.
 106
 107         @param string
 108         String to find.
 109
 110         @param caseSensitive
 111         Whether search is case sensitive (default is not).
 112
 113         @returns The zero-based position of the item, or wxNOT_FOUND if the
 114                    string was not found.
 115     */
 116     int FindString(const wxString& string,
 117                    bool caseSensitive = @false);
 118
 119     /**
 120         Returns a pointer to the client data associated with the given item (if any).
 121         It is an error to call this function for a control which doesn't have untyped
 122         client data at all although it is ok to call it even if the given item doesn't
 123         have any client data associated with it (but other items do).
 124
 125         @param n
 126         The zero-based position of the item.
 127
 128         @returns A pointer to the client data, or @NULL if not present.
 129     */
 130     void * GetClientData(unsigned int n);
 131
 132     /**
 133         Returns a pointer to the client data associated with the given item (if any).
 134         It is an error to call this function for a control which doesn't have typed
 135         client data at all although it is ok to call it even if the given item doesn't
 136         have any client data associated with it (but other items do).
 137
 138         @param n
 139         The zero-based position of the item.
 140
 141         @returns A pointer to the client data, or @NULL if not present.
 142     */
 143     wxClientData * GetClientObject(unsigned int n);
 144
 145     /**
 146         Returns the number of items in the control.
 147
 148         @sa IsEmpty()
 149     */
 150     unsigned int GetCount();
 151
 152     /**
 153         Returns the index of the selected item or @c wxNOT_FOUND if no item is
 154         selected.
 155
 156         @returns The position of the current selection.
 157
 158         @remarks This method can be used with single selection list boxes only,
 159                    you should use wxListBox::GetSelections for the list
 160                    boxes with wxLB_MULTIPLE style.
 161
 162         @sa SetSelection(), GetStringSelection()
 163     */
 164     int GetSelection();
 165
 166     /**
 167         Returns the label of the item with the given index.
 168
 169         @param n
 170         The zero-based index.
 171
 172         @returns The label of the item or an empty string if the position was
 173                    invalid.
 174     */
 175     wxString GetString(unsigned int n);
 176
 177     /**
 178         Returns the label of the selected item or an empty string if no item is
 179         selected.
 180
 181         @sa GetSelection()
 182     */
 183     wxString GetStringSelection();
 184
 185     /**
 186         Returns the array of the labels of all items in the control.
 187     */
 188     wxArrayString GetStrings();
 189
 190     //@{
 191     /**
 192         Inserts several items at once into the control. Notice that calling this method
 193         is usually much faster than inserting them one by one if you need to insert a
 194         lot
 195         of items.
 196
 197         @param item
 198         String to add.
 199
 200         @param pos
 201         Position to insert item before, zero based.
 202
 203         @param stringsArray
 204         Contains items to insert into the control content
 205
 206         @param strings
 207         Array of strings of size n.
 208
 209         @param n
 210         Number of items in the strings array.
 211
 212         @param clientData
 213         Array of client data pointers of size n to associate with the new items.
 214
 215         @returns The return value is the index of the newly inserted item. If the
 216                    insertion failed for some reason, -1 is returned.
 217     */
 218     int Insert(const wxString& item, unsigned int pos);
 219     int Insert(const wxString& item, unsigned int pos,
 220                void * clientData);
 221     int Insert(const wxString& item, unsigned int pos,
 222                wxClientData * clientData);
 223     void Insert(const wxArrayString& strings, unsigned int pos);
 224     void Insert(const wxArrayString& strings, unsigned int pos);
 225     void Insert(unsigned int n, const wxString* strings,
 226                 unsigned int pos);
 227     void Insert(unsigned int n, const wxString* strings,
 228                 unsigned int pos,
 229                 void ** clientData);
 230     void Insert(unsigned int n, const wxString* strings,
 231                 unsigned int pos,
 232                 wxClientData ** clientData);
 233     //@}
 234
 235     /**
 236         Returns @true if the control is empty or @false if it has some items.
 237
 238         @sa GetCount()
 239     */
 240     bool IsEmpty();
 241
 242     /**
 243         This is the same as SetSelection() and
 244         exists only because it is slightly more natural for controls which support
 245         multiple selection.
 246     */
 247     void Select(int n);
 248
 249     //@{
 250     /**
 251         Replaces the current control contents with the given items. Notice that calling
 252         this method is much faster than appending the items one by one if you need to
 253         append a lot of them.
 254
 255         @param item
 256         The single item to insert into the control.
 257
 258         @param stringsArray
 259         Contains items to set as control content.
 260
 261         @param strings
 262         Raw C++ array of strings. Only used in conjunction with 'n'.
 263
 264         @param n
 265         Number of items passed in 'strings'. Only used in conjunction with 'strings'.
 266
 267         @param clientData
 268         Client data to associate with the item(s).
 269
 270         @returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
 271                    style) the return value could be different from
 272                    (GetCount() - 1). When setting a single item to the
 273                    container, the return value is the index of the newly
 274                    added item which may be different from the last one
 275                    if the control is sorted (e.g. has wxLB_SORT or
 276                    wxCB_SORT style).
 277     */
 278     int Set(const wxString& item);
 279     int Set(const wxString& item, void * clientData);
 280     int Set(const wxString& item, wxClientData * clientData);
 281     void Set(const wxArrayString& stringsArray);
 282     void Set(unsigned int n, const wxString* strings);
 283     void Set(unsigned int n, const wxString* strings,
 284              void ** clientData);
 285     void Set(unsigned int n, const wxString* strings,
 286              wxClientData ** clientData);
 287     //@}
 288
 289     /**
 290         Associates the given untyped client data pointer with the given item. Note that
 291         it is an error to call this function if any typed client data pointers had been
 292         associated with the control items before.
 293
 294         @param n
 295         The zero-based item index.
 296
 297         @param data
 298         The client data to associate with the item.
 299     */
 300     void SetClientData(unsigned int n, void * data);
 301
 302     /**
 303         Associates the given typed client data pointer with the given item: the
 304         @e data object will be deleted when the item is deleted (either explicitly
 305         by using @ref delete() Deletes or implicitly when the
 306         control itself is destroyed).
 307
 308         Note that it is an error to call this function if any untyped client data
 309         pointers had been associated with the control items before.
 310
 311         @param n
 312         The zero-based item index.
 313
 314         @param data
 315         The client data to associate with the item.
 316     */
 317     void SetClientObject(unsigned int n, wxClientData * data);
 318
 319     /**
 320         Sets the selection to the given item @e n or removes the selection entirely
 321         if @e n == @c wxNOT_FOUND.
 322
 323         Note that this does not cause any command events to be emitted nor does it
 324         deselect any other items in the controls which support multiple selections.
 325
 326         @param n
 327         The string position to select, starting from zero.
 328
 329         @sa SetString(), SetStringSelection()
 330     */
 331     void SetSelection(int n);
 332
 333     /**
 334         Sets the label for the given item.
 335
 336         @param n
 337         The zero-based item index.
 338
 339         @param string
 340         The label to set.
 341     */
 342     void SetString(unsigned int n, const wxString& string);
 343
 344     /**
 345         Selects the item with the specified string in the control. This doesn't cause
 346         any command events to be emitted.
 347
 348         @param string
 349         The string to select.
 350
 351         @returns @true if the specified string has been selected, @false if it
 352                    wasn't found in the control.
 353     */
 354     bool SetStringSelection(const wxString& string);
 355 };