X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..685a9fa61d56606cadb99a0a34773ecfb9865fa8:/interface/wx/combo.h

diff --git a/interface/wx/combo.h b/interface/wx/combo.h
index 353daaf8f5..268f247573 100644
--- a/interface/wx/combo.h
+++ b/interface/wx/combo.h
@@ -3,12 +3,11 @@
 // Purpose:     interface of wxComboCtrl and wxComboPopup
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     @class wxComboPopup
-    @wxheader{combo.h}
 
     In order to use a custom popup with wxComboCtrl, an interface class must be
     derived from wxComboPopup.
@@ -35,13 +34,44 @@ public:
 
         @return @true if the call succeeded, @false otherwise.
     */
-    virtual bool Create(wxWindow* parent);
+    virtual bool Create(wxWindow* parent) = 0;
+
+    /**
+        You only need to implement this member function if you create
+        your popup class in non-standard way. The default implementation can
+        handle both multiple-inherited popup control (as seen in wxComboCtrl
+        samples) and one allocated separately in heap.
+
+        If you do completely re-implement this function, make sure it calls
+        Destroy() for the popup control and also deletes @a this object
+        (usually as the last thing).
+    */
+    virtual void DestroyPopup();
 
     /**
         Utility function that hides the popup.
     */
     void Dismiss();
 
+    /**
+        Implement to customize matching of value string to an item container
+        entry.
+        
+        @param item
+            String entered, usually by user or from SetValue() call.
+            
+        @param trueItem
+            When item matches an entry, but the entry's string representation
+            is not exactly the same (case mismatch, for example), then the
+            true item string should be written back to here, if it is not
+            a NULL pointer.
+
+        @remarks
+            Default implementation always return true and does not alter
+            trueItem.
+    */
+    virtual bool FindItem(const wxString& item, wxString* trueItem=NULL);
+
     /**
         The derived class may implement this to return adjusted size for the
         popup control, according to the variables given.
@@ -50,24 +80,29 @@ public:
             Preferred minimum width.
         @param prefHeight
             Preferred height. May be -1 to indicate no preference.
-        @param maxWidth
+        @param maxHeight
             Max height for window, as limited by screen size.
 
         @remarks This function is called each time popup is about to be shown.
     */
     virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight);
 
+    /**
+        Returns pointer to the associated parent wxComboCtrl.
+    */
+    wxComboCtrl* GetComboCtrl() const;
+
     /**
         The derived class must implement this to return pointer to the
         associated control created in Create().
     */
-    virtual wxWindow* GetControl();
+    virtual wxWindow* GetControl() = 0;
 
     /**
         The derived class must implement this to return string representation
         of the value.
     */
-    virtual wxString GetStringValue() const;
+    virtual wxString GetStringValue() const = 0;
 
     /**
         The derived class must implement this to initialize its internal
@@ -82,7 +117,7 @@ public:
         Useful in conjunction with LazyCreate().
     */
     bool IsCreated() const;
-
+    
     /**
         The derived class may implement this to return @true if it wants to
         delay call to Create() until the popup is shown for the first time. It
@@ -132,11 +167,12 @@ public:
     */
     virtual void SetStringValue(const wxString& value);
 
+protected:
     /**
-        Parent wxComboCtrl. This is parameter has been prepared before Init()
-        is called.
+        Parent wxComboCtrl. This member variable is prepared automatically
+        before Init() is called.
     */
-    wxComboCtrl m_combo;
+    wxComboCtrl*    m_combo;
 };
 
 
@@ -154,7 +190,7 @@ struct wxComboCtrlFeatures
         BitmapButton    = 0x0002, ///< Button may be replaced with bitmap.
         ButtonSpacing   = 0x0004, ///< Button can have spacing from the edge
                                   ///< of the control.
-        TextIndent      = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used.
+        TextIndent      = 0x0008, ///< wxComboCtrl::SetMargins() can be used.
         PaintControl    = 0x0010, ///< Combo control itself can be custom painted.
         PaintWritable   = 0x0020, ///< A variable-width area in front of writable
                                   ///< combo control's textctrl can be custom
@@ -170,7 +206,6 @@ struct wxComboCtrlFeatures
 
 /**
     @class wxComboCtrl
-    @wxheader{combo.h}
 
     A combo control is a generic combobox that allows totally custom popup. In
     addition it has other customization features. For instance, position and
@@ -250,13 +285,13 @@ struct wxComboCtrlFeatures
         int m_value; // current item index
 
     private:
-        DECLARE_EVENT_TABLE()
+        wxDECLARE_EVENT_TABLE();
     };
 
-    BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
+    wxBEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
         EVT_MOTION(wxListViewComboPopup::OnMouseMove)
         EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
-    END_EVENT_TABLE()
+    wxEND_EVENT_TABLE()
     @endcode
 
     Here's how you would create and populate it in a dialog constructor:
@@ -266,6 +301,7 @@ struct wxComboCtrlFeatures
 
     wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
 
+    // It is important to call SetPopupControl() as soon as possible
     comboCtrl->SetPopupControl(popupCtrl);
 
     // Populate using wxListView methods
@@ -280,7 +316,7 @@ struct wxComboCtrlFeatures
     @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.
@@ -293,22 +329,30 @@ struct wxComboCtrlFeatures
            Drop button will behave more like a standard push button.
     @endStyleTable
 
-    @beginEventTable{wxCommandEvent}
+    @beginEventEmissionTable{wxCommandEvent}
     @event{EVT_TEXT(id, func)}
-           Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes.
+           Process a @c wxEVT_COMMAND_TEXT_UPDATED event, when the text 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 combo control.
+    @event{EVT_COMBOBOX_DROPDOWN(id, func)}
+           Process a @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
+           when the popup window is shown (drops down).
+    @event{EVT_COMBOBOX_CLOSEUP(id, func)}
+           Process a @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
+           when the popup window of the combo control disappears (closes up).
+           You should avoid adding or deleting items in this event.
     @endEventTable
 
     @library{wxbase}
     @category{ctrl}
-    <!-- @appearance{comboctrl.png} -->
+    @appearance{comboctrl.png}
 
     @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
          wxCommandEvent
 */
-class wxComboCtrl : public wxControl
+class wxComboCtrl : public wxControl,
+                    public wxTextEntry
 {
 public:
     /**
@@ -327,9 +371,10 @@ public:
             Initial selection string. An empty string indicates no selection.
         @param pos
             Window position.
+            If ::wxDefaultPosition is specified then a default position is chosen.
         @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 style
             Window style. See wxComboCtrl.
         @param validator
@@ -339,32 +384,19 @@ public:
 
         @see Create(), wxValidator
     */
-    wxComboCtrl(wxWindow* parent, wxWindowID id,
-                const wxString& value = "",
+    wxComboCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,
+                const wxString& value = wxEmptyString,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "comboCtrl");
+                const wxString& name = wxComboBoxNameStr);
 
     /**
         Destructor, destroying the combo control.
     */
     virtual ~wxComboCtrl();
 
-    /**
-        This member function is not normally called in application code.
-        Instead, it can be implemented in a derived class to create a custom
-        popup animation.
-
-        The parameters are the same as those for DoShowPopup().
-
-        @return @true if animation finishes before the function returns,
-                @false otherwise. In the latter case you need to manually call
-                DoShowPopup() after the animation ends.
-    */
-    virtual bool AnimateShow(const wxRect& rect, int flags);
-
     /**
         Copies the selected text to the clipboard.
     */
@@ -375,13 +407,13 @@ public:
         should call or replace this function. See wxComboCtrl() for further
         details.
     */
-    bool Create(wxWindow* parent, wxWindowID id,
-                const wxString& value = "",
+    bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
+                const wxString& value = wxEmptyString,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
-                const wxString& name = "comboCtrl");
+                const wxString& name = wxComboBoxNameStr);
 
     /**
         Copies the selected text to the clipboard and removes the selection.
@@ -389,36 +421,15 @@ public:
     virtual void Cut();
 
     /**
-        This member function is not normally called in application code.
-        Instead, it can be implemented in a derived class to return default
-        wxComboPopup, incase @a popup is @NULL.
+        Dismisses the popup window.
 
-        @note If you have implemented OnButtonClick() to do something else than
-              show the popup, then DoSetPopupControl() must always set @a popup
-              to @NULL.
-    */
-    void DoSetPopupControl(wxComboPopup* popup);
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
 
-    /**
-        This member function is not normally called in application code.
-        Instead, it must be called in a derived class to make sure popup is
-        properly shown after a popup animation has finished (but only if
-        AnimateShow() did not finish the animation within its function scope).
-
-        @param rect
-            Position to show the popup window at, in screen coordinates.
-        @param flags
-            Combination of any of the following:
-            @beginTable
-            @row2col{wxComboCtrl::ShowAbove,
-                     Popup is shown above the control instead of below.}
-            @row2col{wxComboCtrl::CanDeferShow,
-                     Showing the popup can be deferred to happen sometime after
-                     ShowPopup() has finished. In this case, AnimateShow() must
-                     return false.}
-            @endTable
+        @since 2.9.2
     */
-    virtual void DoShowPopup(const wxRect& rect, int flags);
+    virtual void Dismiss();
+
 
     /**
         Enables or disables popup animation, if any, depending on the value of
@@ -432,7 +443,7 @@ public:
 
         @return A reference to the disabled state bitmap.
     */
-    const wxBitmap GetBitmapDisabled() const;
+    const wxBitmap& GetBitmapDisabled() const;
 
     /**
         Returns button mouse hover bitmap that has been set with
@@ -440,7 +451,7 @@ public:
 
         @return A reference to the mouse hover state bitmap.
     */
-    const wxBitmap GetBitmapHover() const;
+    const wxBitmap& GetBitmapHover() const;
 
     /**
         Returns default button bitmap that has been set with
@@ -448,7 +459,7 @@ public:
 
         @return A reference to the normal state bitmap.
     */
-    const wxBitmap GetBitmapNormal() const;
+    const wxBitmap& GetBitmapNormal() const;
 
     /**
         Returns depressed button bitmap that has been set with
@@ -456,7 +467,7 @@ public:
 
         @return A reference to the depressed state bitmap.
     */
-    const wxBitmap GetBitmapPressed() const;
+    const wxBitmap& GetBitmapPressed() const;
 
     /**
         Returns current size of the dropdown button.
@@ -480,6 +491,15 @@ public:
     */
     static int GetFeatures();
 
+    /**
+        Returns the current hint string.
+
+        See SetHint() for more information about hints.
+
+        @since 2.9.1
+    */
+    virtual wxString GetHint() const;
+
     /**
         Returns the insertion point for the combo control's text field.
 
@@ -493,6 +513,19 @@ public:
     */
     virtual long GetLastPosition() const;
 
+    /**
+        Returns the margins used by the control. The @c x field of the returned
+        point is the horizontal margin and the @c y field is the vertical one.
+
+        @remarks If given margin cannot be accurately determined, its value
+                will be set to -1.
+
+        @see SetMargins()
+
+        @since 2.9.1
+    */
+    wxPoint GetMargins() const;
+
     /**
         Returns current popup interface that has been set with
         SetPopupControl().
@@ -511,6 +544,8 @@ public:
 
     /**
         Returns actual indentation in pixels.
+
+        @deprecated Use GetMargins() instead.
     */
     wxCoord GetTextIndent() const;
 
@@ -518,7 +553,7 @@ public:
         Returns area covered by the text field (includes everything except
         borders and the dropdown button).
     */
-    const wxRect GetTextRect() const;
+    const wxRect& GetTextRect() const;
 
     /**
         Returns text representation of the current value. For writable combo
@@ -528,8 +563,14 @@ public:
 
     /**
         Dismisses the popup window.
+
+        @param generateEvent
+            Set this to @true in order to generate
+            @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
+
+        @deprecated Use Dismiss() instead.
     */
-    virtual void HidePopup();
+    virtual void HidePopup(bool generateEvent=false);
 
     /**
         Returns @true if the popup is currently shown
@@ -564,6 +605,16 @@ public:
     */
     virtual void Paste();
 
+    /**
+        Shows the popup portion of the combo control.
+
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event.
+
+        @since 2.9.2
+    */
+    virtual void Popup();
+
     /**
         Removes the text between the two positions in the combo control text
         field.
@@ -586,7 +637,7 @@ public:
         @param text
             The text to insert.
     */
-    virtual void Replace(long from, long to, const wxString& value);
+    virtual void Replace(long from, long to, const wxString& text);
 
     /**
         Sets custom dropdown button graphics.
@@ -633,6 +684,18 @@ public:
     */
     void SetCustomPaintWidth(int width);
 
+    /**
+        Sets a hint shown in an empty unfocused combo control.
+
+        Notice that hints are known as <em>cue banners</em> under MSW or
+        <em>placeholder strings</em> under OS X.
+
+        @see wxTextEntry::SetHint()
+
+        @since 2.9.1
+    */
+    virtual void SetHint(const wxString& hint);
+
     /**
         Sets the insertion point in the text field.
 
@@ -646,6 +709,21 @@ public:
     */
     virtual void SetInsertionPointEnd();
 
+    //@{
+    /**
+        Attempts to set the control margins. When margins are given as wxPoint,
+        x indicates the left and y the top margin. Use -1 to indicate that
+        an existing value should be used.
+
+        @return
+            @true if setting of all requested margins was successful.
+
+        @since 2.9.1
+    */
+    bool SetMargins(const wxPoint& pt);
+    bool SetMargins(wxCoord left, wxCoord top = -1);
+    //@}
+
     /**
         Set side of the control to which the popup will align itself. Valid
         values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that
@@ -711,10 +789,28 @@ public:
     */
     void SetText(const wxString& value);
 
+    /**
+        Set a custom window style for the embedded wxTextCtrl. Usually you
+        will need to use this during two-step creation, just before Create().
+        For example:
+
+        @code
+            wxComboCtrl* comboCtrl = new wxComboCtrl();
+
+            // Let's make the text right-aligned
+            comboCtrl->SetTextCtrlStyle(wxTE_RIGHT);
+
+            comboCtrl->Create(parent, wxID_ANY, wxEmptyString);
+        @endcode
+    */
+    void SetTextCtrlStyle( int style );
+
     /**
         This will set the space in pixels between left edge of the control and
         the text, regardless whether control is read-only or not. Value -1 can
         be given to indicate platform default.
+
+        @deprecated Use SetMargins() instead.
     */
     void SetTextIndent(int indent);
 
@@ -729,12 +825,14 @@ public:
 
     /**
         Same as SetValue(), but also sends wxCommandEvent of type
-        wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
+        @c wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
     */
     void SetValueWithEvent(const wxString& value, bool withEvent = true);
 
     /**
         Show the popup.
+
+        @deprecated Use Popup() instead.
     */
     virtual void ShowPopup();
 
@@ -751,5 +849,52 @@ public:
         will appear as if the focus has been lost from it.
     */
     void UseAltPopupWindow(bool enable = true);
+
+protected:
+
+    /**
+        This member function is not normally called in application code.
+        Instead, it can be implemented in a derived class to create a custom
+        popup animation.
+
+        The parameters are the same as those for DoShowPopup().
+
+        @return @true if animation finishes before the function returns,
+                @false otherwise. In the latter case you need to manually call
+                DoShowPopup() after the animation ends.
+    */
+    virtual bool AnimateShow(const wxRect& rect, int flags);
+
+    /**
+        This member function is not normally called in application code.
+        Instead, it can be implemented in a derived class to return default
+        wxComboPopup, in case @a popup is @NULL.
+
+        @note If you have implemented OnButtonClick() to do something else than
+              show the popup, then DoSetPopupControl() must always set @a popup
+              to @NULL.
+    */
+    virtual void DoSetPopupControl(wxComboPopup* popup);
+
+    /**
+        This member function is not normally called in application code.
+        Instead, it must be called in a derived class to make sure popup is
+        properly shown after a popup animation has finished (but only if
+        AnimateShow() did not finish the animation within its function scope).
+
+        @param rect
+            Position to show the popup window at, in screen coordinates.
+        @param flags
+            Combination of any of the following:
+            @beginTable
+            @row2col{wxComboCtrl::ShowAbove,
+                     Popup is shown above the control instead of below.}
+            @row2col{wxComboCtrl::CanDeferShow,
+                     Showing the popup can be deferred to happen sometime after
+                     ShowPopup() has finished. In this case, AnimateShow() must
+                     return false.}
+            @endTable
+    */
+    virtual void DoShowPopup(const wxRect& rect, int flags);
 };