added wxWindowDisabler ctor for conditionally disabling all windows and use it in...

[wxWidgets.git] / interface / list.h

diff --git a/interface/list.h b/interface/list.h
index cf7c7175cf2f52143977c0a911b1a79c1655ac6e..6988f7feb82b3dd43fc8376fe2358ec87b6a664d 100644 (file)
--- a/interface/list.h
+++ b/interface/list.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // 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


@@ -9,38 +9,37 @@
 /**
     @class wxListT
     @wxheader{list.h}
 /**
     @class wxListT
     @wxheader{list.h}

-    
+

     The wxListT 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 wxListT actually stores
     pointers and therefore its iterators return pointers and not references
     The wxListT 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 wxListT 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 
+    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
     if wxList::DeleteContents has been called.
     is defined as @e T*. wxListT destroys an object after removing it only
     if wxList::DeleteContents has been called.

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

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

-    
+

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

-    
-    @seealso
-    wxArrayT, wxVectorT
+
+    @see wxArrayT(), wxVectorT()

 */
 */

-class wxList<T> 
+class wxList<T>

 {
 public:
     //@{
 {
 public:
     //@{


@@ -48,7 +47,7 @@ public:
         Constructors.
     */
     wxListT();
         Constructors.
     */
     wxListT();

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

     //@}
 
     /**
     //@}
 
     /**


@@ -58,9 +57,9 @@ public:
     ~wxListT();
 
     /**
     ~wxListT();
 
     /**

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

     */
     */

-    wxListT::compatibility_iterator Append(T * object);
+    wxListT::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,24 +68,24 @@ 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.
     */
     void DeleteContents(bool destroy);
 
     /**
         on objects stored in the list whenever they are removed.
         The default is @false.
     */
     void DeleteContents(bool destroy);
 
     /**

-        Deletes the given element refered to by @c iter from the list, 
+        Deletes the given element refered to by @c iter from the list,

         returning @true if successful.
     */
     bool DeleteNode(const compatibility_iterator& iter);
 
     /**
         returning @true if successful.
     */
     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 +93,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);
+    wxListT::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();
+    wxListT::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();
+    wxListT::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);
+    wxListT::compatibility_iterator Insert(T* object);
+    wxListT::compatibility_iterator Insert(size_t position,
+                                           T* object);
+    wxListT::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);
+    wxListT::compatibility_iterator Item(size_t index) const;

 
     /**
         @b NB: This function is deprecated, use wxList::Find instead.
     */
 
     /**
         @b NB: This function is deprecated, use wxList::Find instead.
     */

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

 
     /**
         @b NB: This function is deprecated, use @ref wxList::itemfunc Item instead.
 
     /**
         @b NB: 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 */
+    wxListT::compatibility_iterator Nth(int n) const;

 
     /**
         @b NB: This function is deprecated, use wxList::GetCount instead.
 
     /**
         @b NB: 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


@@ -174,23 +171,23 @@ public:
         )
     */
     void assign(const_iterator first, const const_iterator& last);
         )
     */
     void assign(const_iterator first, const const_iterator& last);

-        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;
+    const_reference back() const;

     //@}
 
     //@{
     /**
         Returns a (const) iterator pointing to the beginning of the list.
     */
     //@}
 
     //@{
     /**
         Returns a (const) iterator pointing to the beginning of the list.
     */

-    iterator begin();
-        const_iterator begin();
+    iterator begin() const;
+    const_iterator begin() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -201,31 +198,31 @@ 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();
+    iterator end() const;
+    const_iterator end() const;

     //@}
 
     //@{
     /**
     //@}
 
     //@{
     /**

-        Erases the items from @e first to @e last.
+        Erases the items from @a first to @e last.

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

-        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;
+    const_reference front() const;

     //@}
 
     //@{
     //@}
 
     //@{


@@ -233,15 +230,15 @@ public:
         Inserts an item (or several) at the given position.
     */
     iterator insert(const iterator& it);
         Inserts an item (or several) at the given position.
     */
     iterator insert(const iterator& it);

-        void insert(const iterator& it, size_type n);
-        void insert(const iterator& it, const_iterator first,
-                    const const_iterator& last);
+    void insert(const iterator& it, size_type n);
+    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.


@@ -255,14 +252,12 @@ public:
 
     /**
         )
 
     /**
         )

-        

         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();


@@ -272,8 +267,8 @@ public:
         Returns a (const) reverse iterator pointing to the beginning of the
         reversed list.
     */
         Returns a (const) reverse iterator pointing to the beginning of the
         reversed list.
     */

-    reverse_iterator rbegin();
-        const_reverse_iterator rbegin();
+    reverse_iterator rbegin() const;
+    const_reverse_iterator rbegin() const;

     //@}
 
     /**
     //@}
 
     /**


@@ -286,13 +281,12 @@ public:
         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.
     */

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


@@ -306,15 +300,16 @@ 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}

-    
-    wxNodeBase is the node structure used in linked lists (see 
+
+    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
     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


@@ -322,36 +317,35 @@ public:
     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.
     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
     "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 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,
     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.

-    
+

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

-    
-    @seealso
-    wxList, wxHashTable
+
+    @see wxList, wxHashTable

 */
 */

-class wxNode 
+class wxNode

 {
 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();
+    wxNodeT* 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();
+    wxNodeT* 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 +357,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);

 };
 };

+