docs/doxygen/overviews/container.h

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