added wxGenericStaticBitmap (#9608)

[wxWidgets.git] / interface / ctrlsub.h

diff --git a/interface/ctrlsub.h b/interface/ctrlsub.h
index f0211eef44b4840cb7c4f0818d0f2e0e8f40c7c2..f5407614709e3d61963451f3ca475d5d58f694dc 100644 (file)
--- a/interface/ctrlsub.h
+++ b/interface/ctrlsub.h
@@ -1,355 +1,665 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        ctrlsub.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        ctrlsub.h

-// Purpose:     documentation for wxControlWithItems class
+// Purpose:     interface of wxControlWithItems

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

+

 /**
 /**

-    @class wxControlWithItems
+    @class wxItemContainerImmutable

     @wxheader{ctrlsub.h}
 
     @wxheader{ctrlsub.h}
 

-    This class is an abstract base class for some wxWidgets controls which contain
-    several items, such as wxListBox and
-    wxCheckListBox derived from it,
-    wxChoice and wxComboBox.
+    wxItemContainer defines an interface which is implemented by all controls
+    which have string subitems each of which may be selected.

 
 

-    It defines the methods for accessing the controls items and although each of
-    the derived classes implements them differently, they still all conform to the
-    same interface.
+    It is decomposed in wxItemContainerImmutable which omits all methods
+    adding/removing items and is used by wxRadioBox and wxItemContainer itself.

 
 

-    The items in a wxControlWithItems have (non-empty) string labels and,
-    optionally, client data associated with them. Client data may be of two
-    different kinds: either simple untyped (@c void *) pointers which are simply
-    stored by the control but not used in any way by it, or typed pointers
-    (@c wxClientData *) which are owned by the control meaning that the typed
-    client data (and only it) will be deleted when an item is
-    @ref wxControlWithItems::delete deleted or the entire control is
-    @ref wxControlWithItems::clear cleared (which also happens when it is
-    destroyed). Finally note that in the same control all items must have client
-    data of the same type (typed or untyped), if any. This type is determined by
-    the first call to wxControlWithItems::Append (the version with
-    client data pointer) or wxControlWithItems::SetClientData.
+    Note that this is not a control, it's a mixin interface that classes
+    have to derive from in addition to wxControl or wxWindow.
+
+    Examples: wxListBox, wxCheckListBox, wxChoice and wxComboBox (which
+    implements an extended interface deriving from this one)

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{ctrl}

 
 

-    @seealso
-    wxControlWithItems::Clear
+    @see wxControlWithItems, wxItemContainer

 */
 */

-class wxControlWithItems : public wxControl
+class wxItemContainerImmutable

 {
 public:
 {
 public:

+    /// Constructor
+    wxItemContainerImmutable();
+

     //@{
     //@{

+

     /**
     /**

-        Appends several items at once to the control. Notice that calling this method
-        is usually much faster than appending them one by one if you need to add a lot
-        of items.
-        
-        @param item
-        String to add.
-        
-        @param stringsArray
-        Contains items to append to the control.
-        
-        @param strings
-        Array of strings of size n.
-        
-        @param n
-        Number of items in the strings array.
-        
-        @param clientData
-        Array of client data pointers of size n to associate with the new items.
-        
-        @returns When appending a single item, the return value is the index of
-                   the newly added item which may be different from the
-                   last one if the control is sorted (e.g. has wxLB_SORT
-                   or wxCB_SORT style).
+        Returns the number of items in the control.
+
+        @see IsEmpty()

     */
     */

-    int Append(const wxString& item);
-    int Append(const wxString& item, void * clientData);
-    int Append(const wxString& item, wxClientData * clientData);
-    void Append(const wxArrayString& strings);
-    void Append(unsigned int n, const wxString* strings);
-    void Append(unsigned int n, const wxString* strings,
-                void ** clientData);
-    void Append(unsigned int n, const wxString* strings,
-                wxClientData ** clientData);
-    //@}
+    virtual unsigned int GetCount() const;

 
     /**
 
     /**

-        Removes all items from the control.
-        
-        @e Clear() also deletes the client data of the existing items if it is owned
-        by the control.
+        Returns @true if the control is empty or @false if it has some items.
+
+        @see GetCount()

     */
     */

-    void Clear();
+    bool IsEmpty() const;

 
     /**
 
     /**

-        Deletes an item from the control. The client data associated with the item
-        will be also deleted if it is owned by the control.
-        
-        Note that it is an error (signalled by an assert failure in debug builds) to
-        remove an item with the index negative or greater or equal than the number of
-        items in the control.
-        
+        Returns the label of the item with the given index.
+

         @param n
         @param n

-        The zero-based item index.
-        
-        @sa Clear()
+            The zero-based index.
+
+        @return The label of the item or an empty string if the position was
+                invalid.

     */
     */

-    void Delete(unsigned int n);
+    virtual wxString GetString(unsigned int n) const;

 
     /**
 
     /**

-        Finds an item whose label matches the given string.
-        
-        @param string
-        String to find.
-        
-        @param caseSensitive
-        Whether search is case sensitive (default is not).
-        
-        @returns The zero-based position of the item, or wxNOT_FOUND if the
-                   string was not found.
+        Returns the array of the labels of all items in the control.

     */
     */

-    int FindString(const wxString& string,
-                   bool caseSensitive = @false);
+    wxArrayString GetStrings() const;

 
     /**
 
     /**

-        Returns a pointer to the client data associated with the given item (if any).
-        It is an error to call this function for a control which doesn't have untyped
-        client data at all although it is ok to call it even if the given item doesn't
-        have any client data associated with it (but other items do).
-        
+        Sets the label for the given item.
+

         @param n
         @param n

-        The zero-based position of the item.
-        
-        @returns A pointer to the client data, or @NULL if not present.
+            The zero-based item index.
+        @param string
+            The label to set.

     */
     */

-    void * GetClientData(unsigned int n);
+    virtual void SetString(unsigned int n, const wxString& s);

 
     /**
 
     /**

-        Returns a pointer to the client data associated with the given item (if any).
-        It is an error to call this function for a control which doesn't have typed
-        client data at all although it is ok to call it even if the given item doesn't
-        have any client data associated with it (but other items do).
-        
-        @param n
-        The zero-based position of the item.
-        
-        @returns A pointer to the client data, or @NULL if not present.
+        Finds an item whose label matches the given string.
+
+        @param string
+            String to find.
+        @param caseSensitive
+            Whether search is case sensitive (default is not).
+
+        @return The zero-based position of the item, or wxNOT_FOUND if the
+                string was not found.

     */
     */

-    wxClientData * GetClientObject(unsigned int n);
+    virtual int FindString(const wxString& s, bool bCase = false) const;
+
+    //@}
+
+    /// @name Selection
+    //@{

 
     /**
 
     /**

-        Returns the number of items in the control.
-        
-        @sa IsEmpty()
+        Sets the selection to the given item @a n or removes the selection
+        entirely if @a n == @c wxNOT_FOUND.
+
+        Note that this does not cause any command events to be emitted nor does
+        it deselect any other items in the controls which support multiple
+        selections.
+
+        @param n
+            The string position to select, starting from zero.
+
+        @see SetString(), SetStringSelection()

     */
     */

-    unsigned int GetCount();
+    virtual void SetSelection(int n);

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

-        
-        @returns The position of the current selection.
-        
+
+        @return The position of the current selection.
+

         @remarks This method can be used with single selection list boxes only,
         @remarks This method can be used with single selection list boxes only,

-                   you should use wxListBox::GetSelections for the list
-                   boxes with wxLB_MULTIPLE style.
-        
-        @sa SetSelection(), GetStringSelection()
+                 you should use wxListBox::GetSelections() for the list
+                 boxes with wxLB_MULTIPLE style.
+
+        @see SetSelection(), GetStringSelection()

     */
     */

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

 
     /**
 
     /**

-        Returns the label of the item with the given index.
-        
-        @param n
-        The zero-based index.
-        
-        @returns The label of the item or an empty string if the position was
-                   invalid.
+        Selects the item with the specified string in the control. This doesn't
+        cause any command events to be emitted.
+
+        @param string
+            The string to select.
+
+        @return @true if the specified string has been selected, @false if it
+                wasn't found in the control.

     */
     */

-    wxString GetString(unsigned int n);
+    bool SetStringSelection(const wxString& string);

 
     /**
         Returns the label of the selected item or an empty string if no item is
         selected.
 
     /**
         Returns the label of the selected item or an empty string if no item is
         selected.

-        
-        @sa GetSelection()
+
+        @see GetSelection()

     */
     */

-    wxString GetStringSelection();
+    virtual wxString GetStringSelection() const;

 
     /**
 
     /**

-        Returns the array of the labels of all items in the control.
+        This is the same as SetSelection() and exists only because it is
+        slightly more natural for controls which support multiple selection.

     */
     */

-    wxArrayString GetStrings();
+    void Select(int n);
+
+    //@}
+};
+
+
+/**
+    @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
+    wxChoice. It defines an interface which is implemented by all controls
+    which have string subitems each of which may be selected.
+
+    wxItemContainer extends wxItemContainerImmutable interface with methods
+    for adding/removing items.
+
+    It defines the methods for accessing the controls items and although each
+    of the derived classes implements them differently, they still all conform
+    to the same interface.
+
+    The items in a wxItemContainer have (non-empty) string labels and,
+    optionally, client data associated with them. Client data may be of two
+    different kinds: either simple untyped (@c void *) pointers which are
+    simply stored by the control but not used in any way by it, or typed
+    pointers (wxClientData*) which are owned by the control meaning that the
+    typed client data (and only it) will be deleted when an item is deleted
+    using Delete() or the entire control is cleared using Clear(), which also
+    happens when it is destroyed.
+
+    Finally note that in the same control all items must have client data of
+    the same type (typed or untyped), if any. This type is determined by the
+    first call to Append() (the version with client data pointer) or
+    SetClientData().
+
+    Note that this is not a control, it's a mixin interface that classes
+    have to derive from in addition to wxControl or wxWindow. Convenience
+    class wxControlWithItems is provided for this purpose.
+
+    @library{wxcore}
+    @category{ctrl}

 
 

+    @see wxControlWithItems, wxItemContainerImmutable
+*/
+class wxItemContainer : public wxItemContainerImmutable
+{
+public:

     //@{
     //@{

+

     /**
     /**

-        Inserts several items at once into the control. Notice that calling this method
-        is usually much faster than inserting them one by one if you need to insert a
-        lot
-        of items.
-        
+        Appends item into the control.
+

         @param item
         @param item

-        String to add.
-        
-        @param pos
-        Position to insert item before, zero based.
-        
-        @param stringsArray
-        Contains items to insert into the control content
-        
-        @param strings
-        Array of strings of size n.
-        
+            String to add.
+
+        @return The return value is the index of the newly inserted item.
+                Note that this may be different from the last one if the
+                control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
+                style).
+    */
+    int Append(const wxString& item);
+
+    /**
+        Appends item into the control.
+
+        @param item
+            String to add.
+        @param clientData
+            Pointer to client data to associate with the new item.
+
+        @return The return value is the index of the newly inserted item.
+                Note that this may be different from the last one if the
+                control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
+                style).
+    */
+    int Append(const wxString& item, void* clientData);
+
+    /**
+        Appends item into the control.
+
+        @param item
+            String to add.
+        @param clientData
+            Pointer to client data to associate with the new item.
+
+        @return The return value is the index of the newly inserted item.
+                Note that this may be different from the last one if the
+                control is sorted (e.g. has @c wxLB_SORT or @c wxCB_SORT
+                style).
+    */
+    int Append(const wxString& item, wxClientData* clientData);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.
+    */
+    void Append(const wxArrayString& items);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param clientData
+            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);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param clientData
+            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);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+

         @param n
         @param n

-        Number of items in the strings array.
-        
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+    */
+    void Append(unsigned int n, const wxString* items);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.

         @param clientData
         @param clientData

-        Array of client data pointers of size n to associate with the new items.
-        
-        @returns The return value is the index of the newly inserted item. If the
-                   insertion failed for some reason, -1 is returned.
+            Array of client data pointers of size @a n to associate with the
+            new items.

     */
     */

-    int Insert(const wxString& item, unsigned int pos);
-    int Insert(const wxString& item, unsigned int pos,
-               void * clientData);
-    int Insert(const wxString& item, unsigned int pos,
-               wxClientData * clientData);
-    void Insert(const wxArrayString& strings, unsigned int pos);
-    void Insert(const wxArrayString& strings, unsigned int pos);
-    void Insert(unsigned int n, const wxString* strings,
-                unsigned int pos);
-    void Insert(unsigned int n, const wxString* strings,
-                unsigned int pos,
-                void ** clientData);
-    void Insert(unsigned int n, const wxString* strings,
-                unsigned int pos,
-                wxClientData ** clientData);
+    void Append(unsigned int n, const wxString* items,
+                void** clientData);
+
+    /**
+        Appends several items at once into the control.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param clientData
+            Array of client data pointers of size @a n to associate with the
+            new items.
+    */
+    void Append(unsigned int n, const wxString* items,
+                wxClientData** clientData);

     //@}
 
     /**
     //@}
 
     /**

-        Returns @true if the control is empty or @false if it has some items.
-        
-        @sa GetCount()
+        Removes all items from the control.
+        Clear() also deletes the client data of the existing items if it is
+        owned by the control.

     */
     */

-    bool IsEmpty();
+    void Clear();

 
     /**
 
     /**

-        This is the same as SetSelection() and
-        exists only because it is slightly more natural for controls which support
-        multiple selection.
+        Deletes an item from the control.
+
+        The client data associated with the item will be also deleted if it is
+        owned by the control.  Note that it is an error (signalled by an assert
+        failure in debug builds) to remove an item with the index negative or
+        greater or equal than the number of items in the control.
+
+        @param n
+            The zero-based item index.
+
+        @see Clear()

     */
     */

-    void Select(int n);
+    void Delete(unsigned int n);

 
     //@{
 
     //@{

+

     /**
     /**

-        Replaces the current control contents with the given items. Notice that calling
-        this method is much faster than appending the items one by one if you need to
-        append a lot of them.
-        
-        @param item
-        The single item to insert into the control.
-        
-        @param stringsArray
-        Contains items to set as control content.
-        
-        @param strings
-        Raw C++ array of strings. Only used in conjunction with 'n'.
-        
+        Returns a pointer to the client data associated with the given item (if
+        any).  It is an error to call this function for a control which doesn't
+        have untyped client data at all although it is OK to call it even if
+        the given item doesn't have any client data associated with it (but
+        other items do).
+

         @param n
         @param n

-        Number of items passed in 'strings'. Only used in conjunction with 'strings'.
-        
-        @param clientData
-        Client data to associate with the item(s).
-        
-        @returns When the control is sorted (e.g. has wxLB_SORT or wxCB_SORT
-                   style) the return value could be different from
-                   (GetCount() - 1). When setting a single item to the
-                   container, the return value is the index of the newly
-                   added item which may be different from the last one
-                   if the control is sorted (e.g. has wxLB_SORT or
-                   wxCB_SORT style).
-    */
-    int Set(const wxString& item);
-    int Set(const wxString& item, void * clientData);
-    int Set(const wxString& item, wxClientData * clientData);
-    void Set(const wxArrayString& stringsArray);
-    void Set(unsigned int n, const wxString* strings);
-    void Set(unsigned int n, const wxString* strings,
-             void ** clientData);
-    void Set(unsigned int n, const wxString* strings,
-             wxClientData ** clientData);
-    //@}
+            The zero-based position of the item.
+
+        @return A pointer to the client data, or @NULL if not present.
+    */
+    void* GetClientData(unsigned int n) const;

 
     /**
 
     /**

-        Associates the given untyped client data pointer with the given item. Note that
-        it is an error to call this function if any typed client data pointers had been
-        associated with the control items before.
-        
+        Returns a pointer to the client data associated with the given item (if
+        any).  It is an error to call this function for a control which doesn't
+        have typed client data at all although it is OK to call it even if the
+        given item doesn't have any client data associated with it (but other
+        items do).
+

         @param n
         @param n

-        The zero-based item index.
-        
+            The zero-based position of the item.
+
+        @return A pointer to the client data, or @NULL if not present.
+    */
+    wxClientData* GetClientObject(unsigned int n) const;
+
+    /**
+        Associates the given untyped client data pointer with the given item.
+        Note that it is an error to call this function if any typed client data
+        pointers had been associated with the control items before.
+
+        @param n
+            The zero-based item index.

         @param data
         @param data

-        The client data to associate with the item.
+            The client data to associate with the item.

     */
     */

-    void SetClientData(unsigned int n, void * data);
+    void SetClientData(unsigned int n, void* data);

 
     /**
         Associates the given typed client data pointer with the given item: the
 
     /**
         Associates the given typed client data pointer with the given item: the

-        @e data object will be deleted when the item is deleted (either explicitly
-        by using @ref delete() Deletes or implicitly when the
-        control itself is destroyed).
-        
-        Note that it is an error to call this function if any untyped client data
-        pointers had been associated with the control items before.
-        
+        @a data object will be deleted when the item is deleted (either
+        explicitly by using Delete() or implicitly when the control itself is
+        destroyed).  Note that it is an error to call this function if any
+        untyped client data pointers had been associated with the control items
+        before.
+

         @param n
         @param n

-        The zero-based item index.
-        
+            The zero-based item index.

         @param data
         @param data

-        The client data to associate with the item.
+            The client data to associate with the item.
+    */
+    void SetClientObject(unsigned int n, wxClientData* data);
+
+    //@}
+
+    //@{
+
+    /**
+        Inserts item into the control.
+
+        @param item
+            String to add.
+        @param pos
+            Position to insert item before, zero based.
+
+        @return The return value is the index of the newly inserted item.
+                If the insertion failed for some reason, -1 is returned.
+    */
+    int Insert(const wxString& item, unsigned int pos);
+
+    /**
+        Inserts item into the control.
+
+        @param item
+            String to add.
+        @param pos
+            Position to insert item before, zero based.
+        @param clientData
+            Pointer to client data to associate with the new item.
+
+        @return The return value is the index of the newly inserted item.
+                If the insertion failed for some reason, -1 is returned.
+    */
+    int Insert(const wxString& item, unsigned int pos, void* clientData);
+
+    /**
+        Inserts item into the control.
+
+        @param item
+            String to add.
+        @param pos
+            Position to insert item before, zero based.
+        @param clientData
+            Pointer to client data to associate with the new item.
+
+        @return The return value is the index of the newly inserted item.
+                If the insertion failed for some reason, -1 is returned.
+    */
+    int Insert(const wxString& item, unsigned int pos,
+               wxClientData* clientData);
+
+    /**
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param pos
+            Position to insert the items before, zero based.
+    */
+    void Insert(const wxArrayString& items, unsigned int pos);
+
+    /**
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param pos
+            Position to insert the items before, zero based.
+        @param clientData
+            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,
+                void **clientData);
+
+    /**
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param pos
+            Position to insert the items before, zero based.
+        @param clientData
+            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,
+                wxClientData **clientData);
+
+    /**
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param pos
+            Position to insert the items before, zero based.

     */
     */

-    void SetClientObject(unsigned int n, wxClientData * data);
+    void Insert(unsigned int n, const wxString* items,
+                unsigned int pos);

 
     /**
 
     /**

-        Sets the selection to the given item @e n or removes the selection entirely
-        if @e n == @c wxNOT_FOUND.
-        
-        Note that this does not cause any command events to be emitted nor does it
-        deselect any other items in the controls which support multiple selections.
-        
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+

         @param n
         @param n

-        The string position to select, starting from zero.
-        
-        @sa SetString(), SetStringSelection()
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param pos
+            Position to insert the new items before, zero based.
+        @param clientData
+            Array of client data pointers of size @a n to associate with the
+            new items.

     */
     */

-    void SetSelection(int n);
+    void Insert(unsigned int n, const wxString* items,
+                unsigned int pos,
+                void** clientData);

 
     /**
 
     /**

-        Sets the label for the given item.
-        
+        Inserts several items at once into the control.
+
+        Notice that calling this method is usually much faster than inserting
+        them one by one if you need to insert a lot of items.
+

         @param n
         @param n

-        The zero-based item index.
-        
-        @param string
-        The label to set.
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param pos
+            Position to insert the new items before, zero based.
+        @param clientData
+            Array of client data pointers of size @a n to associate with the
+            new items.

     */
     */

-    void SetString(unsigned int n, const wxString& string);
+    void Insert(unsigned int n, const wxString* items,
+                unsigned int pos,
+                wxClientData** clientData);
+    //@}

 
 

+    //@{

     /**
     /**

-        Selects the item with the specified string in the control. This doesn't cause
-        any command events to be emitted.
-        
-        @param string
-        The string to select.
-        
-        @returns @true if the specified string has been selected, @false if it
-                   wasn't found in the control.
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.

     */
     */

-    bool SetStringSelection(const wxString& string);
+    void Set(const wxArrayString& items);
+
+    /**
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param clientData
+            Array of client data pointers of the same size as @a items to
+            associate with the new items.
+    */
+    void Set(const wxArrayString& items, void **clientData);
+
+    /**
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param items
+            Array of strings to insert.
+        @param clientData
+            Array of client data pointers of the same size as @a items to
+            associate with the new items.
+    */
+    void Set(const wxArrayString& items, wxClientData **clientData);
+
+    /**
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+    */
+    void Set(unsigned int n, const wxString* items);
+
+    /**
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param clientData
+            Array of client data pointers of size @a n to associate with the
+            new items.
+    */
+    void Set(unsigned int n, const wxString* items, void** clientData);
+
+    /**
+        Replaces the current control contents with the given items.
+
+        Notice that calling this method is usually much faster than appending
+        them one by one if you need to add a lot of items.
+
+        @param n
+            Number of items in the @a items array.
+        @param items
+            Array of strings of size @a n.
+        @param clientData
+            Array of client data pointers of size @a n to associate with the
+            new items.
+    */
+    void Set(unsigned int n, const wxString* items, wxClientData** clientData);
+    //@}

 };
 };

+
+
+/**
+    @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
+    (wxChoice and wxListBox).
+
+    @library{wxcore}
+    @category{ctrl}
+
+    @see wxItemContainer, wxItemContainerImmutable
+*/
+class wxControlWithItems : public wxControl, public wxItemContainer
+{
+};
+