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         @param stringsArray
  53             Contains items to append to the control.
  54         @param strings
  55             Array of strings of size n.
  56         @param n
  57             Number of items in the strings array.
  58         @param clientData
  59             Array of client data pointers of size n to associate with the new items.
  60
  61         @returns When appending a single item, the return value is the index of
  62                  the newly added item which may be different from the
  63                  last one if the control is sorted (e.g. has wxLB_SORT
  64                  or wxCB_SORT style).
  65     */
  66     int Append(const wxString& item);
  67     int Append(const wxString& item, void* clientData);
  68     int Append(const wxString& item, wxClientData* clientData);
  69     void Append(const wxArrayString& strings);
  70     void Append(unsigned int n, const wxString* strings);
  71     void Append(unsigned int n, const wxString* strings,
  72                 void** clientData);
  73     void Append(unsigned int n, const wxString* strings,
  74                 wxClientData** clientData);
  75     //@}
  76
  77     /**
  78         Removes all items from the control.
  79         @e Clear() also deletes the client data of the existing items if it is owned
  80         by the control.
  81     */
  82     void Clear();
  83
  84     /**
  85         Deletes an item from the control. The client data associated with the item
  86         will be also deleted if it is owned by the control.
  87         Note that it is an error (signalled by an assert failure in debug builds) to
  88         remove an item with the index negative or greater or equal than the number of
  89         items in the control.
  90
  91         @param n
  92             The zero-based item index.
  93
  94         @see Clear()
  95     */
  96     void Delete(unsigned int n);
  97
  98     /**
  99         Finds an item whose label matches the given string.
 100
 101         @param string
 102             String to find.
 103         @param caseSensitive
 104             Whether search is case sensitive (default is not).
 105
 106         @returns The zero-based position of the item, or wxNOT_FOUND if the
 107                  string was not found.
 108     */
 109     int FindString(const wxString& string,
 110                    bool caseSensitive = false);
 111
 112     /**
 113         Returns a pointer to the client data associated with the given item (if any).
 114         It is an error to call this function for a control which doesn't have untyped
 115         client data at all although it is ok to call it even if the given item doesn't
 116         have any client data associated with it (but other items do).
 117
 118         @param n
 119             The zero-based position of the item.
 120
 121         @returns A pointer to the client data, or @NULL if not present.
 122     */
 123     void* GetClientData(unsigned int n);
 124
 125     /**
 126         Returns a pointer to the client data associated with the given item (if any).
 127         It is an error to call this function for a control which doesn't have typed
 128         client data at all although it is ok to call it even if the given item doesn't
 129         have any client data associated with it (but other items do).
 130
 131         @param n
 132             The zero-based position of the item.
 133
 134         @returns A pointer to the client data, or @NULL if not present.
 135     */
 136     wxClientData* GetClientObject(unsigned int n);
 137
 138     /**
 139         Returns the number of items in the control.
 140
 141         @see IsEmpty()
 142     */
 143     unsigned int GetCount();
 144
 145     /**
 146         Returns the index of the selected item or @c wxNOT_FOUND if no item is
 147         selected.
 148
 149         @returns The position of the current selection.
 150
 151         @remarks This method can be used with single selection list boxes only,
 152                  you should use wxListBox::GetSelections for the list
 153                  boxes with wxLB_MULTIPLE style.
 154
 155         @see SetSelection(), GetStringSelection()
 156     */
 157     int GetSelection();
 158
 159     /**
 160         Returns the label of the item with the given index.
 161
 162         @param n
 163             The zero-based index.
 164
 165         @returns The label of the item or an empty string if the position was
 166                  invalid.
 167     */
 168     wxString GetString(unsigned int n);
 169
 170     /**
 171         Returns the label of the selected item or an empty string if no item is
 172         selected.
 173
 174         @see GetSelection()
 175     */
 176     wxString GetStringSelection();
 177
 178     /**
 179         Returns the array of the labels of all items in the control.
 180     */
 181     wxArrayString GetStrings();
 182
 183     //@{
 184     /**
 185         Inserts several items at once into the control. Notice that calling this method
 186         is usually much faster than inserting them one by one if you need to insert a
 187         lot
 188         of items.
 189
 190         @param item
 191             String to add.
 192         @param pos
 193             Position to insert item before, zero based.
 194         @param stringsArray
 195             Contains items to insert into the control content
 196         @param strings
 197             Array of strings of size n.
 198         @param n
 199             Number of items in the strings array.
 200         @param clientData
 201             Array of client data pointers of size n to associate with the new items.
 202
 203         @returns The return value is the index of the newly inserted item. If the
 204                  insertion failed for some reason, -1 is returned.
 205     */
 206     int Insert(const wxString& item, unsigned int pos);
 207     int Insert(const wxString& item, unsigned int pos,
 208                void* clientData);
 209     int Insert(const wxString& item, unsigned int pos,
 210                wxClientData* clientData);
 211     void Insert(const wxArrayString& strings, unsigned int pos);
 212     void Insert(const wxArrayString& strings, unsigned int pos);
 213     void Insert(unsigned int n, const wxString* strings,
 214                 unsigned int pos);
 215     void Insert(unsigned int n, const wxString* strings,
 216                 unsigned int pos,
 217                 void** clientData);
 218     void Insert(unsigned int n, const wxString* strings,
 219                 unsigned int pos,
 220                 wxClientData** clientData);
 221     //@}
 222
 223     /**
 224         Returns @true if the control is empty or @false if it has some items.
 225
 226         @see GetCount()
 227     */
 228     bool IsEmpty();
 229
 230     /**
 231         This is the same as SetSelection() and
 232         exists only because it is slightly more natural for controls which support
 233         multiple selection.
 234     */
 235     void Select(int n);
 236
 237     //@{
 238     /**
 239         Replaces the current control contents with the given items. Notice that calling
 240         this method is much faster than appending the items one by one if you need to
 241         append a lot of them.
 242
 243         @param item
 244             The single item to insert into the control.
 245         @param stringsArray
 246             Contains items to set as control content.
 247         @param strings
 248             Raw C++ array of strings. Only used in conjunction with 'n'.
 249         @param n
 250             Number of items passed in 'strings'. Only used in conjunction with
 251         'strings'.
 252         @param clientData
 253             Client data to associate with the item(s).
 254
 255         @returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
 256                  style) the return value could be different from
 257                  (GetCount() - 1). When setting a single item to the
 258                  container, the return value is the index of the newly
 259                  added item which may be different from the last one if
 260                  the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
 261                  style).
 262     */
 263     int Set(const wxString& item);
 264     int Set(const wxString& item, void* clientData);
 265     int Set(const wxString& item, wxClientData* clientData);
 266     void Set(const wxArrayString& stringsArray);
 267     void Set(unsigned int n, const wxString* strings);
 268     void Set(unsigned int n, const wxString* strings,
 269              void** clientData);
 270     void Set(unsigned int n, const wxString* strings,
 271              wxClientData** clientData);
 272     //@}
 273
 274     /**
 275         Associates the given untyped client data pointer with the given item. Note that
 276         it is an error to call this function if any typed client data pointers had been
 277         associated with the control items before.
 278
 279         @param n
 280             The zero-based item index.
 281         @param data
 282             The client data to associate with the item.
 283     */
 284     void SetClientData(unsigned int n, void* data);
 285
 286     /**
 287         Associates the given typed client data pointer with the given item: the
 288         @a data object will be deleted when the item is deleted (either explicitly
 289         by using @ref delete() Deletes or implicitly when the
 290         control itself is destroyed).
 291         Note that it is an error to call this function if any untyped client data
 292         pointers had been associated with the control items before.
 293
 294         @param n
 295             The zero-based item index.
 296         @param data
 297             The client data to associate with the item.
 298     */
 299     void SetClientObject(unsigned int n, wxClientData* data);
 300
 301     /**
 302         Sets the selection to the given item @a n or removes the selection entirely
 303         if @a n == @c wxNOT_FOUND.
 304         Note that this does not cause any command events to be emitted nor does it
 305         deselect any other items in the controls which support multiple selections.
 306
 307         @param n
 308             The string position to select, starting from zero.
 309
 310         @see SetString(), SetStringSelection()
 311     */
 312     void SetSelection(int n);
 313
 314     /**
 315         Sets the label for the given item.
 316
 317         @param n
 318             The zero-based item index.
 319         @param string
 320             The label to set.
 321     */
 322     void SetString(unsigned int n, const wxString& string);
 323
 324     /**
 325         Selects the item with the specified string in the control. This doesn't cause
 326         any command events to be emitted.
 327
 328         @param string
 329             The string to select.
 330
 331         @returns @true if the specified string has been selected, @false if it
 332                  wasn't found in the control.
 333     */
 334     bool SetStringSelection(const wxString& string);
 335 };