simplify code so it always returns the same object

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

diff --git a/interface/wx/combobox.h b/interface/wx/combobox.h
index 2054fbd949aec4771fb0407626410aa3d9df529d..aaf7894177e84390dfd9096d78106ca7d2e7dda4 100644 (file)
--- a/interface/wx/combobox.h
+++ b/interface/wx/combobox.h
@@ -3,15 +3,17 @@
 // 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

 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxComboBox
 
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxComboBox
 

-    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 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.


@@ -19,19 +21,27 @@
     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.
 

+    Please refer to wxTextEntry documentation for the description of methods
+    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.


@@ -39,25 +49,38 @@
 
     @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}
     @category{ctrl}
     @endEventTable
 
     @library{wxcore}
     @category{ctrl}

-    @appearance{combobox.png}
+    @appearance{combobox}

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

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

 {
 public:
     /**
 {
 public:
     /**


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

-    //@{

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


@@ -75,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


@@ -91,10 +116,9 @@ 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
+        @beginWxPerlOnly
+        Not supported by wxPerl.
+        @endWxPerlOnly

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


@@ -130,10 +154,9 @@ 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
+        @beginWxPerlOnly
+        Use an array reference for the @a choices parameter.
+        @endWxPerlOnly

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


@@ -145,7 +168,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.


@@ -176,47 +198,8 @@ public:
     //@}
 
     /**
     //@}
 
     /**

-        Returns @true if the combobox is editable and there is a text selection
-        to copy to the clipboard. Only available on Windows.
-    */
-    virtual 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.
-    */
-    virtual 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.
-    */
-    virtual bool CanPaste() const;
-
-    /**
-        Returns @true if the combobox is editable and the last undo can be
-        redone. Only available on Windows.
-    */
-    virtual bool CanRedo() const;
-
-    /**
-        Returns @true if the combobox is editable and the last edit can be
-        undone. Only available on Windows.
-    */
-    virtual bool CanUndo() const;
+        Returns the item being selected right now.

 
 

-    /**
-        Copies the selected text to the clipboard.
-    */
-    virtual void Copy();
-
-    /**
-        Copies the selected text to the clipboard and removes the selection.
-    */
-    virtual 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.


@@ -224,7 +207,7 @@ public:
     virtual int GetCurrentSelection() const;
 
     /**
     virtual int GetCurrentSelection() const;
 
     /**

-        Returns the insertion point for the combobox's text field.
+        Same as wxTextEntry::GetInsertionPoint().

 
         @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.


@@ -232,100 +215,100 @@ public:
     virtual long GetInsertionPoint() const;
 
     /**
     virtual long GetInsertionPoint() const;
 
     /**

-        Returns the last position in the combobox text field.
-    */
-    virtual long GetLastPosition() const;
+        IsEmpty() is not available in this class.

 
 

-    /**
-        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 method is documented here only to notice that it can't be used
+        with this class because of the ambiguity between the methods with the
+        same name inherited from wxItemContainer and wxTextEntry base classes.

 
 

-        Currently this method is only implemented in wxMSW and wxGTK.
-    */
-    virtual void GetSelection(long* from, long* to) const;
+        Because of this, any attempt to call it results in a compilation error
+        and you should use either IsListEmpty() or IsTextEmpty() depending on
+        what exactly do you want to test.
+     */
+    bool IsEmpty() const;

 
     /**
 
     /**

-        Returns the current value in the combobox text field.
-    */
-    virtual wxString GetValue() const;
+        Returns true if the list of combobox choices is empty.
+
+        Use this method instead of (not available in this class) IsEmpty() to
+        test if the list of items is empty.
+
+        @since 2.9.3
+     */
+    bool IsListEmpty() const;

 
     /**
 
     /**

-        Pastes text from the clipboard to the text field.
-    */
-    virtual void Paste();
+        Returns true if the text of the combobox is empty.
+
+        Use this method instead of (not available in this class) IsEmpty() to
+        test if the text currently entered into the combobox is empty.
+
+        @since 2.9.3
+     */
+    bool IsTextEmpty() const;

 
     /**
 
     /**

-        Redoes the last undo in the text field. Windows only.
+        Same as wxTextEntry::SetSelection().

     */
     */

-    virtual void Redo();
+    virtual void SetSelection(long from, long to);

 
     /**
 
     /**

-        Removes the text between the two positions in the combobox text field.
+        Sets the text for the combobox text field.

 
 

-        @param from
-            The first position.
-        @param to
-            The last position.
-    */
-    virtual void Remove(long from, long to);
+        Notice that this method will generate a @c wxEVT_COMMAND_TEXT_UPDATED
+        event, use wxTextEntry::ChangeValue() if this is undesirable.

 
 

-    /**
-        Replaces the text between two positions with the given text, in 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. This is case insensitive.

 
 

-        @param from
-            The first position.
-        @param to
-            The second position.

         @param text
         @param text

-            The text to insert.
+            The text to set.

     */
     */

-    virtual void Replace(long from, long to, const wxString& text);
+    virtual void SetValue(const wxString& text);

 
     /**
 
     /**

-        Sets the insertion point in the combobox text field.
+        Shows the list box portion of the combo box.

 
 

-        @param pos
-            The new insertion point.
-    */
-    virtual void SetInsertionPoint(long pos);
+        Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.

 
 

-    /**
-        Sets the insertion point at the end of the combobox text field.
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event except under wxOSX where
+        generation of this event is not supported at all.
+
+        @since 2.9.1

     */
     */

-    virtual void SetInsertionPointEnd();
+    virtual void Popup();

 
     /**
 
     /**

-        Selects the text between the two positions, in the combobox text field.
+        Hides the list box portion of the combo box.

 
 

-        @param from
-            The first position.
-        @param to
-            The second position.
+        Currently this method is implemented in wxMSW, wxGTK and wxOSX/Cocoa.

 
 

-        @beginWxPythonOnly
-        This method is called SetMark() in wxPython, "SetSelection" is kept for
-        wxControlWithItems::SetSelection().
-        @endWxPythonOnly
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event except under wxOSX where
+        generation of this event is not supported at all.
+
+        @since 2.9.1

     */
     */

-    virtual void SetSelection(long from, long to);
+    virtual void Dismiss();

 
 

-    /**
-        Sets the text for the combobox text field.
+    virtual int GetSelection() const;
+    virtual void GetSelection(long *from, long *to) const;
+    virtual void SetSelection(int n);
+    virtual int FindString(const wxString& s, bool bCase = false) const;
+    virtual wxString GetString(unsigned int n) const;
+    virtual wxString GetStringSelection() const;

 
 

-        @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.
+    /**
+        Changes the text of the specified combobox item.

 
 

-        @param text
-            The text to set.
-    */
-    virtual void SetValue(const wxString& text);
+        Notice that if the item is the currently selected one, i.e. if its text
+        is displayed in the text part of the combobox, then the text is also
+        replaced with the new @a text.
+     */
+    virtual void SetString(unsigned int n, const wxString& text);

 
 

-    /**
-        Undoes the last edit in the text field. Windows only.
-    */
-    virtual void Undo();
+    virtual unsigned int GetCount() const;

 };
 
 };