X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/4050e98de9c43a9fa60dffb35202d89d749ba081..50d4763f1710f6e45ac6af7112d1ce9effe93bc4:/interface/wx/list.h diff --git a/interface/wx/list.h b/interface/wx/list.h index ed990569a6..7d2f566c63 100644 --- a/interface/wx/list.h +++ b/interface/wx/list.h @@ -3,33 +3,34 @@ // Purpose: interface of wxList // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** + 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 objects 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 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(); @@ -122,30 +132,30 @@ public: void DeleteContents(bool destroy); /** - Deletes the given element refered to by @a iter from the list + Deletes the given element referred 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. + Removes element referred to be @a iter. + + Deletes the actual object if DeleteContents( @true ) was called previously. */ void Erase(const compatibility_iterator& iter); /** - Returns the iterator refering to @a object or @NULL if none found. + Returns the iterator referring to @a object or @NULL if none found. */ wxList::compatibility_iterator Find(T* object) const; @@ -182,7 +192,7 @@ public: T* object); /** - Inserts @a object before the object refered to be @a iter. + Inserts @a object before the object referred to be @a iter. */ wxList::compatibility_iterator Insert(compatibility_iterator iter, T* object); @@ -193,23 +203,25 @@ public: bool IsEmpty() const; /** - Returns the iterator refering to the object at the given + Returns the iterator referring to the object at the given @a index in the list. */ 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,12 +241,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 +256,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 +338,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 +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() 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. @@ -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: