X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/a1d5aa9361ecbbe6715ef29d8c69ddaa8a00d4ba..ff8af61ce07803bd86cafea25a06915dfed2ce36:/interface/wx/combo.h

diff --git a/interface/wx/combo.h b/interface/wx/combo.h
index 38ef1f9342..2238961d63 100644
--- a/interface/wx/combo.h
+++ b/interface/wx/combo.h
@@ -3,9 +3,23 @@
 // Purpose:     interface of wxComboCtrl and wxComboPopup
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
+//
+// New window styles for wxComboCtrlBase
+//
+enum
+{
+    // Double-clicking a read-only combo triggers call to popup's OnComboPopup.
+    // In wxOwnerDrawnComboBox, for instance, it cycles item.
+    wxCC_SPECIAL_DCLICK             = 0x0100,
+
+    // Dropbutton acts like standard push button.
+    wxCC_STD_BUTTON                 = 0x0200
+};
+
+
 /**
     @class wxComboPopup
 
@@ -36,11 +50,42 @@ public:
     */
     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.
@@ -86,7 +131,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
@@ -254,13 +299,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:
@@ -285,7 +330,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.
@@ -300,26 +345,28 @@ struct wxComboCtrlFeatures
 
     @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_COMBOX_DROPDOWN(id, func)}
-           Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated
+    @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_COMBOX_CLOSEUP(id, func)}
-           Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated
+    @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}
+    @library{wxcore}
     @category{ctrl}
-    @appearance{comboctrl.png}
+    @appearance{comboctrl}
 
     @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
          wxCommandEvent
 */
-class wxComboCtrl : public wxControl
+class wxComboCtrl : public wxControl,
+                    public wxTextEntry
 {
 public:
     /**
@@ -387,12 +434,52 @@ public:
     */
     virtual void Cut();
 
+    /**
+        Dismisses the popup window.
+
+        Notice that calling this function will generate a
+        @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
+
+        @since 2.9.2
+    */
+    virtual void Dismiss();
+
+
     /**
         Enables or disables popup animation, if any, depending on the value of
         the argument.
     */
     void EnablePopupAnimation(bool enable = true);
 
+    
+    /**
+       Returns true if given key combination should toggle the popup.
+    */
+    virtual bool IsKeyPopupToggle(const wxKeyEvent& event) const;
+
+
+    /**
+       Prepare background of combo control or an item in a dropdown list in a
+       way typical on platform. This includes painting the focus/disabled
+       background and setting the clipping region.
+
+       Unless you plan to paint your own focus indicator, you should always
+       call this in your wxComboPopup::PaintComboControl implementation.  In
+       addition, it sets pen and text colour to what looks good and proper
+       against the background.
+
+       flags: wxRendererNative flags:
+              wxCONTROL_ISSUBMENU: is drawing a list item instead of combo control
+              wxCONTROL_SELECTED: list item is selected
+              wxCONTROL_DISABLED: control/item is disabled
+    */
+    virtual void PrepareBackground( wxDC& dc, const wxRect& rect, int flags ) const;
+
+    /**
+       Returns true if focus indicator should be drawn in the control.
+    */
+    bool ShouldDrawFocus() const;
+
     /**
         Returns disabled button bitmap that has been set with
         SetButtonBitmaps().
@@ -447,6 +534,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.
 
@@ -513,7 +609,9 @@ public:
 
         @param generateEvent
             Set this to @true in order to generate
-            wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
+            @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event.
+
+        @deprecated Use Dismiss() instead.
     */
     virtual void HidePopup(bool generateEvent=false);
 
@@ -550,6 +648,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.
@@ -619,6 +727,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 bool SetHint(const wxString& hint);
+
     /**
         Sets the insertion point in the text field.
 
@@ -712,6 +832,22 @@ 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
@@ -731,13 +867,15 @@ public:
     virtual void SetValue(const wxString& value);
 
     /**
-        Same as SetValue(), but also sends wxCommandEvent of type
-        wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
-    */
-    void SetValueWithEvent(const wxString& value, bool withEvent = true);
+       Changes value of the control as if user had done it by selecting an
+       item from a combo box drop-down list.
+     */
+    void SetValueByUser(const wxString& value);
 
     /**
         Show the popup.
+
+        @deprecated Use Popup() instead.
     */
     virtual void ShowPopup();
 
@@ -773,7 +911,7 @@ protected:
     /**
         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.
+        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