X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/6a93e7940bcc36a8671cafc7ec265e8d961dc070..b9fc07ba8b7472e88089414e1d42e3df1774e9f3:/interface/wx/list.h diff --git a/interface/wx/list.h b/interface/wx/list.h index bd35298d39..7d2f566c63 100644 --- a/interface/wx/list.h +++ b/interface/wx/list.h @@ -3,35 +3,34 @@ // Purpose: interface of wxList // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** - @class wxList - 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 + 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 + 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 + 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 std::list and the old + 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 std::list documentation for further information on how - to use the class. Below we documented both the supported STL and the legacy API + 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. + for 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 + 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 @@ -86,11 +85,15 @@ 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{data} + @category{containers} - @see wxArray, wxVector + @see wxArray, wxVector, wxNode */ +template class wxList { public: @@ -129,7 +132,7 @@ 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. @@ -145,14 +148,14 @@ public: bool DeleteObject(T* object); /** - Removes element refered to be @a iter. + Removes element referred to be @a iter. - Deletes the actualy object if DeleteContents( @true ) was called previously. + 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; @@ -189,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); @@ -200,15 +203,17 @@ 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; /** - @deprecated 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; /** @deprecated This function is deprecated, use Item() instead. @@ -236,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. @@ -369,9 +374,13 @@ public: /** Resizes the list. - If the the list is enlarges items with the value @e v are appended to 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. @@ -387,12 +396,10 @@ 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 + 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 wxNodeBase-derived classes which are automatically defined by WX_DECLARE_LIST + 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). @@ -405,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{data} @see wxList, wxHashTable */ +template class wxNode { public: