]> git.saurik.com Git - wxWidgets.git/blame - docs/latex/wx/tcontain.tex
patch 1306473
[wxWidgets.git] / docs / latex / wx / tcontain.tex
CommitLineData
6e6110ee
VZ
1\section{Container classes overview}\label{wxcontaineroverview}
2
3Classes: \helpref{wxList}{wxlist}, \helpref{wxArray}{wxarray}
4
fc2171bd 5wxWidgets uses itself several container classes including doubly-linked lists
6e6110ee 6and dynamic arrays (i.e. arrays which expand automatically when they become
fc2171bd 7full). For both historical and portability reasons wxWidgets does not
6e6110ee 8use STL which provides the standard implementation of many container classes in
fc2171bd 9C++. First of all, wxWidgets has existed since well before STL was written, and
6e6110ee
VZ
10secondly we don't believe that today compilers can deal really well with all of
11STL classes (this is especially true for some less common platforms). Of
12course, the compilers are evolving quite rapidly and hopefully their progress
fc2171bd 13will allow to base future versions of wxWidgets on STL - but this is not yet
6e6110ee
VZ
14the case.
15
fc2171bd 16wxWidgets container classes don't pretend to be as powerful or full as STL
6e6110ee 17ones, but they are quite useful and may be compiled with absolutely any C++
fc2171bd 18compiler. They're used internally by wxWidgets, but may, of course, be used in
6e6110ee
VZ
19your programs as well if you wish.
20
fc2171bd 21The list classes in wxWidgets are doubly-linked lists which may either own the
6e6110ee
VZ
22objects they contain (meaning that the list deletes the object when it is
23removed from the list or the list itself is destroyed) or just store the
247aba10 24pointers depending on whether you called or not
6e6110ee
VZ
25\helpref{wxList::DeleteContents}{wxlistdeletecontents} method.
26
06ad8636 27Dynamic arrays resemble C arrays but with two important differences: they
f70c0443 28provide run-time range checking in debug builds and they automatically expand
6e6110ee
VZ
29the allocated memory when there is no more space for new items. They come in
30two sorts: the "plain" arrays which store either built-in types such as "char",
31"int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
32own the object pointers to which they store.
33
fc2171bd 34For the same portability reasons, the container classes implementation in wxWidgets
6e6110ee
VZ
35does not use templates, but is rather based on C preprocessor i.e. is done with
36the macros: {\it WX\_DECLARE\_LIST} and {\it WX\_DEFINE\_LIST} for the linked
6be663cf
JS
37lists and {\it WX\_DECLARE\_ARRAY}, {\it WX\_DECLARE\_OBJARRAY} and {\it WX\_DEFINE\_OBJARRAY} for
38the dynamic arrays. The "DECLARE" macro declares a
6e6110ee
VZ
39new container class containing the elements of given type and is needed for all
40three types of container classes: lists, arrays and objarrays. The "DEFINE"
41classes must be inserted in your program in a place where the {\bf full
42declaration of container element class is in scope} (i.e. not just forward
43declaration), otherwise destructors of the container elements will not be
44called! As array classes never delete the items they contain anyhow, there is
45no WX\_DEFINE\_ARRAY macro for them.
46
06ad8636 47Examples of usage of these macros may be found in \helpref{wxList}{wxlist} and
6e6110ee
VZ
48\helpref{wxArray}{wxarray} documentation.
49
fc2171bd 50Finally, wxWidgets predefines several commonly used container classes. wxList
6e6110ee
VZ
51is defined for compatibility with previous versions as a list containing
52wxObjects and wxStringList as a list of C-style strings (char *), both of these
53classes are deprecated and should not be used in new programs. The following
54array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
55wxArrayString. The first three store elements of corresponding types, but
56wxArrayString is somewhat special: it is an optimized version of wxArray which
57uses its knowledge about \helpref{wxString}{wxstring} reference counting
58schema.
59