X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4050e98de9c43a9fa60dffb35202d89d749ba081..4ce846b17c9a1ad71c749253cc8b73d492ed9634:/interface/wx/list.h?ds=sidebyside diff --git a/interface/wx/list.h b/interface/wx/list.h index ed990569a6..eae8cd2cf2 100644 --- a/interface/wx/list.h +++ b/interface/wx/list.h @@ -7,26 +7,28 @@ ///////////////////////////////////////////////////////////////////////////// /** + @class wxList - 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. + The wxList class provides linked list functionality. + + 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. + 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. + 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 @@ -73,14 +75,19 @@ 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. @library{wxbase} - @category{FIXME} + @category{data} @see wxArray, wxVector */ @@ -91,7 +98,7 @@ public: Default constructor. */ wxList(); - + /** Constructor which initialized the list with an array of @a count elements. */ @@ -109,7 +116,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 +131,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 +206,17 @@ public: wxList::compatibility_iterator Item(size_t index) const; /** - @note This function is deprecated, use Find() instead. + @deprecated This function is deprecated, use Find() instead. */ wxList::compatibility_iterator 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,12 +236,12 @@ 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. */ - reference back() const; + reference back(); /** Returns the last item of the list as a const reference. @@ -244,7 +251,7 @@ public: /** Returns an iterator pointing to the beginning of the list. */ - iterator begin() const; + iterator begin(); /** Returns a const iterator pointing to the beginning of the list. @@ -326,18 +333,18 @@ public: /** Adds an item to end of the list. */ - void push_back(); + void push_back(const_reference v = value_type()); /** Adds an item to the front of the list. */ - void push_front(); + void push_front(const_reference v = value_type()); /** Returns a reverse iterator pointing to the beginning of the reversed list. */ - reverse_iterator rbegin() const; + reverse_iterator rbegin(); /** Returns a const reverse iterator pointing to the beginning of the @@ -351,22 +358,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() const; + 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. @@ -384,13 +393,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 + 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 compatibility only and usage of this class is strongly deprecated. In the documentation below, the type @c T should be thought of as a @@ -400,7 +410,7 @@ public: helps to think of it as if it were. @library{wxbase} - @category{FIXME} + @category{data} @see wxList, wxHashTable */