X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/382f12e41917abf78fb7f00d786c7ead112e4df4..d72177fd4db4389689051dffc7c74a84e58dc4a4:/interface/wx/ctrlsub.h

diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h
index 0a6e4446f8..33652cb461 100644
--- a/interface/wx/ctrlsub.h
+++ b/interface/wx/ctrlsub.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxControlWithItems
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
@@ -247,7 +247,7 @@ public:
         @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.
@@ -261,7 +261,7 @@ public:
             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.
@@ -275,7 +275,7 @@ public:
             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.
@@ -288,7 +288,7 @@ public:
         @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.
@@ -304,8 +304,8 @@ public:
             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.
@@ -321,7 +321,7 @@ public:
             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);
     //@}
 
@@ -347,6 +347,51 @@ public:
     */
     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;
+
+
     //@{
 
     /**
@@ -370,6 +415,10 @@ public:
         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.
 
@@ -463,7 +512,7 @@ public:
         @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.
@@ -479,7 +528,7 @@ public:
             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);
 
     /**
@@ -496,7 +545,7 @@ public:
             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);
 
     /**
@@ -512,7 +561,7 @@ public:
         @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);
 
     /**
@@ -531,7 +580,7 @@ public:
             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);
 
@@ -551,7 +600,7 @@ public:
             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);
     //@}