Add wxRTTI for the wxFileSystemWatcherEvent class

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

diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h
index f5407614709e3d61963451f3ca475d5d58f694dc..3f0c41bcd3a2f2c1fa1c480aaf366a056cf12909 100644 (file)
--- a/interface/wx/ctrlsub.h
+++ b/interface/wx/ctrlsub.h
@@ -3,13 +3,12 @@
 // Purpose:     interface of wxControlWithItems
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxControlWithItems
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     @class wxItemContainerImmutable
 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     @class wxItemContainerImmutable

-    @wxheader{ctrlsub.h}

 
     wxItemContainer defines an interface which is implemented by all controls
     which have string subitems each of which may be selected.
 
     wxItemContainer defines an interface which is implemented by all controls
     which have string subitems each of which may be selected.


@@ -41,7 +40,7 @@ public:
 
         @see IsEmpty()
     */
 
         @see IsEmpty()
     */

-    virtual unsigned int GetCount() const;
+    virtual unsigned int GetCount() const = 0;

 
     /**
         Returns @true if the control is empty or @false if it has some items.
 
     /**
         Returns @true if the control is empty or @false if it has some items.


@@ -59,7 +58,7 @@ public:
         @return The label of the item or an empty string if the position was
                 invalid.
     */
         @return The label of the item or an empty string if the position was
                 invalid.
     */

-    virtual wxString GetString(unsigned int n) const;
+    virtual wxString GetString(unsigned int n) const = 0;

 
     /**
         Returns the array of the labels of all items in the control.
 
     /**
         Returns the array of the labels of all items in the control.


@@ -74,7 +73,7 @@ public:
         @param string
             The label to set.
     */
         @param string
             The label to set.
     */

-    virtual void SetString(unsigned int n, const wxString& s);
+    virtual void SetString(unsigned int n, const wxString& string) = 0;

 
     /**
         Finds an item whose label matches the given string.
 
     /**
         Finds an item whose label matches the given string.


@@ -87,7 +86,7 @@ public:
         @return The zero-based position of the item, or wxNOT_FOUND if the
                 string was not found.
     */
         @return The zero-based position of the item, or wxNOT_FOUND if the
                 string was not found.
     */

-    virtual int FindString(const wxString& s, bool bCase = false) const;
+    virtual int FindString(const wxString& string, bool caseSensitive = false) const;

 
     //@}
 
 
     //@}
 


@@ -107,7 +106,7 @@ public:
 
         @see SetString(), SetStringSelection()
     */
 
         @see SetString(), SetStringSelection()
     */

-    virtual void SetSelection(int n);
+    virtual void SetSelection(int n) = 0;

 
     /**
         Returns the index of the selected item or @c wxNOT_FOUND if no item is
 
     /**
         Returns the index of the selected item or @c wxNOT_FOUND if no item is


@@ -121,15 +120,20 @@ public:
 
         @see SetSelection(), GetStringSelection()
     */
 
         @see SetSelection(), GetStringSelection()
     */

-    virtual int GetSelection() const;
+    virtual int GetSelection() const = 0;

 
     /**
 
     /**

-        Selects the item with the specified string in the control. This doesn't
-        cause any command events to be emitted.
+        Selects the item with the specified string in the control.
+
+        This method doesn't cause any command events to be emitted.
+
+        Notice that this method is case-insensitive, i.e. the string is
+        compared with all the elements of the control case-insensitively and
+        the first matching entry is selected, even if it doesn't have exactly
+        the same case as this string and there is an exact match afterwards.

 
         @param string
             The string to select.
 
         @param string
             The string to select.

-

         @return @true if the specified string has been selected, @false if it
                 wasn't found in the control.
     */
         @return @true if the specified string has been selected, @false if it
                 wasn't found in the control.
     */


@@ -155,7 +159,6 @@ public:
 
 /**
     @class wxItemContainer
 
 /**
     @class wxItemContainer

-    @wxheader{ctrlsub.h}

 
     This class is an abstract base class for some wxWidgets controls which
     contain several items such as wxListBox, wxCheckListBox, wxComboBox or
 
     This class is an abstract base class for some wxWidgets controls which
     contain several items such as wxListBox, wxCheckListBox, wxComboBox or


@@ -249,7 +252,7 @@ public:
         @param items
             Array of strings to insert.
     */
         @param items
             Array of strings to insert.
     */

-    void Append(const wxArrayString& items);
+    int Append(const wxArrayString& items);

 
     /**
         Appends several items at once into the control.
 
     /**
         Appends several items at once into the control.


@@ -263,7 +266,7 @@ public:
             Array of client data pointers of the same size as @a items to
             associate with the new items.
     */
             Array of client data pointers of the same size as @a items to
             associate with the new items.
     */

-    void Append(const wxArrayString& items, void **clientData);
+    int Append(const wxArrayString& items, void **clientData);

 
     /**
         Appends several items at once into the control.
 
     /**
         Appends several items at once into the control.


@@ -277,7 +280,7 @@ public:
             Array of client data pointers of the same size as @a items to
             associate with the new items.
     */
             Array of client data pointers of the same size as @a items to
             associate with the new items.
     */

-    void Append(const wxArrayString& items, wxClientData **clientData);
+    int Append(const wxArrayString& items, wxClientData **clientData);

 
     /**
         Appends several items at once into the control.
 
     /**
         Appends several items at once into the control.


@@ -290,7 +293,7 @@ public:
         @param items
             Array of strings of size @a n.
     */
         @param items
             Array of strings of size @a n.
     */

-    void Append(unsigned int n, const wxString* items);
+    int Append(unsigned int n, const wxString* items);

 
     /**
         Appends several items at once into the control.
 
     /**
         Appends several items at once into the control.


@@ -306,8 +309,8 @@ public:
             Array of client data pointers of size @a n to associate with the
             new items.
     */
             Array of client data pointers of size @a n to associate with the
             new items.
     */

-    void Append(unsigned int n, const wxString* items,
-                void** clientData);
+    int Append(unsigned int n, const wxString* items,
+               void** clientData);

 
     /**
         Appends several items at once into the control.
 
     /**
         Appends several items at once into the control.


@@ -323,7 +326,7 @@ public:
             Array of client data pointers of size @a n to associate with the
             new items.
     */
             Array of client data pointers of size @a n to associate with the
             new items.
     */

-    void Append(unsigned int n, const wxString* items,
+    int Append(unsigned int n, const wxString* items,

                 wxClientData** clientData);
     //@}
 
                 wxClientData** clientData);
     //@}
 


@@ -349,6 +352,51 @@ public:
     */
     void Delete(unsigned int n);
 
     */
     void Delete(unsigned int n);
 

+
+    /**
+        Returns the client object associated with the given item and transfers
+        its ownership to the caller.
+
+        This method, unlike GetClientObject(), expects the caller to delete the
+        returned pointer. It also replaces the internally stored pointer with
+        @NULL, i.e. completely detaches the client object pointer from the
+        control.
+
+        It's an error to call this method unless HasClientObjectData() returns
+        @true.
+
+        @param n
+            The zero-based item index.
+        @return The associated client object pointer to be deleted by caller or
+            @NULL.
+
+        @since 2.9.2
+     */
+    wxClientData *DetachClientObject(unsigned int n);
+
+    /**
+       Returns true, if either untyped data (@c void*) or object data (wxClientData*)
+       is associated with the items of the control.
+    */
+    bool HasClientData() const;
+
+    /**
+       Returns true, if object data is associated with the items of the
+       control.
+
+       Object data pointers have the type @c wxClientData* instead of @c void*
+       and, importantly, are owned by the control, i.e. will be deleted by it,
+       unlike their untyped counterparts.
+    */
+    bool HasClientObjectData() const;
+
+    /**
+       Returns true, if untyped data (@c void*)
+       is associated with the items of the control.
+    */
+    bool HasClientUntypedData() const;
+
+

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


@@ -372,6 +420,10 @@ public:
         given item doesn't have any client data associated with it (but other
         items do).
 
         given item doesn't have any client data associated with it (but other
         items do).
 

+        Notice that the returned pointer is still owned by the control and will
+        be deleted by it, use DetachClientObject() if you want to remove the
+        pointer from the control.
+

         @param n
             The zero-based position of the item.
 
         @param n
             The zero-based position of the item.
 


@@ -464,8 +516,10 @@ public:
             Array of strings to insert.
         @param pos
             Position to insert the items before, zero based.
             Array of strings to insert.
         @param pos
             Position to insert the items before, zero based.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(const wxArrayString& items, unsigned int pos);
+    int Insert(const wxArrayString& items, unsigned int pos);

 
     /**
         Inserts several items at once into the control.
 
     /**
         Inserts several items at once into the control.


@@ -480,8 +534,10 @@ public:
         @param clientData
             Array of client data pointers of the same size as @a items to
             associate with the new items.
         @param clientData
             Array of client data pointers of the same size as @a items to
             associate with the new items.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(const wxArrayString& items, unsigned int pos,
+    int Insert(const wxArrayString& items, unsigned int pos,

                 void **clientData);
 
     /**
                 void **clientData);
 
     /**


@@ -497,8 +553,10 @@ public:
         @param clientData
             Array of client data pointers of the same size as @a items to
             associate with the new items.
         @param clientData
             Array of client data pointers of the same size as @a items to
             associate with the new items.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(const wxArrayString& items, unsigned int pos,
+    int Insert(const wxArrayString& items, unsigned int pos,

                 wxClientData **clientData);
 
     /**
                 wxClientData **clientData);
 
     /**


@@ -513,8 +571,10 @@ public:
             Array of strings of size @a n.
         @param pos
             Position to insert the items before, zero based.
             Array of strings of size @a n.
         @param pos
             Position to insert the items before, zero based.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(unsigned int n, const wxString* items,
+    int Insert(unsigned int n, const wxString* items,

                 unsigned int pos);
 
     /**
                 unsigned int pos);
 
     /**


@@ -532,8 +592,10 @@ public:
         @param clientData
             Array of client data pointers of size @a n to associate with the
             new items.
         @param clientData
             Array of client data pointers of size @a n to associate with the
             new items.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(unsigned int n, const wxString* items,
+    int Insert(unsigned int n, const wxString* items,

                 unsigned int pos,
                 void** clientData);
 
                 unsigned int pos,
                 void** clientData);
 


@@ -552,8 +614,10 @@ public:
         @param clientData
             Array of client data pointers of size @a n to associate with the
             new items.
         @param clientData
             Array of client data pointers of size @a n to associate with the
             new items.

+        @return The return value is the index of the last inserted item.
+                If the insertion failed for some reason, -1 is returned.

     */
     */

-    void Insert(unsigned int n, const wxString* items,
+    int Insert(unsigned int n, const wxString* items,

                 unsigned int pos,
                 wxClientData** clientData);
     //@}
                 unsigned int pos,
                 wxClientData** clientData);
     //@}


@@ -648,7 +712,6 @@ public:
 
 /**
     @class wxControlWithItems
 
 /**
     @class wxControlWithItems

-    @wxheader{ctrlsub.h}

 
     This is convenience class that derives from both wxControl and
     wxItemContainer. It is used as basis for some wxWidgets controls
 
     This is convenience class that derives from both wxControl and
     wxItemContainer. It is used as basis for some wxWidgets controls