Fix missing documentation for several GDI functions.

[wxWidgets.git] / include / wx / combo.h

diff --git a/include/wx/combo.h b/include/wx/combo.h
index 1093a26f5d8c7654fb6a7c37e3b538ad44af1a5b..76bf25f53276dc221cad2efcd72ba838a7ce81ec 100644 (file)
--- a/include/wx/combo.h
+++ b/include/wx/combo.h
@@ -45,6 +45,7 @@
 #include "wx/control.h"
 #include "wx/renderer.h" // this is needed for wxCONTROL_XXX flags
 #include "wx/bitmap.h" // wxBitmap used by-value
 #include "wx/control.h"
 #include "wx/renderer.h" // this is needed for wxCONTROL_XXX flags
 #include "wx/bitmap.h" // wxBitmap used by-value

+#include "wx/textentry.h"

 
 class WXDLLIMPEXP_FWD_CORE wxTextCtrl;
 class WXDLLIMPEXP_FWD_CORE wxComboPopup;
 
 class WXDLLIMPEXP_FWD_CORE wxTextCtrl;
 class WXDLLIMPEXP_FWD_CORE wxComboPopup;


@@ -86,7 +87,7 @@ enum
     wxCC_IFLAG_CREATED              = 0x0100,
     // Internal use: really put button outside
     wxCC_IFLAG_BUTTON_OUTSIDE       = 0x0200,
     wxCC_IFLAG_CREATED              = 0x0100,
     // Internal use: really put button outside
     wxCC_IFLAG_BUTTON_OUTSIDE       = 0x0200,

-    // Internal use: SetMargins has been succesfully called
+    // Internal use: SetMargins has been successfully called

     wxCC_IFLAG_LEFT_MARGIN_SET      = 0x0400,
     // Internal use: Set wxTAB_TRAVERSAL to parent when popup is dismissed
     wxCC_IFLAG_PARENT_TAB_TRAVERSAL = 0x0800,
     wxCC_IFLAG_LEFT_MARGIN_SET      = 0x0400,
     // Internal use: Set wxTAB_TRAVERSAL to parent when popup is dismissed
     wxCC_IFLAG_PARENT_TAB_TRAVERSAL = 0x0800,


@@ -95,7 +96,8 @@ enum
     // Internal use: Skip popup animation.
     wxCC_IFLAG_DISABLE_POPUP_ANIM   = 0x2000,
     // Internal use: Drop-button is a bitmap button or has non-default size
     // Internal use: Skip popup animation.
     wxCC_IFLAG_DISABLE_POPUP_ANIM   = 0x2000,
     // Internal use: Drop-button is a bitmap button or has non-default size

-    // (but can still be on either side of the control).
+    // (but can still be on either side of the control), regardless whether
+    // specified by the platform or the application.

     wxCC_IFLAG_HAS_NONSTANDARD_BUTTON   = 0x4000
 };
 
     wxCC_IFLAG_HAS_NONSTANDARD_BUTTON   = 0x4000
 };
 


@@ -138,12 +140,14 @@ struct wxComboCtrlFeatures
 };
 
 
 };
 
 

-class WXDLLIMPEXP_CORE wxComboCtrlBase : public wxControl
+class WXDLLIMPEXP_CORE wxComboCtrlBase : public wxControl,
+                                         public wxTextEntry

 {
     friend class wxComboPopup;
 {
     friend class wxComboPopup;

+    friend class wxComboPopupEvtHandler;

 public:
     // ctors and such
 public:
     // ctors and such

-    wxComboCtrlBase() : wxControl() { Init(); }
+    wxComboCtrlBase() : wxControl(), wxTextEntry() { Init(); }

 
     bool Create(wxWindow *parent,
                 wxWindowID id,
 
     bool Create(wxWindow *parent,
                 wxWindowID id,


@@ -156,9 +160,19 @@ public:
 
     virtual ~wxComboCtrlBase();
 
 
     virtual ~wxComboCtrlBase();
 

-    // show/hide popup window
+    // Show/hide popup window (wxComboBox-compatible methods)
+    virtual void Popup();
+    virtual void Dismiss()
+    {
+        HidePopup(true);
+    }
+
+    // Show/hide popup window.
+    // TODO: Maybe deprecate in favor of Popup()/Dismiss().
+    //       However, these functions are still called internally
+    //       so it is not straightforward.

     virtual void ShowPopup();
     virtual void ShowPopup();

-    virtual void HidePopup();
+    virtual void HidePopup(bool generateEvent=false);

 
     // Override for totally custom combo action
     virtual void OnButtonClick();
 
     // Override for totally custom combo action
     virtual void OnButtonClick();


@@ -194,26 +208,56 @@ public:
     virtual bool Enable(bool enable = true);
     virtual bool Show(bool show = true);
     virtual bool SetFont(const wxFont& font);
     virtual bool Enable(bool enable = true);
     virtual bool Show(bool show = true);
     virtual bool SetFont(const wxFont& font);

-#if wxUSE_VALIDATORS
-    virtual void SetValidator(const wxValidator &validator);
-    virtual wxValidator *GetValidator();
-#endif // wxUSE_VALIDATORS
-
-    // wxTextCtrl methods - for readonly combo they should return
-    // without errors.
-    virtual wxString GetValue() const;
-    virtual void SetValue(const wxString& value);
+
+    //
+    // wxTextEntry methods
+    //
+    // NB: We basically need to override all of them because there is
+    //     no guarantee how platform-specific wxTextEntry is implemented.
+    //
+    virtual void SetValue(const wxString& value)
+        { wxTextEntryBase::SetValue(value); }
+    virtual void ChangeValue(const wxString& value)
+        { wxTextEntryBase::ChangeValue(value); }
+
+    virtual void WriteText(const wxString& text);
+    virtual void AppendText(const wxString& text)
+        { wxTextEntryBase::AppendText(text); }
+
+    virtual wxString GetValue() const
+        { return wxTextEntryBase::GetValue(); }
+
+    virtual wxString GetRange(long from, long to) const
+        { return wxTextEntryBase::GetRange(from, to); }
+
+    // Replace() and DoSetValue() need to be fully re-implemented since
+    // EventSuppressor utility class does not work with the way
+    // wxComboCtrl is implemented.
+    virtual void Replace(long from, long to, const wxString& value);
+
+    virtual void Remove(long from, long to);
+

     virtual void Copy();
     virtual void Cut();
     virtual void Paste();
     virtual void Copy();
     virtual void Cut();
     virtual void Paste();

+
+    virtual void Undo();
+    virtual void Redo();
+    virtual bool CanUndo() const;
+    virtual bool CanRedo() const;
+

     virtual void SetInsertionPoint(long pos);
     virtual void SetInsertionPoint(long pos);

-    virtual void SetInsertionPointEnd();

     virtual long GetInsertionPoint() const;
     virtual long GetLastPosition() const;
     virtual long GetInsertionPoint() const;
     virtual long GetLastPosition() const;

-    virtual void Replace(long from, long to, const wxString& value);
-    virtual void Remove(long from, long to);
+

     virtual void SetSelection(long from, long to);
     virtual void SetSelection(long from, long to);

-    virtual void Undo();
+    virtual void GetSelection(long *from, long *to) const;
+
+    virtual bool IsEditable() const;
+    virtual void SetEditable(bool editable);
+
+    virtual bool SetHint(const wxString& hint);
+    virtual wxString GetHint() const;

 
     // This method sets the text without affecting list selection
     // (ie. wxComboPopup::SetStringValue doesn't get called).
 
     // This method sets the text without affecting list selection
     // (ie. wxComboPopup::SetStringValue doesn't get called).


@@ -221,7 +265,13 @@ public:
 
     // This method sets value and also optionally sends EVT_TEXT
     // (needed by combo popups)
 
     // This method sets value and also optionally sends EVT_TEXT
     // (needed by combo popups)

-    void SetValueWithEvent(const wxString& value, bool withEvent = true);
+    wxDEPRECATED( 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. Needs to be public so that
+    // derived popup classes can call it.
+    void SetValueByUser(const wxString& value);

 
     //
     // Popup customization methods
 
     //
     // Popup customization methods


@@ -303,7 +353,7 @@ public:
                            const wxBitmap& bmpHover = wxNullBitmap,
                            const wxBitmap& bmpDisabled = wxNullBitmap );
 
                            const wxBitmap& bmpHover = wxNullBitmap,
                            const wxBitmap& bmpDisabled = wxNullBitmap );
 

-#if WXWIN_COMPATIBILITY_2_6
+#if WXWIN_COMPATIBILITY_2_8

     //
     // This will set the space in pixels between left edge of the control and the
     // text, regardless whether control is read-only (ie. no wxTextCtrl) or not.
     //
     // This will set the space in pixels between left edge of the control and the
     // text, regardless whether control is read-only (ie. no wxTextCtrl) or not.


@@ -385,16 +435,9 @@ public:
     const wxBitmap& GetBitmapHover() const { return m_bmpHover; }
     const wxBitmap& GetBitmapDisabled() const { return m_bmpDisabled; }
 
     const wxBitmap& GetBitmapHover() const { return m_bmpHover; }
     const wxBitmap& GetBitmapDisabled() const { return m_bmpDisabled; }
 

-    // Margins functions mirrored from TextEntryBase
-    // (wxComboCtrl does not inherit from wxTextEntry, but may embed a
-    // wxTextCtrl, so we need these). Also note that these functions
-    // have replaced SetTextIndent() in wxWidgets 2.9.1 and later.
-    bool SetMargins(const wxPoint& pt)
-        { return DoSetMargins(pt); }
-    bool SetMargins(wxCoord left, wxCoord top = -1)
-        { return DoSetMargins(wxPoint(left, top)); }
-    wxPoint GetMargins() const
-        { return DoGetMargins(); }
+    // Set custom style flags for embedded wxTextCtrl. Usually must be used
+    // with two-step creation, before Create() call.
+    void SetTextCtrlStyle( int style );

 
     // Return internal flags
     wxUint32 GetInternalFlags() const { return m_iFlags; }
 
     // Return internal flags
     wxUint32 GetInternalFlags() const { return m_iFlags; }


@@ -402,8 +445,11 @@ public:
     // Return true if Create has finished
     bool IsCreated() const { return m_iFlags & wxCC_IFLAG_CREATED ? true : false; }
 
     // Return true if Create has finished
     bool IsCreated() const { return m_iFlags & wxCC_IFLAG_CREATED ? true : false; }
 

+    // Need to override to return text area background colour
+    wxColour GetBackgroundColour() const;
+

     // common code to be called on popup hide/dismiss
     // common code to be called on popup hide/dismiss

-    void OnPopupDismiss();
+    void OnPopupDismiss(bool generateEvent);

 
     // PopupShown states
     enum
 
     // PopupShown states
     enum


@@ -427,6 +473,16 @@ public:
 
 protected:
 
 
 protected:
 

+    // Returns true if hint text should be drawn in the control
+    bool ShouldUseHintText(int flags = 0) const
+    {
+        return ( !m_text &&
+                 !(flags & wxCONTROL_ISSUBMENU) &&
+                 !m_valueString.length() &&
+                 m_hintText.length() &&
+                 !ShouldDrawFocus() );
+    }
+

     //
     // Override these for customization purposes
     //
     //
     // Override these for customization purposes
     //


@@ -443,7 +499,11 @@ protected:
 
     // Creates wxTextCtrl.
     //   extraStyle: Extra style parameters
 
     // Creates wxTextCtrl.
     //   extraStyle: Extra style parameters

-    void CreateTextCtrl( int extraStyle, const wxValidator& validator );
+    void CreateTextCtrl( int extraStyle );
+
+    // Called when text was changed programmatically
+    // (e.g. from WriteText())
+    void OnSetValue(const wxString& value);

 
     // Installs standard input handler to combo (and optionally to the textctrl)
     void InstallInputHandlers();
 
     // Installs standard input handler to combo (and optionally to the textctrl)
     void InstallInputHandlers();


@@ -481,7 +541,14 @@ protected:
     void DestroyPopup();
 
     // override the base class virtuals involved in geometry calculations
     void DestroyPopup();
 
     // override the base class virtuals involved in geometry calculations

+    // The common version only sets a default width, so the derived classes
+    // should override it and set the height and change the width as needed.

     virtual wxSize DoGetBestSize() const;
     virtual wxSize DoGetBestSize() const;

+    virtual wxSize DoGetSizeFromTextSize(int xlen, int ylen = -1) const;
+
+    // also set the embedded wxTextCtrl colours
+    virtual bool SetForegroundColour(const wxColour& colour);
+    virtual bool SetBackgroundColour(const wxColour& colour);

 
     // NULL popup can be used to indicate default in a derived class
     virtual void DoSetPopupControl(wxComboPopup* popup);
 
     // NULL popup can be used to indicate default in a derived class
     virtual void DoSetPopupControl(wxComboPopup* popup);


@@ -496,7 +563,8 @@ protected:
 
     // Standard textctrl positioning routine. Just give it platform-dependant
     // textctrl coordinate adjustment.
 
     // Standard textctrl positioning routine. Just give it platform-dependant
     // textctrl coordinate adjustment.

-    virtual void PositionTextCtrl( int textCtrlXAdjust, int textCtrlYAdjust );
+    virtual void PositionTextCtrl( int textCtrlXAdjust = 0,
+                                   int textCtrlYAdjust = 0);

 
     // event handlers
     void OnSizeEvent( wxSizeEvent& event );
 
     // event handlers
     void OnSizeEvent( wxSizeEvent& event );


@@ -505,6 +573,7 @@ protected:
     void OnTextCtrlEvent(wxCommandEvent& event);
     void OnSysColourChanged(wxSysColourChangedEvent& event);
     void OnKeyEvent(wxKeyEvent& event);
     void OnTextCtrlEvent(wxCommandEvent& event);
     void OnSysColourChanged(wxSysColourChangedEvent& event);
     void OnKeyEvent(wxKeyEvent& event);

+    void OnCharEvent(wxKeyEvent& event);

 
     // Set customization flags (directs how wxComboCtrlBase helpers behave)
     void Customize( wxUint32 flags ) { m_iFlags |= flags; }
 
     // Set customization flags (directs how wxComboCtrlBase helpers behave)
     void Customize( wxUint32 flags ) { m_iFlags |= flags; }


@@ -533,6 +602,11 @@ protected:
     virtual void DoSetToolTip( wxToolTip *tip );
 #endif
 
     virtual void DoSetToolTip( wxToolTip *tip );
 #endif
 

+    // protected wxTextEntry methods
+    virtual void DoSetValue(const wxString& value, int flags);
+    virtual wxString DoGetValue() const;
+    virtual wxWindow *GetEditableWindow() { return this; }
+

     // margins functions
     virtual bool DoSetMargins(const wxPoint& pt);
     virtual wxPoint DoGetMargins() const;
     // margins functions
     virtual bool DoSetMargins(const wxPoint& pt);
     virtual wxPoint DoGetMargins() const;


@@ -540,6 +614,9 @@ protected:
     // This is used when m_text is hidden (readonly).
     wxString                m_valueString;
 
     // This is used when m_text is hidden (readonly).
     wxString                m_valueString;
 

+    // This is used when control is unfocused and m_valueString is empty
+    wxString                m_hintText;
+

     // the text control and button we show all the time
     wxTextCtrl*             m_text;
     wxWindow*               m_btn;
     // the text control and button we show all the time
     wxTextCtrl*             m_text;
     wxWindow*               m_btn;


@@ -560,7 +637,7 @@ protected:
     wxEvtHandler*           m_toplevEvtHandler;
 
     // this is for the control in popup
     wxEvtHandler*           m_toplevEvtHandler;
 
     // this is for the control in popup

-    wxEvtHandler*           m_popupExtraHandler;
+    wxEvtHandler*           m_popupEvtHandler;

 
     // this is for the popup window
     wxEvtHandler*           m_popupWinEvtHandler;
 
     // this is for the popup window
     wxEvtHandler*           m_popupWinEvtHandler;


@@ -568,7 +645,7 @@ protected:
     // main (ie. topmost) window of a composite control (default = this)
     wxWindow*               m_mainCtrlWnd;
 
     // main (ie. topmost) window of a composite control (default = this)
     wxWindow*               m_mainCtrlWnd;
 

-    // used to prevent immediate re-popupping incase closed popup
+    // used to prevent immediate re-popupping in case closed popup

     // by clicking on the combo control (needed because of inconsistent
     // transient implementation across platforms).
     wxLongLong              m_timeCanAcceptClick;
     // by clicking on the combo control (needed because of inconsistent
     // transient implementation across platforms).
     wxLongLong              m_timeCanAcceptClick;


@@ -601,6 +678,9 @@ protected:
     wxRect                  m_tcArea;
     wxRect                  m_btnArea;
 
     wxRect                  m_tcArea;
     wxRect                  m_btnArea;
 

+    // Colour of the text area, in case m_text is NULL
+    wxColour                m_tcBgCol;
+

     // current button state (uses renderer flags)
     int                     m_btnState;
 
     // current button state (uses renderer flags)
     int                     m_btnState;
 


@@ -625,6 +705,9 @@ protected:
     // platform-dependant customization and other flags
     wxUint32                m_iFlags;
 
     // platform-dependant customization and other flags
     wxUint32                m_iFlags;
 

+    // custom style for m_text
+    int                     m_textCtrlStyle;
+

     // draw blank button background under bitmap?
     bool                    m_blankButtonBg;
 
     // draw blank button background under bitmap?
     bool                    m_blankButtonBg;
 


@@ -634,6 +717,9 @@ protected:
     // should the focus be reset to the textctrl in idle time?
     bool                    m_resetFocus;
 
     // should the focus be reset to the textctrl in idle time?
     bool                    m_resetFocus;
 

+    // is the text-area background colour overridden?
+    bool                    m_hasTcBgCol;
+

 private:
     void Init();
 
 private:
     void Init();
 


@@ -685,6 +771,13 @@ public:
     // Return true for success.
     virtual bool Create(wxWindow* parent) = 0;
 
     // Return true for success.
     virtual bool Create(wxWindow* parent) = 0;
 

+    // Calls Destroy() for the popup control (i.e. one returned by
+    // GetControl()) and makes sure that 'this' is deleted at the end.
+    // Default implementation works for both cases where popup control
+    // class is multiple inherited or created on heap as a separate
+    // object.
+    virtual void DestroyPopup();
+

     // We must have an associated control which is subclassed by the combobox.
     virtual wxWindow *GetControl() = 0;
 
     // We must have an associated control which is subclassed by the combobox.
     virtual wxWindow *GetControl() = 0;
 


@@ -701,14 +794,25 @@ public:
     // Gets displayed string representation of the value.
     virtual wxString GetStringValue() const = 0;
 
     // Gets displayed string representation of the value.
     virtual wxString GetStringValue() const = 0;
 

+    // Called to check if the popup - when an item container - actually
+    // has matching item. Case-sensitivity checking etc. is up to the
+    // implementation. If the found item matched the string, but is
+    // different, it should be written back to pItem. Default implementation
+    // always return true and does not alter trueItem.
+    virtual bool FindItem(const wxString& item, wxString* trueItem=NULL);
+

     // This is called to custom paint in the combo control itself (ie. not the popup).
     // Default implementation draws value as string.
     virtual void PaintComboControl( wxDC& dc, const wxRect& rect );
 
     // This is called to custom paint in the combo control itself (ie. not the popup).
     // Default implementation draws value as string.
     virtual void PaintComboControl( wxDC& dc, const wxRect& rect );
 

-    // Receives key events from the parent wxComboCtrl.
+    // Receives wxEVT_KEY_DOWN key events from the parent wxComboCtrl.

     // Events not handled should be skipped, as usual.
     virtual void OnComboKeyEvent( wxKeyEvent& event );
 
     // Events not handled should be skipped, as usual.
     virtual void OnComboKeyEvent( wxKeyEvent& event );
 

+    // Receives wxEVT_CHAR key events from the parent wxComboCtrl.
+    // Events not handled should be skipped, as usual.
+    virtual void OnComboCharEvent( wxKeyEvent& event );
+

     // Implement if you need to support special action when user
     // double-clicks on the parent wxComboCtrl.
     virtual void OnComboDoubleClick();
     // Implement if you need to support special action when user
     // double-clicks on the parent wxComboCtrl.
     virtual void OnComboDoubleClick();