add handling of wxWrapSizer flags (part of ticket 9468)

[wxWidgets.git] / interface / combobox.h

diff --git a/interface/combobox.h b/interface/combobox.h
index ac98f43f63142df4aa063cdc424a73c98a1e78b3..d70190e385d114de366ec3ef591fadf3f9188cba 100644 (file)
--- a/interface/combobox.h
+++ b/interface/combobox.h
@@ -10,29 +10,28 @@
     @class wxComboBox
     @wxheader{combobox.h}
 
     @class wxComboBox
     @wxheader{combobox.h}
 

-    A combobox is like a combination of an edit control and a listbox. It can be
-    displayed as static list with editable or read-only text field; or a drop-down
-    list with
-    text field; or a drop-down list without a text field.
+    A combobox is like a combination of an edit control and a listbox. It can
+    be displayed as static list with editable or read-only text field; or a
+    drop-down list with text field; or a drop-down list without a text field.

 
 

-    A combobox permits a single selection only. Combobox items are numbered from
-    zero.
+    A combobox permits a single selection only. Combobox items are numbered
+    from zero.

 
 

-    If you need a customized combobox, have a look at wxComboCtrl, wxOwnerDrawnComboBox,
-    wxComboPopup and the ready-to-use wxBitmapComboBox.
+    If you need a customized combobox, have a look at wxComboCtrl,
+    wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.

 
     @beginStyleTable
 
     @beginStyleTable

-    @style{wxCB_SIMPLE}:
+    @style{wxCB_SIMPLE}

            Creates a combobox with a permanently displayed list. Windows only.
            Creates a combobox with a permanently displayed list. Windows only.

-    @style{wxCB_DROPDOWN}:
+    @style{wxCB_DROPDOWN}

            Creates a combobox with a drop-down list.
            Creates a combobox with a drop-down list.

-    @style{wxCB_READONLY}:
-           Same as wxCB_DROPDOWN but only the strings specified as the
-           combobox choices can be selected, it is impossible to select (even
-           from a program) a string which is not in the choices list.
-    @style{wxCB_SORT}:
+    @style{wxCB_READONLY}
+           Same as wxCB_DROPDOWN but only the strings specified as the combobox
+           choices can be selected, it is impossible to select (even from a
+           program) a string which is not in the choices list.
+    @style{wxCB_SORT}

            Sorts the entries in the list alphabetically.
            Sorts the entries in the list alphabetically.

-    @style{wxTE_PROCESS_ENTER}:
+    @style{wxTE_PROCESS_ENTER}

            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
            (otherwise pressing Enter key is either processed internally by the
            control or used for navigation between dialog controls). Windows
            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
            (otherwise pressing Enter key is either processed internally by the
            control or used for navigation between dialog controls). Windows


@@ -40,14 +39,14 @@
     @endStyleTable
 
     @beginEventTable{wxCommandEvent}
     @endStyleTable
 
     @beginEventTable{wxCommandEvent}

-    @event{EVT_COMBOBOX(id, func)}:
+    @event{EVT_COMBOBOX(id, func)}

            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
            Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on

-           the list is selected. Note that calling GetValue returns the new
+           the list is selected. Note that calling GetValue() returns the new

            value of selection.
            value of selection.

-    @event{EVT_TEXT(id, func)}:
+    @event{EVT_TEXT(id, func)}

            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
            changes.
            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
            changes.

-    @event{EVT_TEXT_ENTER(id, func)}:
+    @event{EVT_TEXT_ENTER(id, func)}

            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
            the combobox (notice that the combobox must have been created with
            wxTE_PROCESS_ENTER style to receive this event).
            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
            the combobox (notice that the combobox must have been created with
            wxTE_PROCESS_ENTER style to receive this event).


@@ -55,13 +54,18 @@
 
     @library{wxcore}
     @category{ctrl}
 
     @library{wxcore}
     @category{ctrl}

-    @appearance{combobox.png}
+    <!-- @appearance{combobox.png} -->

 
     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
 */
 
     @see wxListBox, wxTextCtrl, wxChoice, wxCommandEvent
 */

-class wxComboBox : public wxControlWithItems
+class wxComboBox : public wxControl, public wxItemContainer

 {
 public:
 {
 public:

+    /**
+        Default constructor.
+    */
+    wxComboBox();
+

     //@{
     /**
         Constructor, creating and showing a combobox.
     //@{
     /**
         Constructor, creating and showing a combobox.


@@ -75,8 +79,7 @@ public:
         @param pos
             Window position.
         @param size
         @param pos
             Window position.
         @param size

-            Window size. If wxDefaultSize is specified then the window is
-        sized
+            Window size. If wxDefaultSize is specified then the window is sized

             appropriately.
         @param n
             Number of strings with which to initialise the control.
             appropriately.
         @param n
             Number of strings with which to initialise the control.


@@ -89,9 +92,13 @@ public:
         @param name
             Window name.
 
         @param name
             Window name.
 

+        @beginWxPythonOnly
+        The wxComboBox constructor in wxPython reduces the @a n and @a choices
+        arguments are to a single argument, which is a list of strings.
+        @endWxPythonOnly
+

         @see Create(), wxValidator
     */
         @see Create(), wxValidator
     */

-    wxComboBox();

     wxComboBox(wxWindow* parent, wxWindowID id,
                const wxString& value = "",
                const wxPoint& pos = wxDefaultPosition,
     wxComboBox(wxWindow* parent, wxWindowID id,
                const wxString& value = "",
                const wxPoint& pos = wxDefaultPosition,


@@ -116,36 +123,57 @@ public:
     */
     ~wxComboBox();
 
     */
     ~wxComboBox();
 

+    //@{

     /**
     /**

-        Returns @true if the combobox is editable and there is a text selection to copy
-        to the clipboard.
-        Only available on Windows.
+        Creates the combobox for two-step construction. Derived classes should
+        call or replace this function. See wxComboBox() for further details.
+    */
+    bool Create(wxWindow* parent, wxWindowID id,
+                const wxString& value = "",
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                int n, const wxString choices[],
+                long style = 0,
+                const wxValidator& validator = wxDefaultValidator,
+                const wxString& name = "comboBox");
+    bool Create(wxWindow* parent, wxWindowID id,
+                const wxString& value,
+                const wxPoint& pos,
+                const wxSize& size,
+                const wxArrayString& choices,
+                long style = 0,
+                const wxValidator& validator = wxDefaultValidator,
+                const wxString& name = "comboBox");
+    //@}
+
+    /**
+        Returns @true if the combobox is editable and there is a text selection
+        to copy to the clipboard. Only available on Windows.

     */
     bool CanCopy() const;
 
     /**
     */
     bool CanCopy() const;
 
     /**

-        Returns @true if the combobox is editable and there is a text selection to copy
-        to the clipboard.
-        Only available on Windows.
+        Returns @true if the combobox is editable and there is a text selection
+        to copy to the clipboard. Only available on Windows.

     */
     bool CanCut() const;
 
     /**
     */
     bool CanCut() const;
 
     /**

-        Returns @true if the combobox is editable and there is text on the clipboard
-        that can be pasted into the
-        text field. Only available on Windows.
+        Returns @true if the combobox is editable and there is text on the
+        clipboard that can be pasted into the text field. Only available on
+        Windows.

     */
     bool CanPaste() const;
 
     /**
     */
     bool CanPaste() const;
 
     /**

-        Returns @true if the combobox is editable and the last undo can be redone.
-        Only available on Windows.
+        Returns @true if the combobox is editable and the last undo can be
+        redone. Only available on Windows.

     */
     bool CanRedo() const;
 
     /**
     */
     bool CanRedo() const;
 
     /**

-        Returns @true if the combobox is editable and the last edit can be undone.
-        Only available on Windows.
+        Returns @true if the combobox is editable and the last edit can be
+        undone. Only available on Windows.

     */
     bool CanUndo() const;
 
     */
     bool CanUndo() const;
 


@@ -154,47 +182,23 @@ public:
     */
     void Copy();
 
     */
     void Copy();
 

-    //@{
-    /**
-        Creates the combobox for two-step construction. Derived classes
-        should call or replace this function. See wxComboBox()
-        for further details.
-    */
-    bool Create(wxWindow* parent, wxWindowID id,
-                const wxString& value = "",
-                const wxPoint& pos = wxDefaultPosition,
-                const wxSize& size = wxDefaultSize,
-                int n, const wxString choices[],
-                long style = 0,
-                const wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "comboBox");
-    bool Create(wxWindow* parent, wxWindowID id,
-                const wxString& value,
-                const wxPoint& pos,
-                const wxSize& size,
-                const wxArrayString& choices,
-                long style = 0,
-                const wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "comboBox");
-    //@}
-

     /**
         Copies the selected text to the clipboard and removes the selection.
     */
     void Cut();
 
     /**
     /**
         Copies the selected text to the clipboard and removes the selection.
     */
     void Cut();
 
     /**

-        This function does the same things as
-        wxChoice::GetCurrentSelection and
-        returns the item currently selected in the dropdown list if it's open or the
-        same thing as wxControlWithItems::GetSelection otherwise.
+        This function does the same things as wxChoice::GetCurrentSelection()
+        and returns the item currently selected in the dropdown list if it's
+        open or the same thing as wxControlWithItems::GetSelection() otherwise.

     */
     int GetCurrentSelection() const;
 
     /**
         Returns the insertion point for the combobox's text field.
     */
     int GetCurrentSelection() const;
 
     /**
         Returns the insertion point for the combobox's text field.

-        @b Note: Under wxMSW, this function always returns 0 if the combobox
-        doesn't have the focus.
+
+        @note Under wxMSW, this function always returns 0 if the combobox
+              doesn't have the focus.

     */
     long GetInsertionPoint() const;
 
     */
     long GetInsertionPoint() const;
 


@@ -204,9 +208,10 @@ public:
     virtual wxTextPos GetLastPosition() const;
 
     /**
     virtual wxTextPos GetLastPosition() const;
 
     /**

-        This is the same as wxTextCtrl::GetSelection
-        for the text control which is part of the combobox. Notice that this is a
-        different method from wxControlWithItems::GetSelection.
+        This is the same as wxTextCtrl::GetSelection() for the text control
+        which is part of the combobox. Notice that this is a different method
+        from wxControlWithItems::GetSelection().
+

         Currently this method is only implemented in wxMSW and wxGTK.
     */
     void GetSelection(long* from, long* to) const;
         Currently this method is only implemented in wxMSW and wxGTK.
     */
     void GetSelection(long* from, long* to) const;


@@ -237,8 +242,8 @@ public:
     void Remove(long from, long to);
 
     /**
     void Remove(long from, long to);
 
     /**

-        Replaces the text between two positions with the given text, in the combobox
-        text field.
+        Replaces the text between two positions with the given text, in the
+        combobox text field.

 
         @param from
             The first position.
 
         @param from
             The first position.


@@ -269,6 +274,11 @@ public:
             The first position.
         @param to
             The second position.
             The first position.
         @param to
             The second position.

+
+        @beginWxPythonOnly
+        This method is called SetMark() in wxPython, "SetSelection" is kept for
+        wxControlWithItems::SetSelection().
+        @endWxPythonOnly

     */
     void SetSelection(long from, long to);
 
     */
     void SetSelection(long from, long to);
 


@@ -276,7 +286,8 @@ public:
         Sets the text for the combobox text field.
 
         @note For a combobox with @c wxCB_READONLY style the string must be in
         Sets the text for the combobox text field.
 
         @note For a combobox with @c wxCB_READONLY style the string must be in

-              the combobox choices list, otherwise the call to SetValue() is ignored.
+              the combobox choices list, otherwise the call to SetValue() is
+              ignored.

 
         @param text
             The text to set.
 
         @param text
             The text to set.