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>, wxStack<T>, wxHashMap, wxHashSet
  14
  15 @section overview_container_intro Overview
  16
  17 For historical reasons, wxWidgets uses custom container classes internally.
  18 This was unfortunately unavoidable during a long time when the standard library
  19 wasn't widely available and can't be easily changed even now that it is for
  20 compatibility reasons. If you are building your own version of the library and
  21 don't care about compatibility nor slight (less than 5%) size penalty imposed
  22 by the use of STL classes, you may choose to use the "STL" build of wxWidgets
  23 in which these custom classes are replaced with their standard counterparts and
  24 only read the section @ref overview_container_std explaining how to do it.
  25
  26 Otherwise you will need to know about the custom wxWidgets container classes
  27 such as wxList<T> and wxArray<T> if only to use wxWidgets functions that work
  28 with them, e.g. wxWindow::GetChildren(), and you should find the information
  29 about using these classes below useful.
  30
  31 Notice that we recommend that you use standard classes directly in your own
  32 code instead of the container classes provided by wxWidgets in any case as the
  33 standard classes are easier to use and may also be safer because of extra
  34 run-time checks they may perform as well as more efficient.
  35
  36 Finally notice that recent versions of wxWidgets also provide standard-like
  37 classes such as wxVector<T>, wxStack<T> or wxDList which can be used exactly
  38 like the std::vector<T>, std::stack<T> and std::list<T*>, respectively, and
  39 actually are just typedefs for the corresponding types if wxWidgets is compiled
  40 in STL mode. These classes could be useful if you wish to avoid the use of the
  41 standard library in your code for some reason.
  42
  43 To summarize, you should use the standard container classes such as
  44 std::vector<T> and std::list<T> if possible and wxVector<T> or wxDList<T> if
  45 it isn't and only use legacy wxWidgets containers such as wxArray<T> and
  46 wxList<T> when you must, i.e. when you use a wxWidgets function taking or
  47 returning a container of such type.
  48
  49
  50 @section overview_container_legacy Legacy Classes
  51
  52 The list classes in wxWidgets are doubly-linked lists which may either own the
  53 objects they contain (meaning that the list deletes the object when it is
  54 removed from the list or the list itself is destroyed) or just store the
  55 pointers depending on whether or not you called wxList<T>::DeleteContents()
  56 method.
  57
  58 Dynamic arrays resemble C arrays but with two important differences: they
  59 provide run-time range checking in debug builds and they automatically expand
  60 the allocated memory when there is no more space for new items. They come in
  61 two sorts: the "plain" arrays which store either built-in types such as "char",
  62 "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
  63 own the object pointers to which they store.
  64
  65 For the same portability reasons, the container classes implementation in
  66 wxWidgets don't use templates, but are rather based on C preprocessor i.e. are
  67 implemented using the macros: WX_DECLARE_LIST() and WX_DEFINE_LIST() for the
  68 linked lists and WX_DECLARE_ARRAY(), WX_DECLARE_OBJARRAY() and
  69 WX_DEFINE_OBJARRAY() for the dynamic arrays.
  70
  71 The "DECLARE" macro declares a new container class containing the elements of
  72 given type and is needed for all three types of container classes: lists,
  73 arrays and objarrays. The "DEFINE" classes must be inserted in your program in
  74 a place where the @e full declaration of container element class is in scope
  75 (i.e. not just forward declaration), otherwise destructors of the container
  76 elements will not be called!
  77
  78 As array classes never delete the items they contain anyhow, there is no
  79 WX_DEFINE_ARRAY() macro for them.
  80
  81 Examples of usage of these macros may be found in wxList<T> and wxArray<T>
  82 documentation.
  83
  84 Finally, wxWidgets predefines several commonly used container classes. wxList
  85 is defined for compatibility with previous versions as a list containing
  86 wxObjects and wxStringList as a list of C-style strings (char *), both of these
  87 classes are deprecated and should not be used in new programs. The following
  88 array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
  89 wxArrayString. The first three store elements of corresponding types, but
  90 wxArrayString is somewhat special: it is an optimized version of wxArray which
  91 uses its knowledge about wxString reference counting schema.
  92
  93
  94 @section overview_container_std STL Build
  95
  96 To build wxWidgets with the standard containers you need to set
  97 wxUSE_STD_CONTAINERS option to 1 in @c wx/msw/setup.h for wxMSW builds or
  98 specify @c --enable-std_containers option to configure (which is also
  99 implicitly enabled by @c --enable-stl option) in Unix builds.
 100
 101 The standard container build is mostly, but not quite, compatible with the
 102 default one. Here are the most important differences:
 103  - wxList::compatibility_iterator must be used instead of wxList::Node* when
 104    iterating over the list contents. The compatibility_iterator class has the
 105    same semantics as a Node pointer but it is an object and not a pointer, so
 106    you need to write
 107         @code
 108         for ( wxWindowList::compatibility_iterator it = list.GetFirst();
 109               it;
 110               it = it->GetNext() )
 111             ...
 112         @endcode
 113    instead of the old
 114         @code
 115         for ( wxWindowList::Node *n = list.GetFirst(); n; n = n->GetNext() )
 116             ...
 117         @endcode
 118  - wxSortedArrayString and wxArrayString are separate classes now and the
 119    former doesn't derive from the latter. If you need to convert a sorted array
 120    to a normal one, you must copy all the elements. Alternatively, you may
 121    avoid the use of wxSortedArrayString by using a normal array and calling its
 122    Sort() method when needed.
 123  - WX_DEFINE_ARRAY_INT(bool) cannot be used because of the differences in
 124    std::vector<bool> specialization compared with the generic std::vector<>
 125    class. Please either use std::vector<bool> directly or use an integer array
 126    instead.
 127
 128
 129 */
 130