Use wxCOMPtr throughout wxWebViewIE to simplify the code and reduce the chance of...

[wxWidgets.git] / interface / wx / list.h

diff --git a/interface/wx/list.h b/interface/wx/list.h
index e49ae62ed4fd3ea6a66672491355cf70c2e52dd2..7d2f566c631d56a4eb84dfef2542121f3d4e31e8 100644 (file)
--- a/interface/wx/list.h
+++ b/interface/wx/list.h
@@ -3,34 +3,34 @@
 // Purpose:     interface of wxList<T>
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxList<T>
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @wxheader{list.h}
+    The wxList<T> class provides linked list functionality.

 
 

-    The wxList<T> 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<T> 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<T> 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<T> 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<T> destroys an object after removing it only if wxList<T>::DeleteContents
+    has been called.

 
     wxList<T> is not a real template and it requires that you declare and define
 
     wxList<T> 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<T> will actually derive from std::list and just add a legacy
+    each wxList<T> 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<T> will actually derive from @c std::list and just add a legacy

     compatibility layer for the old wxList class.
 
     @code
     compatibility layer for the old wxList class.
 
     @code


@@ -74,17 +74,26 @@
         MyListElement *current = node->GetData();
 
         ...process the current element...
         MyListElement *current = node->GetData();
 
         ...process the current element...

-        
+

         node = node->GetNext();
     }
     @endcode
 
         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}
 
     @library{wxbase}

-    @category{FIXME}
+    @category{containers}

 
 

-    @see wxArray<T>, wxVector<T>
+    @see wxArray<T>, wxVector<T>, wxNode<T>

 */
 */

+template<typename T>

 class wxList<T>
 {
 public:
 class wxList<T>
 {
 public:


@@ -92,9 +101,9 @@ public:
         Default constructor.
     */
     wxList<T>();
         Default constructor.
     */
     wxList<T>();

-    
+

     /**
     /**

-        Constructor which initialized the list with an array of @count elements.
+        Constructor which initialized the list with an array of @a count elements.

     */
     wxList<T>(size_t count, T* elements[]);
 
     */
     wxList<T>(size_t count, T* elements[]);
 


@@ -110,7 +119,7 @@ public:
     wxList<T>::compatibility_iterator Append(T* object);
 
     /**
     wxList<T>::compatibility_iterator Append(T* object);
 
     /**

-        Clears the list. 
+        Clears the list.

         Deletes the actual objects if DeleteContents( @true ) was called previously.
     */
     void Clear();
         Deletes the actual objects if DeleteContents( @true ) was called previously.
     */
     void Clear();


@@ -123,30 +132,30 @@ public:
     void DeleteContents(bool destroy);
 
     /**
     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.
         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
         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);
 
     /**
         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);
 
     /**
     */
     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<T>::compatibility_iterator Find(T* object) const;
 
     */
     wxList<T>::compatibility_iterator Find(T* object) const;
 


@@ -183,7 +192,7 @@ public:
                                            T* object);
 
     /**
                                            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<T>::compatibility_iterator Insert(compatibility_iterator iter,
                                            T* object);
     */
     wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
                                            T* object);


@@ -194,23 +203,25 @@ public:
     bool IsEmpty() const;
 
     /**
     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<T>::compatibility_iterator Item(size_t index) const;
 
     /**
         @a index in the list.
     */
     wxList<T>::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<T>::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<T>::compatibility_iterator Nth(int n) const;
 
     /**
     */
     wxList<T>::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;
         Returns the number of elements in the list.
     */
     int Number() const;


@@ -230,12 +241,12 @@ public:
     /**
        Clears the list and adds @a n items with value @a v to it.
     */
     /**
        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.
     */
 
     /**
         Returns the last item of the list.
     */

-    reference back() const;
+    reference back();

 
     /**
         Returns the last item of the list as a const reference.
 
     /**
         Returns the last item of the list as a const reference.


@@ -245,7 +256,7 @@ public:
     /**
         Returns an iterator pointing to the beginning of the list.
     */
     /**
         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.
 
     /**
         Returns a const iterator pointing to the beginning of the list.


@@ -327,18 +338,18 @@ public:
     /**
         Adds an item to end of the list.
     */
     /**
         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.
     */
 
     /**
         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.
     */
 
     /**
         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
 
     /**
         Returns a const reverse iterator pointing to the beginning of the


@@ -352,22 +363,24 @@ public:
     void remove(const_reference v);
 
     /**
     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;
 
     /**
     */
     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.
 
     /**
         Reverses the list.


@@ -383,16 +396,14 @@ public:
 
 
 /**
 
 
 /**

-    @class wxNode
-    @wxheader{list.h}
-
-    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<T> is the node structure used in linked lists (see wxList) and derived
+    classes. You should never use wxNode<T> class directly, however, because it
+    works with untyped (@c void *) data and this is unsafe.
+    Use wxNode<T>-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
     compatibility only and usage of this class is strongly deprecated.
 
     In the documentation below, the type @c T should be thought of as a


@@ -401,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.
 
     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}
     @library{wxbase}

-    @category{FIXME}
+    @category{data}

 
     @see wxList<T>, wxHashTable
 */
 
     @see wxList<T>, wxHashTable
 */

+template<typename T>

 class wxNode<T>
 {
 public:
 class wxNode<T>
 {
 public: