Mention wxDataViewTreeCtrl in wxTreeCtrl

[wxWidgets.git] / interface / list.h

diff --git a/interface/list.h b/interface/list.h
index 679bff3e46366eba8df643078264b51e8011a6fe..3e2f5a95b9d5cb7c4a822673f4fc860a88efec35 100644 (file)
--- a/interface/list.h
+++ b/interface/list.h
@@ -1,24 +1,23 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        list.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        list.h

-// Purpose:     documentation for wxList<T> class
+// Purpose:     interface of wxList<T>

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 /**
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 /**

-    @class wxListT

     @wxheader{list.h}
 
     @wxheader{list.h}
 

-    The wxListT class provides linked list functionality. It has been rewritten
+    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
     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 wxListT actually stores
+    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
     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*. wxListT destroys an object after removing it only
+    is defined as @e T*. wxList<T> destroys an object after removing it only

     if wxList::DeleteContents has been called.
 
     if wxList::DeleteContents has been called.
 

-    wxListT 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
     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


@@ -31,14 +30,60 @@
     the the same class.
 
     Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)
     the the same class.
 
     Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)

-    then wxListT will actually derive from std::list and just add a legacy
+    then wxList<T> will actually derive from std::list and just add a legacy

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

+    @code
+    // this part might be in a header or source (.cpp) file
+    class MyListElement
+    {
+        ... // whatever
+    };
+
+    // this macro declares and partly implements MyList class
+    WX_DECLARE_LIST(MyListElement, MyList);
+
+    ...
+
+    // the only requirement for the rest is to be AFTER the full declaration of
+    // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
+    // usually it will be found in the source file and not in the header
+
+    #include <wx/listimpl.cpp>
+    WX_DEFINE_LIST(MyList);
+
+
+    MyList list;
+    MyListElement element;
+    list.Append(&element);     // ok
+    list.Append(17);           // error: incorrect type
+
+    // let's iterate over the list in STL syntax
+    MyList::iterator iter;
+    for (iter = list.begin(); iter != list.end(); ++iter)
+    {
+        MyListElement *current = *iter;
+
+        ...process the current element...
+    }
+
+    // the same with the legacy API from the old wxList class
+    MyList::compatibility_iterator node = list.GetFirst();
+    while (node)
+    {
+        MyListElement *current = node->GetData();
+
+        ...process the current element...
+        
+        node = node->GetNext();
+    }
+    @endcode
+
+

     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

-    @seealso
-    wxArrayT, wxVectorT
+    @see wxArray<T>, wxVector<T>

 */
 class wxList<T>
 {
 */
 class wxList<T>
 {


@@ -47,20 +92,20 @@ public:
     /**
         Constructors.
     */
     /**
         Constructors.
     */

-    wxListT();
-    wxListT(size_t count, T * elements[]);
+    wxList<T>();
+    wxList<T>(size_t count, T* elements[]);

     //@}
 
     /**
         Destroys the list, but does not delete the objects stored in the list
         unless you called DeleteContents(@true ).
     */
     //@}
 
     /**
         Destroys the list, but does not delete the objects stored in the list
         unless you called DeleteContents(@true ).
     */

-    ~wxListT();
+    ~wxList<T>();

 
     /**
 
     /**

-        Appends the pointer to @e object to the list.
+        Appends the pointer to @a object to the list.

     */
     */

-    wxListT::compatibility_iterator Append(T * object);
+    wxList<T>::compatibility_iterator Append(T* object);

 
     /**
         Clears the list, but does not delete the objects stored in the list
 
     /**
         Clears the list, but does not delete the objects stored in the list


@@ -69,7 +114,7 @@ public:
     void Clear();
 
     /**
     void Clear();
 
     /**

-        If @e destroy is @true, instructs the list to call @e delete
+        If @a destroy is @true, instructs the list to call @e delete

         on objects stored in the list whenever they are removed.
         The default is @false.
     */
         on objects stored in the list whenever they are removed.
         The default is @false.
     */


@@ -82,11 +127,11 @@ public:
     bool DeleteNode(const compatibility_iterator& iter);
 
     /**
     bool DeleteNode(const compatibility_iterator& iter);
 
     /**

-        Finds the given @e object and removes it from the list, returning
+        Finds the given @a object and removes it from the list, returning

         @true if successful. The application must delete the actual object
         separately.
     */
         @true if successful. The application must delete the actual object
         separately.
     */

-    bool DeleteObject(T * object);
+    bool DeleteObject(T* object);

 
     /**
         Removes element refered to be @c iter.
 
     /**
         Removes element refered to be @c iter.


@@ -94,73 +139,71 @@ public:
     void Erase(const compatibility_iterator& iter);
 
     /**
     void Erase(const compatibility_iterator& iter);
 
     /**

-        Returns the iterator refering to @e object or @NULL if none found.
+        Returns the iterator refering to @a object or @NULL if none found.

     */
     */

-    wxListT::compatibility_iterator Find(T * object);
+    wxList<T>::compatibility_iterator Find(T* object) const;

 
     /**
         Returns the number of elements in the list.
     */
 
     /**
         Returns the number of elements in the list.
     */

-    size_t GetCount();
+    size_t GetCount() const;

 
     /**
         Returns the first iterator in the list (@NULL if the list is empty).
     */
 
     /**
         Returns the first iterator in the list (@NULL if the list is empty).
     */

-    wxListT::compatibility_iterator GetFirst();
+    wxList<T>::compatibility_iterator GetFirst() const;

 
     /**
         Returns the last iterator in the list (@NULL if the list is empty).
     */
 
     /**
         Returns the last iterator in the list (@NULL if the list is empty).
     */

-    wxListT::compatibility_iterator GetLast();
+    wxList<T>::compatibility_iterator GetLast() const;

 
     /**
 
     /**

-        Returns the index of @e obj within the list or @c wxNOT_FOUND if
-        @e obj is not found in the list.
+        Returns the index of @a obj within the list or @c wxNOT_FOUND if
+        @a obj is not found in the list.

     */
     */

-    int IndexOf(T* obj);
+    int IndexOf(T* obj) const;

 
     //@{
     /**
         Inserts the object before the object refered to be @e iter.
     */
 
     //@{
     /**
         Inserts the object before the object refered to be @e iter.
     */

-    wxListT::compatibility_iterator Insert(T * object);
-    wxListT::compatibility_iterator Insert(size_t position,
-                                           T * object);
-    wxListT::compatibility_iterator Insert(compatibility_iterator iter,
-                                           T * object);
+    wxList<T>::compatibility_iterator Insert(T* object);
+    wxList<T>::compatibility_iterator Insert(size_t position,
+                                           T* object);
+    wxList<T>::compatibility_iterator Insert(compatibility_iterator iter,
+                                           T* object);

     //@}
 
     /**
         Returns @true if the list is empty, @false otherwise.
     */
     //@}
 
     /**
         Returns @true if the list is empty, @false otherwise.
     */

-    bool IsEmpty();
+    bool IsEmpty() const;

 
     /**
         Returns the iterator refering to the object at the given
         @c index in the list.
     */
 
     /**
         Returns the iterator refering to the object at the given
         @c index in the list.
     */

-    wxListT::compatibility_iterator Item(size_t index);
+    wxList<T>::compatibility_iterator Item(size_t index) const;

 
     /**
 
     /**

-        @b NB: This function is deprecated, use wxList::Find instead.
+        @note This function is deprecated, use wxList::Find instead.

     */
     */

-    wxListT::compatibility_iterator Member(T * object);
+    wxList<T>::compatibility_iterator Member(T* object) const;

 
     /**
 
     /**

-        @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead.
-        
+        @note This function is deprecated, use @ref wxList::itemfunc Item instead.

         Returns the @e nth node in the list, indexing from zero (@NULL if the list is
         empty
         or the nth node could not be found).
     */
         Returns the @e nth node in the list, indexing from zero (@NULL if the list is
         empty
         or the nth node could not be found).
     */

-#define wxListT::compatibility_iterator Nth(int n)     /* implementation is private */
+    wxList<T>::compatibility_iterator Nth(int n) const;

 
     /**
 
     /**

-        @b NB: This function is deprecated, use wxList::GetCount instead.
-        
+        @note This function is deprecated, use wxList::GetCount instead.

         Returns the number of elements in the list.
     */
         Returns the number of elements in the list.
     */

-    int Number();
+    int Number() const;

 
     /**
         Allows the sorting of arbitrary lists by giving a function to compare
 
     /**
         Allows the sorting of arbitrary lists by giving a function to compare


@@ -177,21 +220,25 @@ public:
     void assign(size_type n);
     //@}
 
     void assign(size_type n);
     //@}
 

-    //@{

     /**
         Returns the last item of the list.
     */
     /**
         Returns the last item of the list.
     */

-    reference back();
-    const_reference back();
-    //@}
+    reference back() const;

 
 

-    //@{

     /**
     /**

-        Returns a (const) iterator pointing to the beginning of the list.
+        Returns the last item of the list as a const reference.

     */
     */

-    iterator begin();
-    const_iterator begin();
-    //@}
+    const_reference back() const;
+
+    /**
+        Returns an iterator pointing to the beginning of the list.
+    */
+    iterator begin() const;
+
+    /**
+        Returns a const iterator pointing to the beginning of the list.
+    */
+    const_iterator begin() const;

 
     /**
         Removes all items from the list.
 
     /**
         Removes all items from the list.


@@ -201,47 +248,59 @@ public:
     /**
         Returns @e @true if the list is empty.
     */
     /**
         Returns @e @true if the list is empty.
     */

-    bool empty();
+    bool empty() const;

 
 

-    //@{

     /**
     /**

-        Returns a (const) iterator pointing at the end of the list.
+        Returns a const iterator pointing at the end of the list.

     */
     */

-    iterator end();
-    const_iterator end();
-    //@}
+    const_iterator end() const;

 
 

-    //@{

     /**
     /**

-        Erases the items from @e first to @e last.
+        Returns a iterator pointing at the end of the list.
+    */
+    iterator end() const;
+
+    /**
+        Erases the given item

     */
     iterator erase(const iterator& it);
     */
     iterator erase(const iterator& it);

+
+    /**
+        Erases the items from @e first to @e last.
+    */

     iterator erase(const iterator& first,
                    const iterator& last);
     iterator erase(const iterator& first,
                    const iterator& last);

-    //@}

 
 

-    //@{

     /**
         Returns the first item in the list.
     */
     /**
         Returns the first item in the list.
     */

-    reference front();
-    const_reference front();
-    //@}
+    reference front() const;

 
 

-    //@{

     /**
     /**

-        Inserts an item (or several) at the given position.
+        Returns the first item in the list as a const reference.
+    */
+    const_reference front() const;
+
+    /**
+        Inserts an item at the head of the list

     */
     iterator insert(const iterator& it);
     */
     iterator insert(const iterator& it);

+
+    /**
+        Inserts an item at the given position
+    */

     void insert(const iterator& it, size_type n);
     void insert(const iterator& it, size_type n);

+
+    /**
+        Inserts several items at the given position.
+    */

     void insert(const iterator& it, const_iterator first,
                 const const_iterator& last);
     void insert(const iterator& it, const_iterator first,
                 const const_iterator& last);

-    //@}

 
     /**
         Returns the largest possible size of the list.
     */
 
     /**
         Returns the largest possible size of the list.
     */

-    size_type max_size();
+    size_type max_size() const;

 
     /**
         Removes the last item from the list.
 
     /**
         Removes the last item from the list.


@@ -254,45 +313,45 @@ public:
     void pop_front();
 
     /**
     void pop_front();
 
     /**

-        )
-        

         Adds an item to end of the list.
     */
     void push_back();
 
     /**
         Adds an item to end of the list.
     */
     void push_back();
 
     /**

-        )
-        

         Adds an item to the front of the list.
     */
     void push_front();
 
         Adds an item to the front of the list.
     */
     void push_front();
 

-    //@{

     /**
     /**

-        Returns a (const) reverse iterator pointing to the beginning of the
+        Returns a reverse iterator pointing to the beginning of the

         reversed list.
     */
         reversed list.
     */

-    reverse_iterator rbegin();
-    const_reverse_iterator rbegin();
-    //@}
+    reverse_iterator rbegin() const;
+
+    /**
+        Returns a const reverse iterator pointing to the beginning of the
+        reversed list.
+    */
+    const_reverse_iterator rbegin() const;

 
     /**
         Removes an item from the list.
     */
     void remove(const_reference v);
 
 
     /**
         Removes an item from the list.
     */
     void remove(const_reference v);
 

-    //@{

     /**
     /**

-        Returns a (const) reverse iterator pointing to the end of the
+        Returns a reverse iterator pointing to the end of the

         reversed list.
     */
         reversed list.
     */

-    reverse_iterator rend();
-    const_reverse_iterator rend();
-    //@}
+    reverse_iterator rend() const;
+
+    /**
+        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 the list is enlarges items with
         the value @e v are appended to the list.
     */


@@ -306,10 +365,11 @@ public:
     /**
         Returns the size of the list.
     */
     /**
         Returns the size of the list.
     */

-    size_type size();
+    size_type size() const;

 };
 
 
 };
 
 

+

 /**
     @class wxNode
     @wxheader{list.h}
 /**
     @class wxNode
     @wxheader{list.h}


@@ -324,7 +384,7 @@ public:
     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

-    "template'' parameter: this is the type of data stored in the linked list or,
+    "template" parameter: this is the type of data stored in the linked list or,

     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
     written as wxNodeT even though it isn't really a template class -- but it
     helps to think of it as if it were.
     in other words, the first argument of WX_DECLARE_LIST macro. Also, wxNode is
     written as wxNodeT even though it isn't really a template class -- but it
     helps to think of it as if it were.


@@ -332,26 +392,25 @@ public:
     @library{wxbase}
     @category{FIXME}
 
     @library{wxbase}
     @category{FIXME}
 

-    @seealso
-    wxList, wxHashTable
+    @see wxList<T>, wxHashTable

 */
 */

-class wxNode
+class wxNode<T>

 {
 public:
     /**
         Retrieves the client data pointer associated with the node.
     */
 {
 public:
     /**
         Retrieves the client data pointer associated with the node.
     */

-    T * GetData();
+    T* GetData() const;

 
     /**
         Retrieves the next node or @NULL if this node is the last one.
     */
 
     /**
         Retrieves the next node or @NULL if this node is the last one.
     */

-    wxNodeT * GetNext();
+    wxNode<T>* GetNext() const;

 
     /**
         Retrieves the previous node or @NULL if this node is the first one in the list.
     */
 
     /**
         Retrieves the previous node or @NULL if this node is the first one in the list.
     */

-    wxNodeT * GetPrevious();
+    wxNode<T>* GetPrevious();

 
     /**
         Returns the zero-based index of this node within the list. The return value
 
     /**
         Returns the zero-based index of this node within the list. The return value


@@ -363,5 +422,6 @@ public:
         Sets the data associated with the node (usually the pointer will have been
         set when the node was created).
     */
         Sets the data associated with the node (usually the pointer will have been
         set when the node was created).
     */

-    void SetData(T * data);
+    void SetData(T* data);

 };
 };

+