X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d54cf7ff131b62cc83116d5bfb8d2b5c49de9574..7df4c51f6021fbf1b204db918a1cc5c4ddff31cc:/docs/doxygen/overviews/container.h diff --git a/docs/doxygen/overviews/container.h b/docs/doxygen/overviews/container.h index 101147576e..55d5a68585 100644 --- a/docs/doxygen/overviews/container.h +++ b/docs/doxygen/overviews/container.h @@ -6,66 +6,69 @@ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -/*! +/** - @page overview_container Container classes overview +@page overview_container Container Classes - Classes: #wxListT, #wxArrayT, #wxVectorT +Classes: wxList, wxArray, wxVector - 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++. +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 - 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 - 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. +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 +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. - 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 - pointers depending on whether you called or not wxList::DeleteContents method. +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 or not you called 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 - the dynamic arrays. +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: WX_DECLARE_LIST() and WX_DEFINE_LIST() for the linked +lists and WX_DECLARE_ARRAY(), WX_DECLARE_OBJARRAY() and 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! +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 @e 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. +As array classes never delete the items they contain anyhow, there is 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 - classes are deprecated and should not be used in new programs. The following - 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. +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 +classes are deprecated and should not be used in new programs. The following +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. */ +