X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/76e9224eb2edea8afe45faa6a1cd1b2894d245c2..3399af21d10d3f8ce4f39dfb29df5546ab265ef6:/interface/wx/ctrlsub.h diff --git a/interface/wx/ctrlsub.h b/interface/wx/ctrlsub.h index f9d338c5d5..3f0c41bcd3 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 ///////////////////////////////////////////////////////////////////////////// @@ -40,7 +40,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. @@ -58,7 +58,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. @@ -73,7 +73,7 @@ public: @param string The label to set. */ - virtual void SetString(unsigned int n, const wxString& string); + virtual void SetString(unsigned int n, const wxString& string) = 0; /** Finds an item whose label matches the given string. @@ -106,7 +106,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 @@ -120,15 +120,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. */ @@ -247,7 +252,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 +266,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 +280,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 +293,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 +309,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 +326,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 +352,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 +420,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. @@ -462,8 +516,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. @@ -478,8 +534,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); /** @@ -495,8 +553,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); /** @@ -511,8 +571,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); /** @@ -530,8 +592,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); @@ -550,8 +614,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); //@}