Added wxPGProperty::Enable() for conveniency. Refactored related code and improved...

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

diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h
index f5407614709e3d61963451f3ca475d5d58f694dc..33652cb4619f2d99695190a83c4e238d8661799d 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,7 +120,7 @@ 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
 
     /**
         Selects the item with the specified string in the control. This doesn't


@@ -155,7 +154,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 +247,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 +261,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 +275,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 +288,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 +304,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 +321,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 +347,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 +415,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.
 


@@ -465,7 +512,7 @@ public:
         @param pos
             Position to insert the items before, zero based.
     */
         @param pos
             Position to insert the items before, zero based.
     */

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


@@ -481,7 +528,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 Insert(const wxArrayString& items, unsigned int pos,
+    int Insert(const wxArrayString& items, unsigned int pos,

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


@@ -498,7 +545,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 Insert(const wxArrayString& items, unsigned int pos,
+    int Insert(const wxArrayString& items, unsigned int pos,

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


@@ -514,7 +561,7 @@ public:
         @param pos
             Position to insert the items before, zero based.
     */
         @param pos
             Position to insert the items before, zero based.
     */

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

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


@@ -533,7 +580,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 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);
 


@@ -553,7 +600,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 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 +695,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