]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/container.h
More doxygen topic overview cleanup.
[wxWidgets.git] / docs / doxygen / overviews / container.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
d54cf7ff 2// Name: container.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/*!
36c9828f 10
d54cf7ff 11 @page overview_container Container classes overview
36c9828f 12
98ba1eee 13 Classes: wxList<T>, wxArray<T>, wxVector<T>
d54cf7ff 14
15b6757b
FM
15 wxWidgets uses itself several container classes including doubly-linked lists
16 and dynamic arrays (i.e. arrays which expand automatically when they become
d54cf7ff
FM
17 full). For both historical and portability reasons wxWidgets does not use STL
18 which provides the standard implementation of many container classes in C++.
19
20 First of all, wxWidgets has existed since well before STL was written, and
15b6757b 21 secondly we don't believe that today compilers can deal really well with all of
d54cf7ff 22 STL classes (this is especially true for some less common platforms). Of
15b6757b
FM
23 course, the compilers are evolving quite rapidly and hopefully their progress
24 will allow to base future versions of wxWidgets on STL - but this is not yet
25 the case.
d54cf7ff 26
15b6757b
FM
27 wxWidgets container classes don't pretend to be as powerful or full as STL
28 ones, but they are quite useful and may be compiled with absolutely any C++
29 compiler. They're used internally by wxWidgets, but may, of course, be used in
30 your programs as well if you wish.
d54cf7ff 31
15b6757b
FM
32 The list classes in wxWidgets are doubly-linked lists which may either own the
33 objects they contain (meaning that the list deletes the object when it is
34 removed from the list or the list itself is destroyed) or just store the
d54cf7ff
FM
35 pointers depending on whether you called or not wxList::DeleteContents method.
36
15b6757b
FM
37 Dynamic arrays resemble C arrays but with two important differences: they
38 provide run-time range checking in debug builds and they automatically expand
39 the allocated memory when there is no more space for new items. They come in
40 two sorts: the "plain" arrays which store either built-in types such as "char",
41 "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
42 own the object pointers to which they store.
d54cf7ff 43
15b6757b
FM
44 For the same portability reasons, the container classes implementation in wxWidgets
45 does not use templates, but is rather based on C preprocessor i.e. is done with
46 the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
47 lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
d54cf7ff
FM
48 the dynamic arrays.
49
50 The "DECLARE" macro declares a new container class containing the elements of
51 given type and is needed for all three types of container classes: lists,
52 arrays and objarrays. The "DEFINE" classes must be inserted in your program
53 in a place where the @b full declaration of container element class is in scope
54 (i.e. not just forward declaration), otherwise destructors of the container
55 elements will not be called!
56
57 As array classes never delete the items they contain anyhow, there is
15b6757b 58 no WX_DEFINE_ARRAY macro for them.
d54cf7ff 59
98ba1eee 60 Examples of usage of these macros may be found in wxList and wxArray documentation.
d54cf7ff 61
15b6757b
FM
62 Finally, wxWidgets predefines several commonly used container classes. wxList
63 is defined for compatibility with previous versions as a list containing
64 wxObjects and wxStringList as a list of C-style strings (char *), both of these
65 classes are deprecated and should not be used in new programs. The following
66 array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
67 wxArrayString. The first three store elements of corresponding types, but
68 wxArrayString is somewhat special: it is an optimized version of wxArray which
98ba1eee 69 uses its knowledge about wxString reference counting schema.
36c9828f 70
d54cf7ff 71*/