Add new sample project files.

[wxWidgets.git] / interface / wx / combobox.h

diff --git a/interface/wx/combobox.h b/interface/wx/combobox.h
index ca08253bf4d1f7597115979c564c20861d197656..602916cccf407a78d26253ed3a4944c7ad9c9dd7 100644 (file)
--- a/interface/wx/combobox.h
+++ b/interface/wx/combobox.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxComboBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxComboBox
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 /**
 /////////////////////////////////////////////////////////////////////////////
 
 /**


@@ -13,7 +13,7 @@
 
     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
 
     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.
+    field depending on the platform and presence of wxCB_READONLY style.

 
     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.


@@ -22,21 +22,26 @@
     wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
 
     Please refer to wxTextEntry documentation for the description of methods
     wxOwnerDrawnComboBox, wxComboPopup and the ready-to-use wxBitmapComboBox.
 
     Please refer to wxTextEntry documentation for the description of methods

-    operating with the text entry part of the combobox.
+    operating with the text entry part of the combobox and to wxItemContainer
+    for the methods operating with the list of strings. Notice that at least
+    under MSW wxComboBox doesn't behave correctly if it contains strings
+    differing in case only so portable programs should avoid adding such
+    strings to this control.

 
     @beginStyleTable
     @style{wxCB_SIMPLE}
            Creates a combobox with a permanently displayed list. Windows only.
     @style{wxCB_DROPDOWN}
 
     @beginStyleTable
     @style{wxCB_SIMPLE}
            Creates a combobox with a permanently displayed list. Windows only.
     @style{wxCB_DROPDOWN}

-           Creates a combobox with a drop-down list.
+           Creates a combobox with a drop-down list. MSW and Motif only.

     @style{wxCB_READONLY}
     @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.
+           A combobox with this style behaves like a wxChoice (and may look in
+           the same way as well, although this is platform-dependent), i.e. it
+           allows the user to choose from the list of options but doesn't allow
+           to enter a value not present in the list.

     @style{wxCB_SORT}
            Sorts the entries in the list alphabetically.
     @style{wxTE_PROCESS_ENTER}
     @style{wxCB_SORT}
            Sorts the entries in the list alphabetically.
     @style{wxTE_PROCESS_ENTER}

-           The control will generate the event wxEVT_COMMAND_TEXT_ENTER
+           The control will generate the event @c wxEVT_COMMAND_TEXT_ENTER

            (otherwise pressing Enter key is either processed internally by the
            control or used for navigation between dialog controls). Windows
            only.
            (otherwise pressing Enter key is either processed internally by the
            control or used for navigation between dialog controls). Windows
            only.


@@ -44,16 +49,27 @@
 
     @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_COMBOBOX(id, func)}
 
     @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_COMBOBOX(id, func)}

-           Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
+           Process a @c wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on

            the list is selected. Note that calling GetValue() returns the new
            value of selection.
     @event{EVT_TEXT(id, func)}
            the list is selected. Note that calling GetValue() returns the new
            value of selection.
     @event{EVT_TEXT(id, func)}

-           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text
+           Process a @c wxEVT_COMMAND_TEXT_UPDATED event, when the combobox text

            changes.
     @event{EVT_TEXT_ENTER(id, func)}
            changes.
     @event{EVT_TEXT_ENTER(id, func)}

-           Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
+           Process a @c 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).
            the combobox (notice that the combobox must have been created with
            wxTE_PROCESS_ENTER style to receive this event).

+    @event{EVT_COMBOBOX_DROPDOWN(id, func)}
+           Process a @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
+           when the list box part of the combo box is shown (drops down).
+           Notice that this event is currently only supported by wxMSW and
+           wxGTK with GTK+ 2.10 or later.
+    @event{EVT_COMBOBOX_CLOSEUP(id, func)}
+           Process a @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
+           when the list box of the combo box disappears (closes up). This
+           event is only generated for the same platforms as
+           @c wxEVT_COMMAND_COMBOBOX_DROPDOWN above. Also note that only wxMSW
+           supports adding or deleting items in this event.

     @endEventTable
 
     @library{wxcore}
     @endEventTable
 
     @library{wxcore}


@@ -72,7 +88,6 @@ public:
     */
     wxComboBox();
 
     */
     wxComboBox();
 

-    //@{

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


@@ -82,11 +97,14 @@ public:
             Window identifier. The value wxID_ANY indicates a default value.
         @param value
             Initial selection string. An empty string indicates no selection.
             Window identifier. The value wxID_ANY indicates a default value.
         @param value
             Initial selection string. An empty string indicates no selection.

+            Notice that for the controls with @c wxCB_READONLY style this
+            string must be one of the valid choices if it is not empty.

         @param pos
             Window position.
         @param pos
             Window position.

+            If ::wxDefaultPosition is specified then a default position is chosen.

         @param size
         @param size

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

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


@@ -103,6 +121,10 @@ public:
         arguments are to a single argument, which is a list of strings.
         @endWxPythonOnly
 
         arguments are to a single argument, which is a list of strings.
         @endWxPythonOnly
 

+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly
+

         @see Create(), wxValidator
     */
     wxComboBox(wxWindow* parent, wxWindowID id,
         @see Create(), wxValidator
     */
     wxComboBox(wxWindow* parent, wxWindowID id,


@@ -142,6 +164,10 @@ public:
         arguments are to a single argument, which is a list of strings.
         @endWxPythonOnly
 
         arguments are to a single argument, which is a list of strings.
         @endWxPythonOnly
 

+        @beginWxPerlOnly
+        Use an array reference for the @a choices parameter.
+        @endWxPerlOnly
+

         @see Create(), wxValidator
     */
     wxComboBox(wxWindow* parent, wxWindowID id,
         @see Create(), wxValidator
     */
     wxComboBox(wxWindow* parent, wxWindowID id,


@@ -152,7 +178,6 @@ public:
                long style = 0,
                const wxValidator& validator = wxDefaultValidator,
                const wxString& name = wxComboBoxNameStr);
                long style = 0,
                const wxValidator& validator = wxDefaultValidator,
                const wxString& name = wxComboBoxNameStr);

-    //@}

 
     /**
         Destructor, destroying the combobox.
 
     /**
         Destructor, destroying the combobox.


@@ -212,13 +237,40 @@ public:
     /**
         Sets the text for the combobox text field.
 
     /**
         Sets the text for the combobox text field.
 

+        Notice that this method will generate a @c wxEVT_COMMAND_TEXT_UPDATED
+        event, use wxTextEntry::ChangeValue() if this is undesirable.
+

         @note For a combobox with @c wxCB_READONLY style the string must be in
               the combobox choices list, otherwise the call to SetValue() is
         @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.
+              ignored. This is case insensitive.

 
         @param text
             The text to set.
     */
     virtual void SetValue(const wxString& text);
 
         @param text
             The text to set.
     */
     virtual void SetValue(const wxString& text);

+
+    /**
+        Shows the list box portion of the combo box.
+
+        Currently only implemented in wxMSW and wxGTK.
+
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event.
+
+        @since 2.9.1
+    */
+    virtual void Popup();
+
+    /**
+        Hides the list box portion of the combo box.
+
+        Currently only implemented in wxMSW and wxGTK.
+
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
+
+        @since 2.9.1
+    */
+    virtual void Dismiss();

 };
 
 };