X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/ctrlsub.h

diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h
index f540761470..728cba07d5 100644
--- a/interface/wx/ctrlsub.h
+++ b/interface/wx/ctrlsub.h
@@ -2,14 +2,12 @@
 // Name:        ctrlsub.h
 // Purpose:     interface of wxControlWithItems
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 
 /**
     @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.
@@ -41,7 +39,7 @@ public:
 
         @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.
@@ -59,7 +57,7 @@ public:
         @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.
@@ -74,7 +72,7 @@ public:
         @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.
@@ -87,7 +85,7 @@ public:
         @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 +105,7 @@ public:
 
         @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
@@ -121,15 +119,20 @@ public:
 
         @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.
-
         @return @true if the specified string has been selected, @false if it
                 wasn't found in the control.
     */
@@ -155,7 +158,6 @@ public:
 
 /**
     @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
@@ -249,7 +251,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.
@@ -263,7 +265,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.
@@ -277,7 +279,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.
@@ -290,7 +292,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.
@@ -306,8 +308,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.
@@ -323,7 +325,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);
     //@}
 
@@ -349,6 +351,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;
+
+
     //@{
 
     /**
@@ -372,6 +419,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.
 
@@ -464,8 +515,10 @@ public:
             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.
@@ -480,8 +533,10 @@ public:
         @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);
 
     /**
@@ -497,8 +552,10 @@ public:
         @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);
 
     /**
@@ -513,8 +570,10 @@ public:
             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);
 
     /**
@@ -532,8 +591,10 @@ public:
         @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);
 
@@ -552,8 +613,10 @@ public:
         @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);
     //@}
@@ -648,7 +711,6 @@ public:
 
 /**
     @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