added images for topic overviews

[wxWidgets.git] / docs / doxygen / overviews / container.h

diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h
index 796af3f3834525e21fc3c64b4678b677103dfe51..101147576e7ff4288af6b0d0c8bacfad18a799f9 100644 (file)
--- a/docs/doxygen/overviews/container.h
+++ b/docs/doxygen/overviews/container.h
@@ -1,5 +1,5 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        container
+// Name:        container.h

 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     topic overview
 // Author:      wxWidgets team
 // RCS-ID:      $Id$


@@ -8,48 +8,57 @@
 
 /*!
 
 
 /*!
 

- @page container_overview Container classes overview
+ @page overview_container Container classes overview

 
  Classes: #wxListT, #wxArrayT, #wxVectorT
 
  Classes: #wxListT, #wxArrayT, #wxVectorT

+

  wxWidgets uses itself several container classes including doubly-linked lists
  and dynamic arrays (i.e. arrays which expand automatically when they become
  wxWidgets uses itself several container classes including doubly-linked lists
  and dynamic arrays (i.e. arrays which expand automatically when they become

- full). For both historical and portability reasons wxWidgets does not
- use STL which provides the standard implementation of many container classes in
- C++. First of all, wxWidgets has existed since well before STL was written, and
+ full). For both historical and portability reasons wxWidgets does not use STL 
+ which provides the standard implementation of many container classes in C++.
+
+ First of all, wxWidgets has existed since well before STL was written, and

  secondly we don't believe that today compilers can deal really well with all of
  secondly we don't believe that today compilers can deal really well with all of

- STL classes (this is especially @true for some less common platforms). Of
+ STL classes (this is especially true for some less common platforms). Of

  course, the compilers are evolving quite rapidly and hopefully their progress
  will allow to base future versions of wxWidgets on STL - but this is not yet
  the case.
  course, the compilers are evolving quite rapidly and hopefully their progress
  will allow to base future versions of wxWidgets on STL - but this is not yet
  the case.

+

  wxWidgets container classes don't pretend to be as powerful or full as STL
  ones, but they are quite useful and may be compiled with absolutely any C++
  compiler. They're used internally by wxWidgets, but may, of course, be used in
  your programs as well if you wish.
  wxWidgets container classes don't pretend to be as powerful or full as STL
  ones, but they are quite useful and may be compiled with absolutely any C++
  compiler. They're used internally by wxWidgets, but may, of course, be used in
  your programs as well if you wish.

+

  The list classes in wxWidgets are doubly-linked lists which may either own the
  objects they contain (meaning that the list deletes the object when it is
  removed from the list or the list itself is destroyed) or just store the
  The list classes in wxWidgets are doubly-linked lists which may either own the
  objects they contain (meaning that the list deletes the object when it is
  removed from the list or the list itself is destroyed) or just store the

- pointers depending on whether you called or not
- wxList::DeleteContents method.
+ pointers depending on whether you called or not wxList::DeleteContents method.
+

  Dynamic arrays resemble C arrays but with two important differences: they
  provide run-time range checking in debug builds and they automatically expand
  the allocated memory when there is no more space for new items. They come in
  two sorts: the "plain" arrays which store either built-in types such as "char",
  "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
  own the object pointers to which they store.
  Dynamic arrays resemble C arrays but with two important differences: they
  provide run-time range checking in debug builds and they automatically expand
  the allocated memory when there is no more space for new items. They come in
  two sorts: the "plain" arrays which store either built-in types such as "char",
  "int" or "bool" or the pointers to arbitrary objects, or "object arrays" which
  own the object pointers to which they store.

+

  For the same portability reasons, the container classes implementation in wxWidgets
  does not use templates, but is rather based on C preprocessor i.e. is done with
  the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
  lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for
  For the same portability reasons, the container classes implementation in wxWidgets
  does not use templates, but is rather based on C preprocessor i.e. is done with
  the macros: @e WX_DECLARE_LIST and @e WX_DEFINE_LIST for the linked
  lists and @e WX_DECLARE_ARRAY, @e WX_DECLARE_OBJARRAY and @e WX_DEFINE_OBJARRAY for

- the dynamic arrays. The "DECLARE" macro declares a
- new container class containing the elements of given type and is needed for all
- three types of container classes: lists, arrays and objarrays. The "DEFINE"
- classes must be inserted in your program in a place where the @b full
- declaration of container element class is in scope (i.e. not just forward
- declaration), otherwise destructors of the container elements will not be
- called! As array classes never delete the items they contain anyhow, there is
+ the dynamic arrays. 
+
+ The "DECLARE" macro declares a new container class containing the elements of 
+ given type and is needed for all three types of container classes: lists, 
+ arrays and objarrays. The "DEFINE" classes must be inserted in your program 
+ in a place where the @b full declaration of container element class is in scope 
+ (i.e. not just forward declaration), otherwise destructors of the container 
+ elements will not be called! 
+
+ As array classes never delete the items they contain anyhow, there is

  no WX_DEFINE_ARRAY macro for them.
  no WX_DEFINE_ARRAY macro for them.

- Examples of usage of these macros may be found in #wxList and
- #wxArray documentation.
+
+ Examples of usage of these macros may be found in #wxList and #wxArray documentation.
+

  Finally, wxWidgets predefines several commonly used container classes. wxList
  is defined for compatibility with previous versions as a list containing
  wxObjects and wxStringList as a list of C-style strings (char *), both of these
  Finally, wxWidgets predefines several commonly used container classes. wxList
  is defined for compatibility with previous versions as a list containing
  wxObjects and wxStringList as a list of C-style strings (char *), both of these


@@ -57,9 +66,6 @@
  array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
  wxArrayString. The first three store elements of corresponding types, but
  wxArrayString is somewhat special: it is an optimized version of wxArray which
  array classes are defined: wxArrayInt, wxArrayLong, wxArrayPtrVoid and
  wxArrayString. The first three store elements of corresponding types, but
  wxArrayString is somewhat special: it is an optimized version of wxArray which

- uses its knowledge about #wxString reference counting
- schema.
-
- */
-
+ uses its knowledge about #wxString reference counting schema.

 
 

+*/