include/wx/ctrlsub.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/ctrlsub.h (read: "wxConTRoL with SUBitems")
   3 // Purpose:     wxControlWithItems interface
   4 // Author:      Vadim Zeitlin
   5 // Modified by:
   6 // Created:     22.10.99
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) wxWidgets team
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_CTRLSUB_H_BASE_
  13 #define _WX_CTRLSUB_H_BASE_
  14
  15 #include "wx/defs.h"
  16
  17 #if wxUSE_CONTROLS
  18
  19 #include "wx/arrstr.h"
  20 #include "wx/control.h"      // base class
  21
  22 // ----------------------------------------------------------------------------
  23 // wxItemContainer defines an interface which is implemented by all controls
  24 // which have string subitems each of which may be selected.
  25 //
  26 // It is decomposed in wxItemContainerImmutable which omits all methods
  27 // adding/removing items and is used by wxRadioBox and wxItemContainer itself.
  28 //
  29 // Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which
  30 // implements an extended interface deriving from this one)
  31 // ----------------------------------------------------------------------------
  32
  33 class WXDLLIMPEXP_CORE wxItemContainerImmutable
  34 {
  35 public:
  36     wxItemContainerImmutable() { }
  37     virtual ~wxItemContainerImmutable();
  38
  39     // accessing strings
  40     // -----------------
  41
  42     virtual unsigned int GetCount() const = 0;
  43     bool IsEmpty() const { return GetCount() == 0; }
  44
  45     virtual wxString GetString(unsigned int n) const = 0;
  46     wxArrayString GetStrings() const;
  47     virtual void SetString(unsigned int n, const wxString& s) = 0;
  48
  49     // finding string natively is either case sensitive or insensitive
  50     // but never both so fall back to this base version for not
  51     // supported search type
  52     virtual int FindString(const wxString& s, bool bCase = false) const
  53     {
  54         unsigned int count = GetCount();
  55
  56         for ( unsigned int i = 0; i < count ; ++i )
  57         {
  58             if (GetString(i).IsSameAs( s , bCase ))
  59                 return (int)i;
  60         }
  61
  62         return wxNOT_FOUND;
  63     }
  64
  65
  66     // selection
  67     // ---------
  68
  69     virtual void SetSelection(int n) = 0;
  70     virtual int GetSelection() const = 0;
  71
  72     // set selection to the specified string, return false if not found
  73     bool SetStringSelection(const wxString& s);
  74
  75     // return the selected string or empty string if none
  76     virtual wxString GetStringSelection() const;
  77
  78     // this is the same as SetSelection( for single-selection controls but
  79     // reads better for multi-selection ones
  80     void Select(int n) { SetSelection(n); }
  81
  82
  83 protected:
  84     // check that the index is valid
  85     bool IsValid(unsigned int n) const { return n < GetCount(); }
  86     bool IsValidInsert(unsigned int n) const { return n <= GetCount(); }
  87 };
  88
  89 // ----------------------------------------------------------------------------
  90 // wxItemContainer extends wxItemContainerImmutable interface with methods
  91 // for adding/removing items.
  92 //
  93 // Classes deriving from this one must override DoInsertItems() to implement
  94 // adding items to the control. This can often be implemented more efficiently
  95 // than simply looping over the elements and inserting them but if this is not
  96 // the case, the generic DoInsertItemsInLoop can be used in implementation, but
  97 // in this case DoInsertItem() needs to be overridden.
  98 // ----------------------------------------------------------------------------
  99
 100 class WXDLLIMPEXP_CORE wxItemContainer : public wxItemContainerImmutable
 101 {
 102 private:
 103     // AppendItems() and InsertItems() helpers just call DoAppend/InsertItems()
 104     // after doing some checks
 105     //
 106     // NB: they're defined here so that they're inlined when used in public part
 107     int AppendItems(const wxArrayStringsAdapter& items,
 108                     void **clientData,
 109                     wxClientDataType type)
 110     {
 111         if ( items.IsEmpty() )
 112             return wxNOT_FOUND;
 113
 114         return DoAppendItems(items, clientData, type);
 115     }
 116
 117     int AppendItems(const wxArrayStringsAdapter& items)
 118     {
 119         return AppendItems(items, NULL, wxClientData_None);
 120     }
 121
 122     int AppendItems(const wxArrayStringsAdapter& items, void **clientData)
 123     {
 124         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,
 125                       wxT("can't mix different types of client data") );
 126
 127         return AppendItems(items, clientData, wxClientData_Void);
 128     }
 129
 130     int AppendItems(const wxArrayStringsAdapter& items,
 131                     wxClientData **clientData)
 132     {
 133         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,
 134                       wxT("can't mix different types of client data") );
 135
 136         return AppendItems(items, reinterpret_cast<void **>(clientData),
 137                            wxClientData_Object);
 138     }
 139
 140     int InsertItems(const wxArrayStringsAdapter& items,
 141                     unsigned int pos,
 142                     void **clientData,
 143                     wxClientDataType type)
 144     {
 145         wxASSERT_MSG( !IsSorted(), wxT("can't insert items in sorted control") );
 146
 147         wxCHECK_MSG( pos <= GetCount(), wxNOT_FOUND,
 148                      wxT("position out of range") );
 149
 150         // not all derived classes handle empty arrays correctly in
 151         // DoInsertItems() and besides it really doesn't make much sense to do
 152         // this (for append it could correspond to creating an initially empty
 153         // control but why would anybody need to insert 0 items?)
 154         wxCHECK_MSG( !items.IsEmpty(), wxNOT_FOUND,
 155                      wxT("need something to insert") );
 156
 157         return DoInsertItems(items, pos, clientData, type);
 158     }
 159
 160     int InsertItems(const wxArrayStringsAdapter& items, unsigned int pos)
 161     {
 162         return InsertItems(items, pos, NULL, wxClientData_None);
 163     }
 164
 165     int InsertItems(const wxArrayStringsAdapter& items,
 166                      unsigned int pos,
 167                      void **clientData)
 168     {
 169         wxASSERT_MSG( GetClientDataType() != wxClientData_Object,
 170                       wxT("can't mix different types of client data") );
 171
 172         return InsertItems(items, pos, clientData, wxClientData_Void);
 173     }
 174
 175     int InsertItems(const wxArrayStringsAdapter& items,
 176                      unsigned int pos,
 177                      wxClientData **clientData)
 178     {
 179         wxASSERT_MSG( GetClientDataType() != wxClientData_Void,
 180                       wxT("can't mix different types of client data") );
 181
 182         return InsertItems(items, pos,
 183                            reinterpret_cast<void **>(clientData),
 184                            wxClientData_Object);
 185     }
 186
 187 public:
 188     wxItemContainer() { m_clientDataItemsType = wxClientData_None; }
 189     virtual ~wxItemContainer();
 190
 191     // adding items
 192     // ------------
 193
 194     // append single item, return its position in the control (which can be
 195     // different from the last one if the control is sorted)
 196     int Append(const wxString& item)
 197         { return AppendItems(item); }
 198     int Append(const wxString& item, void *clientData)
 199         { return AppendItems(item, &clientData); }
 200     int Append(const wxString& item, wxClientData *clientData)
 201         { return AppendItems(item, &clientData); }
 202
 203     // append several items at once to the control, return the position of the
 204     // last item appended
 205     int Append(const wxArrayString& items)
 206         { return AppendItems(items); }
 207     int Append(const wxArrayString& items, void **clientData)
 208         { return AppendItems(items, clientData); }
 209     int Append(const wxArrayString& items, wxClientData **clientData)
 210         { return AppendItems(items, clientData); }
 211     int Append(unsigned int n, const wxString *items)
 212         { return AppendItems(wxArrayStringsAdapter(n, items)); }
 213     int Append(unsigned int n, const wxString *items, void **clientData)
 214         { return AppendItems(wxArrayStringsAdapter(n, items), clientData); }
 215     int Append(unsigned int n,
 216                const wxString *items,
 217                wxClientData **clientData)
 218         { return AppendItems(wxArrayStringsAdapter(n, items), clientData); }
 219
 220     // only for RTTI needs (separate name)
 221     void AppendString(const wxString& item)
 222         { Append(item); }
 223
 224
 225     // inserting items: not for sorted controls!
 226     // -----------------------------------------
 227
 228     // insert single item at the given position, return its effective position
 229     int Insert(const wxString& item, unsigned int pos)
 230         { return InsertItems(item, pos); }
 231     int Insert(const wxString& item, unsigned int pos, void *clientData)
 232         { return InsertItems(item, pos, &clientData); }
 233     int Insert(const wxString& item, unsigned int pos, wxClientData *clientData)
 234         { return InsertItems(item, pos, &clientData); }
 235
 236     // insert several items at once into the control, return the index of the
 237     // last item inserted
 238     int Insert(const wxArrayString& items, unsigned int pos)
 239         { return InsertItems(items, pos); }
 240     int Insert(const wxArrayString& items, unsigned int pos, void **clientData)
 241         { return InsertItems(items, pos, clientData); }
 242     int Insert(const wxArrayString& items,
 243                unsigned int pos,
 244                wxClientData **clientData)
 245         { return InsertItems(items, pos, clientData); }
 246     int Insert(unsigned int n, const wxString *items, unsigned int pos)
 247         { return InsertItems(wxArrayStringsAdapter(n, items), pos); }
 248     int Insert(unsigned int n,
 249                const wxString *items,
 250                unsigned int pos,
 251                void **clientData)
 252         { return InsertItems(wxArrayStringsAdapter(n, items), pos, clientData); }
 253     int Insert(unsigned int n,
 254                const wxString *items,
 255                unsigned int pos,
 256                wxClientData **clientData)
 257         { return InsertItems(wxArrayStringsAdapter(n, items), pos, clientData); }
 258
 259
 260     // replacing items
 261     // ---------------
 262
 263     void Set(const wxArrayString& items)
 264         { Clear(); Append(items); }
 265     void Set(const wxArrayString& items, void **clientData)
 266         { Clear(); Append(items, clientData); }
 267     void Set(const wxArrayString& items, wxClientData **clientData)
 268         { Clear(); Append(items, clientData); }
 269     void Set(unsigned int n, const wxString *items)
 270         { Clear(); Append(n, items); }
 271     void Set(unsigned int n, const wxString *items, void **clientData)
 272         { Clear(); Append(n, items, clientData); }
 273     void Set(unsigned int n, const wxString *items, wxClientData **clientData)
 274         { Clear(); Append(n, items, clientData); }
 275
 276     // deleting items
 277     // --------------
 278
 279     void Clear();
 280     void Delete(unsigned int pos);
 281
 282
 283     // various accessors
 284     // -----------------
 285
 286     // The control may maintain its items in a sorted order in which case
 287     // items are automatically inserted at the right position when they are
 288     // inserted or appended. Derived classes have to override this method if
 289     // they implement sorting, typically by returning HasFlag(wxXX_SORT)
 290     virtual bool IsSorted() const { return false; }
 291
 292
 293     // client data stuff
 294     // -----------------
 295
 296     void SetClientData(unsigned int n, void* clientData);
 297     void* GetClientData(unsigned int n) const;
 298
 299     // SetClientObject() takes ownership of the pointer, GetClientObject()
 300     // returns it but keeps the ownership while DetachClientObject() expects
 301     // the caller to delete the pointer and also resets the internally stored
 302     // one to NULL for this item
 303     void SetClientObject(unsigned int n, wxClientData* clientData);
 304     wxClientData* GetClientObject(unsigned int n) const;
 305     wxClientData* DetachClientObject(unsigned int n);
 306
 307     // return the type of client data stored in this control: usually it just
 308     // returns m_clientDataItemsType but must be overridden in the controls
 309     // which delegate their client data storage to another one (e.g. wxChoice
 310     // in wxUniv which stores data in wxListBox which it uses anyhow); don't
 311     // forget to override SetClientDataType() if you override this one
 312     //
 313     // NB: for this to work no code should ever access m_clientDataItemsType
 314     //     directly but only via this function!
 315     virtual wxClientDataType GetClientDataType() const
 316         { return m_clientDataItemsType; }
 317
 318     bool HasClientData() const
 319         { return GetClientDataType() != wxClientData_None; }
 320     bool HasClientObjectData() const
 321         { return GetClientDataType() == wxClientData_Object; }
 322     bool HasClientUntypedData() const
 323         { return GetClientDataType() == wxClientData_Void; }
 324
 325 protected:
 326     // there is usually no need to override this method but you can do it if it
 327     // is more convenient to only do "real" insertions in DoInsertItems() and
 328     // to implement items appending here (in which case DoInsertItems() should
 329     // call this method if pos == GetCount() as it can still be called in this
 330     // case if public Insert() is called with such position)
 331     virtual int DoAppendItems(const wxArrayStringsAdapter& items,
 332                               void **clientData,
 333                               wxClientDataType type)
 334     {
 335         return DoInsertItems(items, GetCount(), clientData, type);
 336     }
 337
 338     // this method must be implemented to insert the items into the control at
 339     // position pos which can be GetCount() meaning that the items should be
 340     // appended; for the sorted controls the position can be ignored
 341     //
 342     // the derived classes typically use AssignNewItemClientData() to
 343     // associate the data with the items as they're being inserted
 344     //
 345     // the method should return the index of the position the last item was
 346     // inserted into or wxNOT_FOUND if an error occurred
 347     virtual int DoInsertItems(const wxArrayStringsAdapter & items,
 348                               unsigned int pos,
 349                               void **clientData,
 350                               wxClientDataType type) = 0;
 351
 352     // before the client data is set for the first time for the control which
 353     // hadn't had it before, DoInitItemClientData() is called which gives the
 354     // derived class the possibility to initialize its client data storage only
 355     // when client data is really used
 356     virtual void DoInitItemClientData() { }
 357     virtual void DoSetItemClientData(unsigned int n, void *clientData) = 0;
 358     virtual void *DoGetItemClientData(unsigned int n) const = 0;
 359
 360     virtual void DoClear() = 0;
 361     virtual void DoDeleteOneItem(unsigned int pos) = 0;
 362
 363
 364     // methods useful for the derived classes which don't have any better way
 365     // of adding multiple items to the control than doing it one by one: such
 366     // classes should call DoInsertItemsInLoop() from their DoInsert() and
 367     // override DoInsertOneItem() to perform the real insertion
 368     virtual int DoInsertOneItem(const wxString& item, unsigned int pos);
 369     int DoInsertItemsInLoop(const wxArrayStringsAdapter& items,
 370                             unsigned int pos,
 371                             void **clientData,
 372                             wxClientDataType type);
 373
 374
 375     // helper for DoInsertItems(): n is the index into clientData, pos is the
 376     // position of the item in the control
 377     void AssignNewItemClientData(unsigned int pos,
 378                                  void **clientData,
 379                                  unsigned int n,
 380                                  wxClientDataType type);
 381
 382     // free the client object associated with the item at given position and
 383     // set it to NULL (must only be called if HasClientObjectData())
 384     void ResetItemClientObject(unsigned int n);
 385
 386     // set the type of the client data stored in this control: override this if
 387     // you override GetClientDataType()
 388     virtual void SetClientDataType(wxClientDataType clientDataItemsType)
 389     {
 390         m_clientDataItemsType = clientDataItemsType;
 391     }
 392
 393 private:
 394     // the type of the client data for the items
 395     wxClientDataType m_clientDataItemsType;
 396 };
 397
 398 // Inheriting directly from a wxWindow-derived class and wxItemContainer
 399 // unfortunately introduces an ambiguity for all GetClientXXX() methods as they
 400 // are inherited twice: the "global" versions from wxWindow and the per-item
 401 // versions taking the index from wxItemContainer.
 402 //
 403 // So we need to explicitly resolve them and this helper template class is
 404 // provided to do it. To use it, simply inherit from wxWindowWithItems<Window,
 405 // Container> instead of Window and Container interface directly.
 406 template <class W, class C>
 407 class wxWindowWithItems : public W, public C
 408 {
 409 public:
 410     typedef W BaseWindowClass;
 411     typedef C BaseContainerInterface;
 412
 413     wxWindowWithItems() { }
 414
 415     void SetClientData(void *data)
 416         { BaseWindowClass::SetClientData(data); }
 417     void *GetClientData() const
 418         { return BaseWindowClass::GetClientData(); }
 419     void SetClientObject(wxClientData *data)
 420         { BaseWindowClass::SetClientObject(data); }
 421     wxClientData *GetClientObject() const
 422         { return BaseWindowClass::GetClientObject(); }
 423
 424     void SetClientData(unsigned int n, void* clientData)
 425         { wxItemContainer::SetClientData(n, clientData); }
 426     void* GetClientData(unsigned int n) const
 427         { return wxItemContainer::GetClientData(n); }
 428     void SetClientObject(unsigned int n, wxClientData* clientData)
 429         { wxItemContainer::SetClientObject(n, clientData); }
 430     wxClientData* GetClientObject(unsigned int n) const
 431         { return wxItemContainer::GetClientObject(n); }
 432 };
 433
 434 class WXDLLIMPEXP_CORE wxControlWithItemsBase :
 435     public wxWindowWithItems<wxControl, wxItemContainer>
 436 {
 437 public:
 438     wxControlWithItemsBase() { }
 439
 440     // usually the controls like list/combo boxes have their own background
 441     // colour
 442     virtual bool ShouldInheritColours() const { return false; }
 443
 444 protected:
 445     // fill in the client object or data field of the event as appropriate
 446     //
 447     // calls InitCommandEvent() and, if n != wxNOT_FOUND, also sets the per
 448     // item client data
 449     void InitCommandEventWithItems(wxCommandEvent& event, int n);
 450
 451 private:
 452     wxDECLARE_NO_COPY_CLASS(wxControlWithItemsBase);
 453 };
 454
 455 // define the platform-specific wxControlWithItems class
 456 #if defined(__WXMSW__)
 457     #include "wx/msw/ctrlsub.h"
 458 #elif defined(__WXMOTIF__)
 459     #include "wx/motif/ctrlsub.h"
 460 #else
 461     class WXDLLIMPEXP_CORE wxControlWithItems : public wxControlWithItemsBase
 462     {
 463     public:
 464         wxControlWithItems() { }
 465
 466     private:
 467         DECLARE_ABSTRACT_CLASS(wxControlWithItems)
 468         wxDECLARE_NO_COPY_CLASS(wxControlWithItems);
 469     };
 470 #endif
 471
 472 #endif // wxUSE_CONTROLS
 473
 474 #endif // _WX_CTRLSUB_H_BASE_