X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/682f6de66411d0571042eddec9dec6803045a38c..6bd1764f2716e8d0814edd6374b20960bba23579:/interface/wx/list.h diff --git a/interface/wx/list.h b/interface/wx/list.h index 38ba08708e..cb925cde87 100644 --- a/interface/wx/list.h +++ b/interface/wx/list.h @@ -7,29 +7,30 @@ ///////////////////////////////////////////////////////////////////////////// /** + The wxList class provides linked list functionality. - The wxList class provides linked list functionality. It has been rewritten - to be type safe and to provide the full API of the STL std::list container and - should be used like it. The exception is that wxList actually stores - pointers and therefore its iterators return pointers and not references - to the actual objets in the list (see example below) and @e value_type - is defined as @e T*. wxList destroys an object after removing it only - if wxList::DeleteContents has been called. + This class has been rewritten to be type safe and to provide the full API of + the STL std::list container and should be used like it. + The exception is that wxList actually stores pointers and therefore its + iterators return pointers and not references to the actual objets in the list + (see example below) and @e value_type is defined as @e T*. + wxList destroys an object after removing it only if wxList::DeleteContents + has been called. wxList is not a real template and it requires that you declare and define - each wxListT class in your program. This is done with @e WX_DECLARE_LIST - and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able - to provide a proper template class providing both the STL std::list - and the old wxList API in the future. - - Please refer to the STL std::list documentation for further - information on how to use the class. Below we documented both - the supported STL and the legacy API that originated from the - old wxList class and which can still be used alternatively for - the the same class. - - Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1) - then wxList will actually derive from std::list and just add a legacy + each wxList class in your program. This is done with @e WX_DECLARE_LIST + and @e WX_DEFINE_LIST macros (see example). We hope that we'll be able to + provide a proper template class providing both the STL @c std::list and the old + wxList API in the future. + + Please refer to the STL @c std::list documentation (see http://www.cppreference.com/wiki/stl/list/start) + for further information on how to use the class. + Below we documented both the supported STL and the legacy API + that originated from the old wxList class and which can still be used alternatively + for the the same class. + + Note that if you compile wxWidgets in STL mode (@c wxUSE_STL defined as 1) + then wxList will actually derive from @c std::list and just add a legacy compatibility layer for the old wxList class. @code @@ -73,17 +74,26 @@ MyListElement *current = node->GetData(); ...process the current element... - + node = node->GetNext(); } @endcode + For compatibility with previous versions wxList and wxStringList classes are + still defined, but their usage is deprecated and they will disappear in the + future versions completely. + The use of the latter is especially discouraged as it is not only unsafe but + is also much less efficient than wxArrayString class. + + @tparam T + The type stored in the wxList nodes. @library{wxbase} - @category{FIXME} + @category{containers} - @see wxArray, wxVector + @see wxArray, wxVector, wxNode */ +template class wxList { public: @@ -91,7 +101,7 @@ public: Default constructor. */ wxList(); - + /** Constructor which initialized the list with an array of @a count elements. */ @@ -109,7 +119,7 @@ public: wxList::compatibility_iterator Append(T* object); /** - Clears the list. + Clears the list. Deletes the actual objects if DeleteContents( @true ) was called previously. */ void Clear(); @@ -124,22 +134,22 @@ public: /** Deletes the given element refered to by @a iter from the list if @a iter is a valid iterator. Returns @true if successful. - + Deletes the actual object if DeleteContents( @true ) was called previously. */ bool DeleteNode(const compatibility_iterator& iter); /** Finds the given @a object and removes it from the list, returning - @true if successful. - + @true if successful. + Deletes @a object if DeleteContents( @true ) was called previously. */ bool DeleteObject(T* object); /** Removes element refered to be @a iter. - + Deletes the actualy object if DeleteContents( @true ) was called previously. */ void Erase(const compatibility_iterator& iter); @@ -199,17 +209,19 @@ public: wxList::compatibility_iterator Item(size_t index) const; /** - @note This function is deprecated, use Find() instead. + Check if the object is present in the list. + + @see Find() */ - wxList::compatibility_iterator Member(T* object) const; + bool Member(T* object) const; /** - @note This function is deprecated, use Item() instead. + @deprecated This function is deprecated, use Item() instead. */ wxList::compatibility_iterator Nth(int n) const; /** - @note This function is deprecated, use wxList::GetCount instead. + @deprecated This function is deprecated, use wxList::GetCount instead. Returns the number of elements in the list. */ int Number() const; @@ -229,7 +241,7 @@ public: /** Clears the list and adds @a n items with value @a v to it. */ - void assign(size_type n, const_reference v = value_type()) \ + void assign(size_type n, const_reference v = value_type()); /** Returns the last item of the list. @@ -351,22 +363,24 @@ public: void remove(const_reference v); /** - Returns a reverse iterator pointing to the end of the - reversed list. + Returns a reverse iterator pointing to the end of the reversed list. */ reverse_iterator rend(); /** - Returns a const reverse iterator pointing to the end of the - reversed list. + Returns a const reverse iterator pointing to the end of the reversed list. */ const_reverse_iterator rend() const; /** - Resizes the list. If the the list is enlarges items with - the value @e v are appended to the list. + Resizes the list. + + If the list is longer than @a n, then items are removed until the list + becomes long @a n. + If the list is shorter than @a n items with the value @a v are appended + to the list until the list becomes long @a n. */ - void resize(size_type n); + void resize(size_type n, value_type v = value_type()); /** Reverses the list. @@ -382,15 +396,14 @@ public: /** - @class wxNode - - wxNodeBase is the node structure used in linked lists (see - wxList) and derived classes. You should never use wxNodeBase - class directly, however, because it works with untyped (@c void *) data and - this is unsafe. Use wxNodeBase-derived classes which are automatically defined - by WX_DECLARE_LIST and WX_DEFINE_LIST macros instead as described in - wxList documentation (see example there). Also note that - although there is a class called wxNode, it is defined for backwards + wxNode is the node structure used in linked lists (see wxList) and derived + classes. You should never use wxNode class directly, however, because it + works with untyped (@c void *) data and this is unsafe. + Use wxNode-derived classes which are automatically defined by WX_DECLARE_LIST + and WX_DEFINE_LIST macros instead as described in wxList documentation + (see example there). + + Also note that although there is a class called wxNode, it is defined for backwards compatibility only and usage of this class is strongly deprecated. In the documentation below, the type @c T should be thought of as a @@ -399,11 +412,15 @@ public: written as wxNodeT even though it isn't really a template class -- but it helps to think of it as if it were. + @tparam T + The type stored in the wxNode. + @library{wxbase} - @category{FIXME} + @category{data} @see wxList, wxHashTable */ +template class wxNode { public: