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