| 1 | \section{Container classes overview}\label{wxcontaineroverview} |
| 2 | |
| 3 | Classes: \helpref{wxList}{wxlist}, \helpref{wxArray}{wxarray} |
| 4 | |
| 5 | wxWidgets uses itself several container classes including doubly-linked lists |
| 6 | and dynamic arrays (i.e. arrays which expand automatically when they become |
| 7 | full). For both historical and portability reasons wxWidgets does not |
| 8 | use STL which provides the standard implementation of many container classes in |
| 9 | C++. First of all, wxWidgets has existed since 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 wxWidgets on STL - but this is not yet |
| 14 | the case. |
| 15 | |
| 16 | wxWidgets 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 wxWidgets, but may, of course, be used in |
| 19 | your programs as well if you wish. |
| 20 | |
| 21 | The list classes in wxWidgets are doubly-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 C arrays but with two important differences: they |
| 28 | provide run-time range checking in debug builds and they automatically expand |
| 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, the container classes implementation in wxWidgets |
| 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 WX\_DEFINE\_OBJARRAY} for |
| 38 | 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, wxWidgets 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 | |