interface/ctrlsub.h

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