]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/list.h
added stubs for wxTreeCtrl functions not yet implemented under MSW
[wxWidgets.git] / include / wx / list.h
... / ...
CommitLineData
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/debug.h"
38#include "wx/object.h"
39#include "wx/string.h"
40
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...)
43extern WXDLLEXPORT char* copystring(const char *s);
44
45class WXDLLEXPORT wxObjectListNode;
46typedef wxObjectListNode wxNode;
47
48// undef it to get rid of old, deprecated functions
49#define wxLIST_COMPATIBILITY
50
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
68typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
69
70//
71typedef int (*wxListIterateFunction)(void *current);
72
73// -----------------------------------------------------------------------------
74// key stuff: a list may be optionally keyed on integer or string key
75// -----------------------------------------------------------------------------
76
77union wxListKeyValue
78{
79 long integer;
80 char *string;
81};
82
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; }
97 wxListKey(const char *s)
98 { m_keyType = wxKEY_STRING; m_key.string = strdup(s); }
99 wxListKey(const wxString& s)
100 { m_keyType = wxKEY_STRING; m_key.string = strdup(s.c_str()); }
101
102 // accessors
103 wxKeyType GetKeyType() const { return m_keyType; }
104 const char *GetString() const
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
109 // comparison
110 // Note: implementation moved to list.cpp to prevent BC++ inline
111 // expansion warning.
112 bool operator==(wxListKeyValue value) const ;
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
130class WXDLLEXPORT wxNodeBase
131{
132friend class wxListBase;
133public:
134 // ctor
135 wxNodeBase(wxListBase *list = (wxListBase *)NULL,
136 wxNodeBase *previous = (wxNodeBase *)NULL,
137 wxNodeBase *next = (wxNodeBase *)NULL,
138 void *data = NULL,
139 const wxListKey& key = wxListKey());
140
141 virtual ~wxNodeBase();
142
143 // @@ no check is done that the list is really keyed on strings
144 const char *GetKeyString() const { return m_key.string; }
145 long GetKeyInteger() const { return m_key.integer; }
146
147 // Necessary for some existing code
148 void SetKeyString(char* s) { m_key.string = s; }
149 void SetKeyInteger(long i) { m_key.integer = i; }
150
151#ifdef wxLIST_COMPATIBILITY
152 // compatibility methods
153 wxNode *Next() const { return (wxNode *)GetNext(); }
154 wxNode *Previous() const { return (wxNode *)GetPrevious(); }
155 wxObject *Data() const { return (wxObject *)GetData(); }
156#endif // wxLIST_COMPATIBILITY
157
158protected:
159 // all these are going to be "overloaded" in the derived classes
160 wxNodeBase *GetNext() const { return m_next; }
161 wxNodeBase *GetPrevious() const { return m_previous; }
162
163 void *GetData() const { return m_data; }
164 void SetData(void *data) { m_data = data; }
165
166 // get 0-based index of this node within the list or NOT_FOUND
167 int IndexOf() const;
168
169 virtual void DeleteData() { }
170
171private:
172 // optional key stuff
173 wxListKeyValue m_key;
174
175 void *m_data; // user data
176 wxNodeBase *m_next, // next and previous nodes in the list
177 *m_previous;
178
179 wxListBase *m_list; // list we belong to
180};
181
182// -----------------------------------------------------------------------------
183// a double-linked list class
184// -----------------------------------------------------------------------------
185class WXDLLEXPORT wxListBase : public wxObject
186{
187friend class wxNodeBase; // should be able to call DetachNode()
188public:
189 // default ctor & dtor
190 wxListBase(wxKeyType keyType = wxKEY_NONE) { Init(keyType); }
191 virtual ~wxListBase();
192
193 // accessors
194 // count of items in the list
195 size_t GetCount() const { return m_count; }
196
197 // operations
198
199 // delete all nodes
200 void Clear();
201
202 // instruct it to destroy user data when deleting nodes
203 void DeleteContents(bool destroy) { m_destroy = destroy; }
204
205 // query if to delete
206 bool GetDeleteContents() const
207 { return m_destroy; }
208
209 // get the keytype
210 wxKeyType GetKeyType() const
211 { return m_keyType; }
212
213 // set the keytype (required by the serial code)
214 void SetKeyType(wxKeyType keyType)
215 { wxASSERT( m_count==0 ); m_keyType = keyType; }
216
217protected:
218 // all methods here are "overloaded" in derived classes to provide compile
219 // time type checking
220
221 // create a node for the list of this type
222 virtual wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next,
223 void *data,
224 const wxListKey& key = wxListKey()) = 0;
225
226 // ctors
227 // from an array
228 wxListBase(size_t count, void *elements[]);
229 // from a sequence of objects
230 wxListBase(void *object, ... /* terminate with NULL */);
231
232 // copy ctor and assignment operator
233 wxListBase(const wxListBase& list)
234 { DoCopy(list); }
235 wxListBase& operator=(const wxListBase& list)
236 { Clear(); DoCopy(list); return *this; }
237
238 // get list head/tail
239 wxNodeBase *GetFirst() const { return m_nodeFirst; }
240 wxNodeBase *GetLast() const { return m_nodeLast; }
241
242 // by (0-based) index
243 wxNodeBase *Item(size_t index) const;
244
245 // get the list item's data
246 void *operator[](size_t index) const
247 { wxNodeBase *node = Item(index); return node ? node->GetData() : (wxNodeBase*)NULL; }
248
249 // operations
250 // append to end of list
251 wxNodeBase *Append(void *object);
252 // insert a new item at the beginning of the list
253 wxNodeBase *Insert(void *object) { return Insert( (wxNodeBase*)NULL, object); }
254 // insert before given node or at front of list if prev == NULL
255 wxNodeBase *Insert(wxNodeBase *prev, void *object);
256
257 // keyed append
258 wxNodeBase *Append(long key, void *object);
259 wxNodeBase *Append(const char *key, void *object);
260
261 // removes node from the list but doesn't delete it (returns pointer
262 // to the node or NULL if it wasn't found in the list)
263 wxNodeBase *DetachNode(wxNodeBase *node);
264 // delete element from list, returns FALSE if node not found
265 bool DeleteNode(wxNodeBase *node);
266 // finds object pointer and deletes node (and object if DeleteContents
267 // is on), returns FALSE if object not found
268 bool DeleteObject(void *object);
269
270 // search (all return NULL if item not found)
271 // by data
272 wxNodeBase *Find(void *object) const;
273
274 // by key
275 wxNodeBase *Find(const wxListKey& key) const;
276
277 // get 0-based index of object or NOT_FOUND
278 int IndexOf( void *object ) const;
279
280 // this function allows the sorting of arbitrary lists by giving
281 // a function to compare two list elements. The list is sorted in place.
282 void Sort(const wxSortCompareFunction compfunc);
283
284 // functions for iterating over the list
285 void *FirstThat(wxListIterateFunction func);
286 void ForEach(wxListIterateFunction func);
287 void *LastThat(wxListIterateFunction func);
288
289private:
290 // helpers
291 // common part of all ctors
292 void Init(wxKeyType keyType);
293 // common part of copy ctor and assignment operator
294 void DoCopy(const wxListBase& list);
295 // common part of all Append()s
296 wxNodeBase *AppendCommon(wxNodeBase *node);
297 // free node's data and node itself
298 void DoDeleteNode(wxNodeBase *node);
299
300 size_t m_count; // number of elements in the list
301 bool m_destroy; // destroy user data when deleting list items?
302 wxNodeBase *m_nodeFirst, // pointers to the head and tail of the list
303 *m_nodeLast;
304
305 wxKeyType m_keyType; // type of our keys (may be wxKEY_NONE)
306};
307
308// -----------------------------------------------------------------------------
309// macros for definition of "template" list type
310// -----------------------------------------------------------------------------
311
312// and now some heavy magic...
313
314// declare a list type named 'name' and containing elements of type 'T *'
315// (as a by product of macro expansion you also get wx##name##Node
316// wxNode-dervied type)
317//
318// implementation details:
319// 1. we define _WX_LIST_ITEM_TYPE_##name typedef to save in it the item type
320// for the list of given type - this allows us to pass only the list name
321// to WX_DEFINE_LIST() even if it needs both the name and the type
322//
323// 2. We redefine all not type-safe wxList functions withtype-safe versions
324// which don't take any place (everything is inline), but bring compile
325// time error checking.
326
327#define WX_DECLARE_LIST_2(T, name, nodetype) \
328 typedef int (*wxSortFuncFor_##name)(const T *, const T *); \
329 \
330 class WXDLLEXPORT nodetype : public wxNodeBase \
331 { \
332 public: \
333 nodetype(wxListBase *list = (wxListBase *)NULL, \
334 nodetype *previous = (nodetype *)NULL, \
335 nodetype *next = (nodetype *)NULL, \
336 T *data = (T *)NULL, \
337 const wxListKey& key = wxListKey()) \
338 : wxNodeBase(list, previous, next, data, key) { } \
339 \
340 nodetype *GetNext() const \
341 { return (nodetype *)wxNodeBase::GetNext(); } \
342 nodetype *GetPrevious() const \
343 { return (nodetype *)wxNodeBase::GetPrevious(); } \
344 \
345 T *GetData() const \
346 { return (T *)wxNodeBase::GetData(); } \
347 void SetData(T *data) \
348 { wxNodeBase::SetData(data); } \
349 \
350 virtual void DeleteData(); \
351 }; \
352 \
353 class WXDLLEXPORT name : public wxListBase \
354 { \
355 public: \
356 name(wxKeyType keyType = wxKEY_NONE) : wxListBase(keyType) \
357 { } \
358 name(size_t count, T *elements[]) \
359 : wxListBase(count, (void **)elements) { } \
360 \
361 nodetype *GetFirst() const \
362 { return (nodetype *)wxListBase::GetFirst(); } \
363 nodetype *GetLast() const \
364 { return (nodetype *)wxListBase::GetLast(); } \
365 \
366 nodetype *Item(size_t index) const \
367 { return (nodetype *)wxListBase::Item(index); } \
368 \
369 T *operator[](size_t index) const \
370 { \
371 nodetype *node = Item(index); \
372 return node ? (T*)(node->GetData()) : (T*)NULL; \
373 } \
374 \
375 nodetype *Append(T *object) \
376 { return (nodetype *)wxListBase::Append(object); } \
377 nodetype *Insert(T *object) \
378 { return (nodetype *)Insert((nodetype*)NULL, object); } \
379 nodetype *Insert(nodetype *prev, T *object) \
380 { return (nodetype *)wxListBase::Insert(prev, object); } \
381 \
382 nodetype *Append(long key, void *object) \
383 { return (nodetype *)wxListBase::Append(key, object); } \
384 nodetype *Append(const char *key, void *object) \
385 { return (nodetype *)wxListBase::Append(key, object); } \
386 \
387 nodetype *DetachNode(nodetype *node) \
388 { return (nodetype *)wxListBase::DetachNode(node); } \
389 bool DeleteNode(nodetype *node) \
390 { return wxListBase::DeleteNode(node); } \
391 bool DeleteObject(T *object) \
392 { return wxListBase::DeleteObject(object); } \
393 \
394 nodetype *Find(T *object) const \
395 { return (nodetype *)wxListBase::Find(object); } \
396 \
397 virtual nodetype *Find(const wxListKey& key) const \
398 { return (nodetype *)wxListBase::Find(key); } \
399 \
400 int IndexOf( T *object ) const \
401 { return wxListBase::IndexOf(object); } \
402 \
403 void Sort(wxSortFuncFor_##name func) \
404 { wxListBase::Sort((wxSortCompareFunction)func); } \
405 \
406 protected: \
407 wxNodeBase *CreateNode(wxNodeBase *prev, wxNodeBase *next, \
408 void *data, \
409 const wxListKey& key = wxListKey()) \
410 { \
411 return new nodetype(this, \
412 (nodetype *)prev, (nodetype *)next, \
413 (T *)data, key); \
414 } \
415 }
416
417#define WX_DECLARE_LIST(elementtype, listname) \
418 typedef elementtype _WX_LIST_ITEM_TYPE_##listname; \
419 WX_DECLARE_LIST_2(elementtype, listname, wx##listname##Node)
420
421// this macro must be inserted in your program after
422// #include <wx/listimpl.cpp>
423#define WX_DEFINE_LIST(name) "don't forget to include listimpl.cpp!"
424
425
426// =============================================================================
427// now we can define classes 100% compatible with the old ones
428// =============================================================================
429
430#ifdef wxLIST_COMPATIBILITY
431
432// -----------------------------------------------------------------------------
433// wxList compatibility class: in fact, it's a list of wxObjects
434// -----------------------------------------------------------------------------
435
436WX_DECLARE_LIST_2(wxObject, wxObjectList, wxObjectListNode);
437
438class WXDLLEXPORT wxList : public wxObjectList
439{
440public:
441 wxList(int key_type = wxKEY_NONE) : wxObjectList((wxKeyType)key_type) { }
442
443 // compatibility methods
444 void Sort(wxSortCompareFunction compfunc) { wxListBase::Sort(compfunc); }
445
446 int Number() const { return GetCount(); }
447 wxNode *First() const { return (wxNode *)GetFirst(); }
448 wxNode *Last() const { return (wxNode *)GetLast(); }
449 wxNode *Nth(size_t index) const { return (wxNode *)Item(index); }
450 wxNode *Member(wxObject *object) const { return (wxNode *)Find(object); }
451};
452
453// -----------------------------------------------------------------------------
454// wxStringList class for compatibility with the old code
455// -----------------------------------------------------------------------------
456
457WX_DECLARE_LIST_2(char, wxStringListBase, wxStringListNode);
458
459class WXDLLEXPORT wxStringList : public wxStringListBase
460{
461public:
462 // ctors and such
463 // default
464 wxStringList() { DeleteContents(TRUE); }
465 wxStringList(const char *first ...);
466
467 // copying the string list: the strings are copied, too (extremely
468 // inefficient!)
469 wxStringList(const wxStringList& other) { DoCopy(other); }
470 wxStringList& operator=(const wxStringList& other)
471 { Clear(); DoCopy(other); return *this; }
472
473 // operations
474 // makes a copy of the string
475 wxNode *Add(const char *s)
476 { return (wxNode *)wxStringListBase::Append(copystring(s)); }
477
478 bool Delete(const char *s);
479
480 char **ListToArray(bool new_copies = FALSE) const;
481 bool Member(const char *s) const;
482
483 // alphabetic sort
484 void Sort();
485
486 // compatibility methods
487 int Number() const { return GetCount(); }
488 wxNode *First() const { return (wxNode *)GetFirst(); }
489 wxNode *Last() const { return (wxNode *)GetLast(); }
490 wxNode *Nth(size_t index) const { return (wxNode *)Item(index); }
491
492private:
493 void DoCopy(const wxStringList&); // common part of copy ctor and operator=
494};
495
496#endif // wxLIST_COMPATIBILITY
497
498#endif
499 // _WX_LISTH__