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