include/wx/list.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        list.h
   3 // Purpose:     wxList, wxStringList classes
   4 // Author:      Julian Smart
   5 // Modified by: VZ at 16/11/98: WX_DECLARE_LIST() and typesafe lists added
   6 // Created:     29/01/98
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 1998 Julian Smart
   9 // Licence:     wxWindows license
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 /*
  13   All this is quite ugly but serves two purposes:
  14     1. Be almost 100% compatible with old, untyped, wxList class
  15     2. Ensure compile-time type checking for the linked lists
  16
  17   The idea is to have one base class (wxListBase) working with "void *" data,
  18   but to hide these untyped functions - i.e. make them protected, so they
  19   can only be used from derived classes which have inline member functions
  20   working with right types. This achieves the 2nd goal. As for the first one,
  21   we provide a special derivation of wxListBase called wxList which looks just
  22   like the old class.
  23 */
  24
  25 #ifndef _WX_LISTH__
  26 #define _WX_LISTH__
  27
  28 #ifdef __GNUG__
  29 #pragma interface "list.h"
  30 #endif
  31
  32 // -----------------------------------------------------------------------------
  33 // headers
  34 // -----------------------------------------------------------------------------
  35
  36 #include "wx/defs.h"
  37 #include "wx/object.h"
  38 #include "wx/string.h"
  39
  40 // due to circular header dependencies this function has to be declared here
  41 // (normally it's found in utils.h which includes itself list.h...)
  42 extern WXDLLEXPORT wxChar* copystring(const wxChar *s);
  43
  44 class WXDLLEXPORT wxObjectListNode;
  45 typedef wxObjectListNode wxNode;
  46
  47 // undef it to get rid of old, deprecated functions
  48 #define wxLIST_COMPATIBILITY
  49
  50 // -----------------------------------------------------------------------------
  51 // constants
  52 // -----------------------------------------------------------------------------
  53 enum wxKeyType
  54 {
  55     wxKEY_NONE,
  56     wxKEY_INTEGER,
  57     wxKEY_STRING
  58 };
  59
  60 // -----------------------------------------------------------------------------
  61 // types
  62 // -----------------------------------------------------------------------------
  63
  64 // type of compare function for list sort operation (as in 'qsort'): it should
  65 // return a negative value, 0 or positive value if the first element is less
  66 // than, equal or greater than the second
  67 typedef int (* LINKAGEMODE wxSortCompareFunction)(const void *elem1, const void *elem2);
  68
  69 //
  70 typedef int (* LINKAGEMODE wxListIterateFunction)(void *current);
  71
  72 // -----------------------------------------------------------------------------
  73 // key stuff: a list may be optionally keyed on integer or string key
  74 // -----------------------------------------------------------------------------
  75
  76 union wxListKeyValue
  77 {
  78     long integer;
  79     wxChar *string;
  80 };
  81
  82 // a struct which may contain both types of keys
  83 //
  84 // implementation note: on one hand, this class allows to have only one function
  85 // for any keyed operation instead of 2 almost equivalent. OTOH, it's needed to
  86 // resolve ambiguity which we would otherwise have with wxStringList::Find() and
  87 // wxList::Find(const char *).
  88 class WXDLLEXPORT wxListKey
  89 {
  90 public:
  91     // implicit ctors
  92     wxListKey()
  93         { m_keyType = wxKEY_NONE; }
  94     wxListKey(long i)
  95         { m_keyType = wxKEY_INTEGER; m_key.integer = i; }
  96     wxListKey(const wxChar *s)
  97         { m_keyType = wxKEY_STRING; m_key.string = wxStrdup(s); }
  98     wxListKey(const wxString& s)
  99         { m_keyType = wxKEY_STRING; m_key.string = wxStrdup(s.c_str()); }
 100
 101     // accessors
 102     wxKeyType GetKeyType() const { return m_keyType; }
 103     const wxChar *GetString() const
 104         { wxASSERT( m_keyType == wxKEY_STRING ); return m_key.string; }
 105     long GetNumber() const
 106         { wxASSERT( m_keyType == wxKEY_INTEGER ); return m_key.integer; }
 107
 108     // comparison
 109     // Note: implementation moved to list.cpp to prevent BC++ inline
 110     // expansion warning.
 111     bool operator==(wxListKeyValue value) const ;
 112
 113     // dtor
 114     ~wxListKey()
 115     {
 116         if ( m_keyType == wxKEY_STRING )
 117             free(m_key.string);
 118     }
 119
 120 private:
 121     wxKeyType m_keyType;
 122     wxListKeyValue m_key;
 123 };
 124
 125 // -----------------------------------------------------------------------------
 126 // wxNodeBase class is a (base for) node in a double linked list
 127 // -----------------------------------------------------------------------------
 128
 129 WXDLLEXPORT_DATA(extern wxListKey) wxDefaultListKey;
 130
 131 class WXDLLEXPORT wxNodeBase
 132 {
 133 friend class wxListBase;
 134 public:
 135     // ctor
 136     wxNodeBase(wxListBase *list = (wxListBase *)NULL,
 137                wxNodeBase *previous = (wxNodeBase *)NULL,
 138                wxNodeBase *next = (wxNodeBase *)NULL,
 139                void *data = NULL,
 140                const wxListKey& key = wxDefaultListKey);
 141
 142     virtual ~wxNodeBase();
 143
 144     // FIXME no check is done that the list is really keyed on strings
 145     const wxChar *GetKeyString() const { return m_key.string; }
 146     long GetKeyInteger() const { return m_key.integer; }
 147
 148     // Necessary for some existing code
 149     void SetKeyString(wxChar* s) { m_key.string = s; }
 150     void SetKeyInteger(long i) { m_key.integer = i; }
 151
 152 #ifdef wxLIST_COMPATIBILITY
 153     // compatibility methods
 154     wxNode *Next() const { return (wxNode *)GetNext(); }
 155     wxNode *Previous() const { return (wxNode *)GetPrevious(); }
 156     wxObject *Data() const { return (wxObject *)GetData(); }
 157 #endif // wxLIST_COMPATIBILITY
 158
 159 protected:
 160     // all these are going to be "overloaded" in the derived classes
 161     wxNodeBase *GetNext() const { return m_next; }
 162     wxNodeBase *GetPrevious() const { return m_previous; }
 163
 164     void *GetData() const { return m_data; }
 165     void SetData(void *data) { m_data = data; }
 166
 167     // get 0-based index of this node within the list or wxNOT_FOUND
 168     int IndexOf() const;
 169
 170     virtual void DeleteData() { }
 171
 172 private:
 173     // optional key stuff
 174     wxListKeyValue m_key;
 175
 176     void        *m_data;        // user data
 177     wxNodeBase  *m_next,        // next and previous nodes in the list
 178                 *m_previous;
 179
 180     wxListBase  *m_list;        // list we belong to
 181 };
 182
 183 // -----------------------------------------------------------------------------
 184 // a double-linked list class
 185 // -----------------------------------------------------------------------------
 186 class WXDLLEXPORT wxListBase : public wxObject
 187 {
 188 friend class wxNodeBase;        // should be able to call DetachNode()
 189 friend class wxHashTableBase;   // should be able to call untyped Find()
 190 public:
 191     // default ctor & dtor
 192     wxListBase(wxKeyType keyType = wxKEY_NONE) { Init(keyType); }
 193     virtual ~wxListBase();
 194
 195     // accessors
 196         // count of items in the list
 197     size_t GetCount() const { return m_count; }
 198
 199     // operations
 200
 201         // delete all nodes
 202     void Clear();
 203
 204         // instruct it to destroy user data when deleting nodes
 205     void DeleteContents(bool destroy) { m_destroy = destroy; }
 206
 207        // query if to delete
 208     bool GetDeleteContents() const
 209         { return m_destroy; }
 210
 211       // get the keytype
 212     wxKeyType GetKeyType() const
 213         { return m_keyType; }
 214
 215       // set the keytype (required by the serial code)
 216     void SetKeyType(wxKeyType keyType)
 217         { wxASSERT( m_count==0 ); m_keyType = keyType; }
 218
 219 #ifdef wxLIST_COMPATIBILITY
 220     int Number() const { return GetCount(); }
 221     wxNode *First() const { return (wxNode *)GetFirst(); }
 222     wxNode *Last() const { return (wxNode *)GetLast(); }
 223     wxNode *Nth(size_t index) const { return (wxNode *)Item(index); }
 224 #endif // wxLIST_COMPATIBILITY
 225
 226 protected:
 227
 228     // all methods here are "overloaded" in derived classes to provide compile
 229     // time type checking
 230
 231     // create a node for the list of this type
 232     virtual wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next,
 233                                    void *data,
 234                                    const wxListKey& key = wxDefaultListKey) = 0;
 235
 236 // Can't access these from derived classes otherwise (bug in Salford C++?)
 237 #ifdef __SALFORDC__
 238 public:
 239 #endif
 240
 241     // ctors
 242         // from an array
 243     wxListBase(size_t count, void *elements[]);
 244         // from a sequence of objects
 245     wxListBase(void *object, ... /* terminate with NULL */);
 246
 247 protected:
 248         // copy ctor and assignment operator
 249     wxListBase(const wxListBase& list)
 250         { DoCopy(list); }
 251     wxListBase& operator=(const wxListBase& list)
 252         { Clear(); DoCopy(list); return *this; }
 253
 254         // get list head/tail
 255     wxNodeBase *GetFirst() const { return m_nodeFirst; }
 256     wxNodeBase *GetLast() const { return m_nodeLast; }
 257
 258         // by (0-based) index
 259     wxNodeBase *Item(size_t index) const;
 260
 261         // get the list item's data
 262     void *operator[](size_t index) const
 263         { wxNodeBase *node = Item(index); return node ? node->GetData() : (wxNodeBase*)NULL; }
 264
 265     // operations
 266         // append to end of list
 267     wxNodeBase *Append(void *object);
 268         // insert a new item at the beginning of the list
 269     wxNodeBase *Insert(void *object) { return Insert( (wxNodeBase*)NULL, object); }
 270         // insert a new item at the given position
 271     wxNodeBase *Insert(size_t pos, void *object)
 272         { return pos == GetCount() ? Append(object)
 273                                    : Insert(Item(pos), object); }
 274         // insert before given node or at front of list if prev == NULL
 275     wxNodeBase *Insert(wxNodeBase *prev, void *object);
 276
 277         // keyed append
 278     wxNodeBase *Append(long key, void *object);
 279     wxNodeBase *Append(const wxChar *key, void *object);
 280
 281         // removes node from the list but doesn't delete it (returns pointer
 282         // to the node or NULL if it wasn't found in the list)
 283     wxNodeBase *DetachNode(wxNodeBase *node);
 284         // delete element from list, returns FALSE if node not found
 285     bool DeleteNode(wxNodeBase *node);
 286         // finds object pointer and deletes node (and object if DeleteContents
 287         // is on), returns FALSE if object not found
 288     bool DeleteObject(void *object);
 289
 290     // search (all return NULL if item not found)
 291         // by data
 292     wxNodeBase *Find(void *object) const;
 293
 294         // by key
 295     wxNodeBase *Find(const wxListKey& key) const;
 296
 297     // get 0-based index of object or wxNOT_FOUND
 298     int IndexOf( void *object ) const;
 299
 300     // this function allows the sorting of arbitrary lists by giving
 301     // a function to compare two list elements. The list is sorted in place.
 302     void Sort(const wxSortCompareFunction compfunc);
 303
 304     // functions for iterating over the list
 305     void *FirstThat(wxListIterateFunction func);
 306     void ForEach(wxListIterateFunction func);
 307     void *LastThat(wxListIterateFunction func);
 308
 309 private:
 310     // helpers
 311         // common part of all ctors
 312     void Init(wxKeyType keyType = wxKEY_NONE);
 313         // common part of copy ctor and assignment operator
 314     void DoCopy(const wxListBase& list);
 315         // common part of all Append()s
 316     wxNodeBase *AppendCommon(wxNodeBase *node);
 317         // free node's data and node itself
 318     void DoDeleteNode(wxNodeBase *node);
 319
 320     size_t m_count;             // number of elements in the list
 321     bool m_destroy;             // destroy user data when deleting list items?
 322     wxNodeBase *m_nodeFirst,    // pointers to the head and tail of the list
 323                *m_nodeLast;
 324
 325     wxKeyType m_keyType;        // type of our keys (may be wxKEY_NONE)
 326 };
 327
 328 // -----------------------------------------------------------------------------
 329 // macros for definition of "template" list type
 330 // -----------------------------------------------------------------------------
 331
 332 // and now some heavy magic...
 333
 334 // declare a list type named 'name' and containing elements of type 'T *'
 335 // (as a by product of macro expansion you also get wx##name##Node
 336 // wxNode-derived type)
 337 //
 338 // implementation details:
 339 //  1. We define _WX_LIST_ITEM_TYPE_##name typedef to save in it the item type
 340 //     for the list of given type - this allows us to pass only the list name
 341 //     to WX_DEFINE_LIST() even if it needs both the name and the type
 342 //
 343 //  2. We redefine all non-type-safe wxList functions with type-safe versions
 344 //     which don't take any space (everything is inline), but bring compile
 345 //     time error checking.
 346 //
 347 //  3. The macro which is usually used (WX_DECLARE_LIST) is defined in terms of
 348 //     a more generic WX_DECLARE_LIST_2 macro which, in turn, uses the most
 349 //     generic WX_DECLARE_LIST_3 one. The last macro adds a sometimes
 350 //     interesting capability to store polymorphic objects in the list and is
 351 //     particularly useful with, for example, "wxWindow *" list where the
 352 //     wxWindowBase pointers are put into the list, but wxWindow pointers are
 353 //     retrieved from it.
 354
 355 #define WX_DECLARE_LIST_3(T, Tbase, name, nodetype, classexp)               \
 356     typedef int (*wxSortFuncFor_##name)(const T **, const T **);            \
 357                                                                             \
 358     classexp nodetype : public wxNodeBase                                   \
 359     {                                                                       \
 360     public:                                                                 \
 361         nodetype(wxListBase *list = (wxListBase *)NULL,                     \
 362                  nodetype *previous = (nodetype *)NULL,                     \
 363                  nodetype *next = (nodetype *)NULL,                         \
 364                  T *data = (T *)NULL,                                       \
 365                  const wxListKey& key = wxDefaultListKey)                   \
 366             : wxNodeBase(list, previous, next, data, key) { }               \
 367                                                                             \
 368         nodetype *GetNext() const                                           \
 369             { return (nodetype *)wxNodeBase::GetNext(); }                   \
 370         nodetype *GetPrevious() const                                       \
 371             { return (nodetype *)wxNodeBase::GetPrevious(); }               \
 372                                                                             \
 373         T *GetData() const                                                  \
 374             { return (T *)wxNodeBase::GetData(); }                          \
 375         void SetData(T *data)                                               \
 376             { wxNodeBase::SetData(data); }                                  \
 377                                                                             \
 378         virtual void DeleteData();                                          \
 379     };                                                                      \
 380                                                                             \
 381     classexp name : public wxListBase                                       \
 382     {                                                                       \
 383     public:                                                                 \
 384         typedef nodetype Node;                                              \
 385                                                                             \
 386         name(wxKeyType keyType = wxKEY_NONE) : wxListBase(keyType)          \
 387             { }                                                             \
 388         name(size_t count, T *elements[])                                   \
 389             : wxListBase(count, (void **)elements) { }                      \
 390                                                                             \
 391         name& operator=(const name& list)                                   \
 392             { return (name&)wxListBase::operator=(list); }                  \
 393                                                                             \
 394         nodetype *GetFirst() const                                          \
 395             { return (nodetype *)wxListBase::GetFirst(); }                  \
 396         nodetype *GetLast() const                                           \
 397             { return (nodetype *)wxListBase::GetLast(); }                   \
 398                                                                             \
 399         nodetype *Item(size_t index) const                                  \
 400             { return (nodetype *)wxListBase::Item(index); }                 \
 401                                                                             \
 402         T *operator[](size_t index) const                                   \
 403         {                                                                   \
 404             nodetype *node = Item(index);                                   \
 405             return node ? (T*)(node->GetData()) : (T*)NULL;                 \
 406         }                                                                   \
 407                                                                             \
 408         nodetype *Append(Tbase *object)                                     \
 409             { return (nodetype *)wxListBase::Append(object); }              \
 410         nodetype *Insert(Tbase *object)                                     \
 411             { return (nodetype *)Insert((nodetype*)NULL, object); }         \
 412         nodetype *Insert(size_t pos, Tbase *object)                         \
 413             { return (nodetype *)wxListBase::Insert(pos, object); }         \
 414         nodetype *Insert(nodetype *prev, Tbase *object)                     \
 415             { return (nodetype *)wxListBase::Insert(prev, object); }        \
 416                                                                             \
 417         nodetype *Append(long key, void *object)                            \
 418             { return (nodetype *)wxListBase::Append(key, object); }         \
 419         nodetype *Append(const wxChar *key, void *object)                   \
 420             { return (nodetype *)wxListBase::Append(key, object); }         \
 421                                                                             \
 422         nodetype *DetachNode(nodetype *node)                                \
 423             { return (nodetype *)wxListBase::DetachNode(node); }            \
 424         bool DeleteNode(nodetype *node)                                     \
 425             { return wxListBase::DeleteNode(node); }                        \
 426         bool DeleteObject(Tbase *object)                                    \
 427             { return wxListBase::DeleteObject(object); }                    \
 428                                                                             \
 429         nodetype *Find(Tbase *object) const                                 \
 430             { return (nodetype *)wxListBase::Find(object); }                \
 431                                                                             \
 432         virtual nodetype *Find(const wxListKey& key) const                  \
 433             { return (nodetype *)wxListBase::Find(key); }                   \
 434                                                                             \
 435         int IndexOf(Tbase *object) const                                    \
 436             { return wxListBase::IndexOf(object); }                         \
 437                                                                             \
 438         void Sort(wxSortFuncFor_##name func)                                \
 439             { wxListBase::Sort((wxSortCompareFunction)func); }              \
 440                                                                             \
 441     protected:                                                              \
 442         wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next,          \
 443                                void *data,                                  \
 444                                const wxListKey& key = wxDefaultListKey)     \
 445             {                                                               \
 446                 return new nodetype(this,                                   \
 447                                     (nodetype *)prev, (nodetype *)next,     \
 448                                     (T *)data, key);                        \
 449             }                                                               \
 450     }
 451
 452 #define WX_DECLARE_LIST_2(elementtype, listname, nodename, classexp)        \
 453     WX_DECLARE_LIST_3(elementtype, elementtype, listname, nodename, classexp)
 454
 455 #define WX_DECLARE_LIST(elementtype, listname)                              \
 456     typedef elementtype _WX_LIST_ITEM_TYPE_##listname;                      \
 457     WX_DECLARE_LIST_2(elementtype, listname, wx##listname##Node, class)
 458
 459 #define WX_DECLARE_EXPORTED_LIST(elementtype, listname)                     \
 460     typedef elementtype _WX_LIST_ITEM_TYPE_##listname;                      \
 461     WX_DECLARE_LIST_2(elementtype, listname, wx##listname##Node, class WXDLLEXPORT)
 462
 463 // this macro must be inserted in your program after
 464 //      #include <wx/listimpl.cpp>
 465 #define WX_DEFINE_LIST(name)    "don't forget to include listimpl.cpp!"
 466
 467 // =============================================================================
 468 // now we can define classes 100% compatible with the old ones
 469 // =============================================================================
 470
 471 // ----------------------------------------------------------------------------
 472 // commonly used list classes
 473 // ----------------------------------------------------------------------------
 474
 475 #ifdef wxLIST_COMPATIBILITY
 476
 477 // -----------------------------------------------------------------------------
 478 // wxList compatibility class: in fact, it's a list of wxObjects
 479 // -----------------------------------------------------------------------------
 480
 481 WX_DECLARE_LIST_2(wxObject, wxObjectList, wxObjectListNode, class WXDLLEXPORT);
 482
 483 class WXDLLEXPORT wxList : public wxObjectList
 484 {
 485 public:
 486     wxList(int key_type = wxKEY_NONE) : wxObjectList((wxKeyType)key_type) { }
 487
 488     wxList& operator=(const wxList& list)
 489         { return (wxList&)wxListBase::operator=(list); }
 490
 491     // compatibility methods
 492     void Sort(wxSortCompareFunction compfunc) { wxListBase::Sort(compfunc); }
 493
 494     wxNode *Member(wxObject *object) const { return (wxNode *)Find(object); }
 495 };
 496
 497 // -----------------------------------------------------------------------------
 498 // wxStringList class for compatibility with the old code
 499 // -----------------------------------------------------------------------------
 500
 501 WX_DECLARE_LIST_2(wxChar, wxStringListBase, wxStringListNode, class WXDLLEXPORT);
 502
 503 class WXDLLEXPORT wxStringList : public wxStringListBase
 504 {
 505 public:
 506     // ctors and such
 507         // default
 508     wxStringList() { DeleteContents(TRUE); }
 509     wxStringList(const wxChar *first ...);
 510
 511         // copying the string list: the strings are copied, too (extremely
 512         // inefficient!)
 513     wxStringList(const wxStringList& other) { DeleteContents(TRUE); DoCopy(other); }
 514     wxStringList& operator=(const wxStringList& other)
 515         { Clear(); DoCopy(other); return *this; }
 516
 517     // operations
 518         // makes a copy of the string
 519     wxNode *Add(const wxChar *s)
 520         { return (wxNode *)wxStringListBase::Append(copystring(s)); }
 521
 522     bool Delete(const wxChar *s);
 523
 524     wxChar **ListToArray(bool new_copies = FALSE) const;
 525     bool Member(const wxChar *s) const;
 526
 527     // alphabetic sort
 528     void Sort();
 529
 530 private:
 531     void DoCopy(const wxStringList&); // common part of copy ctor and operator=
 532 };
 533
 534 #endif // wxLIST_COMPATIBILITY
 535
 536 #endif
 537     // _WX_LISTH__