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