1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxComboCtrl declaration
4 // Author: Jaakko Salli
6 // Created: Apr-30-2006
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows licence
10 ///////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_COMBOCONTROL_H_BASE_
13 #define _WX_COMBOCONTROL_H_BASE_
17 A few words about all the classes defined in this file are probably in
18 order: why do we need extra wxComboCtrl and wxComboPopup classes?
20 This is because a traditional combobox is a combination of a text control
21 (with a button allowing to open the pop down list) with a listbox and
22 wxComboBox class is exactly such control, however we want to also have other
23 combinations - in fact, we want to allow anything at all to be used as pop
24 down list, not just a wxListBox.
26 So we define a base wxComboCtrl which can use any control as pop down
27 list and wxComboBox deriving from it which implements the standard wxWidgets
28 combobox API. wxComboCtrl needs to be told somehow which control to use
29 and this is done by SetPopupControl(). However, we need something more than
30 just a wxControl in this method as, for example, we need to call
31 SetSelection("initial text value") and wxControl doesn't have such method.
32 So we also need a wxComboPopup which is just a very simple interface which
33 must be implemented by a control to be usable as a popup.
35 We couldn't derive wxComboPopup from wxControl as this would make it
36 impossible to have a class deriving from both wxListBx and from it, so
37 instead it is just a mix-in.
45 #include "wx/control.h"
46 #include "wx/renderer.h" // this is needed for wxCONTROL_XXX flags
47 #include "wx/bitmap.h" // wxBitmap used by-value
49 class WXDLLIMPEXP_CORE wxTextCtrl
;
50 class WXDLLEXPORT wxComboPopup
;
53 // New window styles for wxComboCtrlBase
57 // Double-clicking a read-only combo triggers call to popup's OnComboPopup.
58 // In wxOwnerDrawnComboBox, for instance, it cycles item.
59 wxCC_SPECIAL_DCLICK
= 0x0100,
61 // Dropbutton acts like standard push button.
62 wxCC_STD_BUTTON
= 0x0200
66 // wxComboCtrl internal flags
69 // First those that can be passed to Customize.
70 // It is Windows style for all flags to be clear.
72 // Button is preferred outside the border (GTK style)
73 wxCC_BUTTON_OUTSIDE_BORDER
= 0x0001,
74 // Show popup on mouse up instead of mouse down (which is the Windows style)
75 wxCC_POPUP_ON_MOUSE_UP
= 0x0002,
76 // All text is not automatically selected on click
77 wxCC_NO_TEXT_AUTO_SELECT
= 0x0004,
79 // Internal use: signals creation is complete
80 wxCC_IFLAG_CREATED
= 0x0100,
81 // Internal use: really put button outside
82 wxCC_IFLAG_BUTTON_OUTSIDE
= 0x0200,
83 // Internal use: SetTextIndent has been called
84 wxCC_IFLAG_INDENT_SET
= 0x0400,
85 // Internal use: Set wxTAB_TRAVERSAL to parent when popup is dismissed
86 wxCC_IFLAG_PARENT_TAB_TRAVERSAL
= 0x0800,
87 // Internal use: Secondary popup window type should be used (if available).
88 wxCC_IFLAG_USE_ALT_POPUP
= 0x1000
92 // Flags used by PreprocessMouseEvent and HandleButtonMouseEvent
95 wxCC_MF_ON_BUTTON
= 0x0001, // cursor is on dropbutton area
96 wxCC_MF_ON_CLICK_AREA
= 0x0002 // cursor is on dropbutton or other area
97 // that can be clicked to show the popup.
101 // Namespace for wxComboCtrl feature flags
102 struct wxComboCtrlFeatures
106 MovableButton
= 0x0001, // Button can be on either side of control
107 BitmapButton
= 0x0002, // Button may be replaced with bitmap
108 ButtonSpacing
= 0x0004, // Button can have spacing from the edge
110 TextIndent
= 0x0008, // SetTextIndent can be used
111 PaintControl
= 0x0010, // Combo control itself can be custom painted
112 PaintWritable
= 0x0020, // A variable-width area in front of writable
113 // combo control's textctrl can be custom
115 Borderless
= 0x0040, // wxNO_BORDER window style works
117 // There are no feature flags for...
118 // PushButtonBitmapBackground - if its in wxRendererNative, then it should be
119 // not an issue to have it automatically under the bitmap.
121 All
= MovableButton
|BitmapButton
|
122 ButtonSpacing
|TextIndent
|
123 PaintControl
|PaintWritable
|
129 class WXDLLEXPORT wxComboCtrlBase
: public wxControl
131 friend class wxComboPopup
;
134 wxComboCtrlBase() : wxControl() { Init(); }
136 bool Create(wxWindow
*parent
,
138 const wxString
& value
,
142 const wxValidator
& validator
,
143 const wxString
& name
);
145 virtual ~wxComboCtrlBase();
147 // show/hide popup window
148 virtual void ShowPopup();
149 virtual void HidePopup();
151 // Override for totally custom combo action
152 virtual void OnButtonClick();
154 // return true if the popup is currently shown
155 bool IsPopupShown() const { return m_isPopupShown
; }
157 // set interface class instance derived from wxComboPopup
158 // NULL popup can be used to indicate default in a derived class
159 void SetPopupControl( wxComboPopup
* popup
)
161 DoSetPopupControl(popup
);
164 // get interface class instance derived from wxComboPopup
165 wxComboPopup
* GetPopupControl()
167 EnsurePopupControl();
168 return m_popupInterface
;
171 // get the popup window containing the popup control
172 wxWindow
*GetPopupWindow() const { return m_winPopup
; }
174 // Get the text control which is part of the combobox.
175 wxTextCtrl
*GetTextCtrl() const { return m_text
; }
177 // get the dropdown button which is part of the combobox
178 // note: its not necessarily a wxButton or wxBitmapButton
179 wxWindow
*GetButton() const { return m_btn
; }
181 // forward these methods to all subcontrols
182 virtual bool Enable(bool enable
= true);
183 virtual bool Show(bool show
= true);
184 virtual bool SetFont(const wxFont
& font
);
186 // wxTextCtrl methods - for readonly combo they should return
188 virtual wxString
GetValue() const;
189 virtual void SetValue(const wxString
& value
);
192 virtual void Paste();
193 virtual void SetInsertionPoint(long pos
);
194 virtual void SetInsertionPointEnd();
195 virtual long GetInsertionPoint() const;
196 virtual long GetLastPosition() const;
197 virtual void Replace(long from
, long to
, const wxString
& value
);
198 virtual void Remove(long from
, long to
);
199 virtual void SetSelection(long from
, long to
);
202 // This method sets the text without affecting list selection
203 // (ie. wxComboPopup::SetStringValue doesn't get called).
204 void SetText(const wxString
& value
);
206 // This method sets value and also optionally sends EVT_TEXT
207 // (needed by combo popups)
208 void SetValueWithEvent(const wxString
& value
, bool withEvent
= true);
211 // Popup customization methods
214 // Sets minimum width of the popup. If wider than combo control, it will extend to the left.
216 // * Value -1 indicates the default.
217 // * Custom popup may choose to ignore this (wxOwnerDrawnComboBox does not).
218 void SetPopupMinWidth( int width
)
220 m_widthMinPopup
= width
;
223 // Sets preferred maximum height of the popup.
225 // * Value -1 indicates the default.
226 // * Custom popup may choose to ignore this (wxOwnerDrawnComboBox does not).
227 void SetPopupMaxHeight( int height
)
229 m_heightPopup
= height
;
232 // Extends popup size horizontally, relative to the edges of the combo control.
234 // * Popup minimum width may override extLeft (ie. it has higher precedence).
235 // * Values 0 indicate default.
236 // * Custom popup may not take this fully into account (wxOwnerDrawnComboBox takes).
237 void SetPopupExtents( int extLeft
, int extRight
)
240 m_extRight
= extRight
;
243 // Set width, in pixels, of custom paint area in writable combo.
244 // In read-only, used to indicate area that is not covered by the
245 // focus rectangle (which may or may not be drawn, depending on the
247 void SetCustomPaintWidth( int width
);
248 int GetCustomPaintWidth() const { return m_widthCustomPaint
; }
250 // Set side of the control to which the popup will align itself.
251 // Valid values are wxLEFT, wxRIGHT and 0. The default value 0 wmeans
252 // that the side of the button will be used.
253 void SetPopupAnchor( int anchorSide
)
255 m_anchorSide
= anchorSide
;
258 // Set position of dropdown button.
259 // width: button width. <= 0 for default.
260 // height: button height. <= 0 for default.
261 // side: wxLEFT or wxRIGHT, indicates on which side the button will be placed.
262 // spacingX: empty space on sides of the button. Default is 0.
264 // There is no spacingY - the button will be centered vertically.
265 void SetButtonPosition( int width
= -1,
270 // Returns current size of the dropdown button.
271 wxSize
GetButtonSize();
274 // Sets dropbutton to be drawn with custom bitmaps.
276 // bmpNormal: drawn when cursor is not on button
277 // pushButtonBg: Draw push button background below the image.
278 // NOTE! This is usually only properly supported on platforms with appropriate
279 // method in wxRendererNative.
280 // bmpPressed: drawn when button is depressed
281 // bmpHover: drawn when cursor hovers on button. This is ignored on platforms
282 // that do not generally display hover differently.
283 // bmpDisabled: drawn when combobox is disabled.
284 void SetButtonBitmaps( const wxBitmap
& bmpNormal
,
285 bool pushButtonBg
= false,
286 const wxBitmap
& bmpPressed
= wxNullBitmap
,
287 const wxBitmap
& bmpHover
= wxNullBitmap
,
288 const wxBitmap
& bmpDisabled
= wxNullBitmap
);
291 // This will set the space in pixels between left edge of the control and the
292 // text, regardless whether control is read-only (ie. no wxTextCtrl) or not.
293 // Platform-specific default can be set with value-1.
295 // * This method may do nothing on some native implementations.
296 void SetTextIndent( int indent
);
298 // Returns actual indentation in pixels.
299 wxCoord
GetTextIndent() const
304 // Returns area covered by the text field.
305 const wxRect
& GetTextRect() const
310 // Call with enable as true to use a type of popup window that guarantees ability
311 // to focus the popup control, and normal function of common native controls.
312 // This alternative popup window is usually a wxDialog, and as such it's parent
313 // frame will appear as if the focus has been lost from it.
314 void UseAltPopupWindow( bool enable
= true )
316 wxASSERT_MSG( !m_winPopup
,
317 wxT("call this only before SetPopupControl") );
320 m_iFlags
|= wxCC_IFLAG_USE_ALT_POPUP
;
322 m_iFlags
&= ~wxCC_IFLAG_USE_ALT_POPUP
;
326 // Utilies needed by the popups or native implementations
329 // Returns true if given key combination should toggle the popup.
330 // NB: This is a separate from other keyboard handling because:
331 // 1) Replaceability.
332 // 2) Centralized code (otherwise it'd be split up between
333 // wxComboCtrl key handler and wxVListBoxComboPopup's
335 virtual bool IsKeyPopupToggle(const wxKeyEvent
& event
) const = 0;
337 // Prepare background of combo control or an item in a dropdown list
338 // in a way typical on platform. This includes painting the focus/disabled
339 // background and setting the clipping region.
340 // Unless you plan to paint your own focus indicator, you should always call this
341 // in your wxComboPopup::PaintComboControl implementation.
342 // In addition, it sets pen and text colour to what looks good and proper
343 // against the background.
344 // flags: wxRendererNative flags: wxCONTROL_ISSUBMENU: is drawing a list item instead of combo control
345 // wxCONTROL_SELECTED: list item is selected
346 // wxCONTROL_DISABLED: control/item is disabled
347 virtual void PrepareBackground( wxDC
& dc
, const wxRect
& rect
, int flags
) const;
349 // Returns true if focus indicator should be drawn in the control.
350 bool ShouldDrawFocus() const
352 const wxWindow
* curFocus
= FindFocus();
353 return ( !m_isPopupShown
&&
354 (curFocus
== this || (m_btn
&& curFocus
== m_btn
)) &&
355 (m_windowStyle
& wxCB_READONLY
) );
358 // These methods return references to appropriate dropbutton bitmaps
359 const wxBitmap
& GetBitmapNormal() const { return m_bmpNormal
; }
360 const wxBitmap
& GetBitmapPressed() const { return m_bmpPressed
; }
361 const wxBitmap
& GetBitmapHover() const { return m_bmpHover
; }
362 const wxBitmap
& GetBitmapDisabled() const { return m_bmpDisabled
; }
364 // Return internal flags
365 wxUint32
GetInternalFlags() const { return m_iFlags
; }
367 // Return true if Create has finished
368 bool IsCreated() const { return m_iFlags
& wxCC_IFLAG_CREATED
? true : false; }
370 // common code to be called on popup hide/dismiss
371 void OnPopupDismiss();
376 // Override these for customization purposes
379 // called from wxSizeEvent handler
380 virtual void OnResize() = 0;
382 // Return native text identation (for pure text, not textctrl)
383 virtual wxCoord
GetNativeTextIndent() const;
385 // Called in syscolourchanged handler and base create
386 virtual void OnThemeChange();
388 // Creates wxTextCtrl.
389 // extraStyle: Extra style parameters
390 void CreateTextCtrl( int extraStyle
, const wxValidator
& validator
);
392 // Installs standard input handler to combo (and optionally to the textctrl)
393 void InstallInputHandlers();
395 // Draws dropbutton. Using wxRenderer or bitmaps, as appropriate.
396 void DrawButton( wxDC
& dc
, const wxRect
& rect
, bool paintBg
= true );
398 // Call if cursor is on button area or mouse is captured for the button.
399 //bool HandleButtonMouseEvent( wxMouseEvent& event, bool isInside );
400 bool HandleButtonMouseEvent( wxMouseEvent
& event
, int flags
);
402 // returns true if event was consumed or filtered (event type is also set to 0 in this case)
403 bool PreprocessMouseEvent( wxMouseEvent
& event
, int flags
);
406 // This will handle left_down and left_dclick events outside button in a Windows-like manner.
407 // If you need alternate behaviour, it is recommended you manipulate and filter events to it
408 // instead of building your own handling routine (for reference, on wxEVT_LEFT_DOWN it will
409 // toggle popup and on wxEVT_LEFT_DCLICK it will do the same or run the popup's dclick method,
410 // if defined - you should pass events of other types of it for common processing).
411 void HandleNormalMouseEvent( wxMouseEvent
& event
);
413 // Creates popup window, calls interface->Create(), etc
416 // Destroy popup window and all related constructs
419 // override the base class virtuals involved in geometry calculations
420 virtual wxSize
DoGetBestSize() const;
422 // NULL popup can be used to indicate default in a derived class
423 virtual void DoSetPopupControl(wxComboPopup
* popup
);
425 // ensures there is atleast the default popup
426 void EnsurePopupControl();
428 // Recalculates button and textctrl areas. Called when size or button setup change.
429 // btnWidth: default/calculated width of the dropbutton. 0 means unchanged,
431 void CalculateAreas( int btnWidth
= 0 );
433 // Standard textctrl positioning routine. Just give it platform-dependant
434 // textctrl coordinate adjustment.
435 void PositionTextCtrl( int textCtrlXAdjust
, int textCtrlYAdjust
);
438 void OnSizeEvent( wxSizeEvent
& event
);
439 void OnFocusEvent(wxFocusEvent
& event
);
440 void OnTextCtrlEvent(wxCommandEvent
& event
);
441 void OnSysColourChanged(wxSysColourChangedEvent
& event
);
442 void OnKeyEvent(wxKeyEvent
& event
);
444 // Set customization flags (directs how wxComboCtrlBase helpers behave)
445 void Customize( wxUint32 flags
) { m_iFlags
|= flags
; }
447 // Dispatches size event and refreshes
448 void RecalcAndRefresh();
451 virtual void DoSetToolTip( wxToolTip
*tip
);
454 // This is used when m_text is hidden (readonly).
455 wxString m_valueString
;
457 // the text control and button we show all the time
461 // wxPopupWindow or similar containing the window managed by the interface.
462 wxWindow
* m_winPopup
;
464 // the popup control/panel
468 wxComboPopup
* m_popupInterface
;
470 // this is input etc. handler for the text control
471 wxEvtHandler
* m_textEvtHandler
;
473 // this is for the top level window
474 wxEvtHandler
* m_toplevEvtHandler
;
476 // this is for the control in popup
477 wxEvtHandler
* m_popupExtraHandler
;
479 // this is for the popup window
480 wxEvtHandler
* m_popupWinEvtHandler
;
482 // used to prevent immediate re-popupping incase closed popup
483 // by clicking on the combo control (needed because of inconsistent
484 // transient implementation across platforms).
485 wxLongLong m_timeCanAcceptClick
;
487 // how much popup should expand to the left/right of the control
491 // minimum popup width
492 wxCoord m_widthMinPopup
;
494 // preferred popup height
495 wxCoord m_heightPopup
;
497 // how much of writable combo is custom-paint by callback?
498 // also used to indicate area that is not covered by "blue"
499 // selection indicator.
500 wxCoord m_widthCustomPaint
;
502 // absolute text indentation, in pixels
505 // side on which the popup is aligned
508 // Width of the "fake" border
509 wxCoord m_widthCustomBorder
;
511 // The button and textctrl click/paint areas
515 // current button state (uses renderer flags)
524 // last default button width
527 // custom dropbutton bitmaps
528 wxBitmap m_bmpNormal
;
529 wxBitmap m_bmpPressed
;
531 wxBitmap m_bmpDisabled
;
533 // area used by the button
536 // platform-dependant customization and other flags
539 // draw blank button background under bitmap?
540 bool m_blankButtonBg
;
542 // is the popup window currenty shown?
548 wxByte m_ignoreEvtText
; // Number of next EVT_TEXTs to ignore
550 // Is popup window wxPopupTransientWindow, wxPopupWindow or wxDialog?
551 wxByte m_popupWinType
;
553 DECLARE_EVENT_TABLE()
555 DECLARE_ABSTRACT_CLASS(wxComboCtrlBase
)
559 // ----------------------------------------------------------------------------
560 // wxComboPopup is the interface which must be implemented by a control to be
561 // used as a popup by wxComboCtrl
562 // ----------------------------------------------------------------------------
565 // wxComboPopup internal flags
568 wxCP_IFLAG_CREATED
= 0x0001 // Set by wxComboCtrlBase after Create is called
572 class WXDLLEXPORT wxComboPopup
574 friend class wxComboCtrlBase
;
578 m_combo
= (wxComboCtrlBase
*) NULL
;
582 // This is called immediately after construction finishes. m_combo member
583 // variable has been initialized before the call.
584 // NOTE: It is not in constructor so the derived class doesn't need to redefine
585 // a default constructor of its own.
586 virtual void Init() { };
588 virtual ~wxComboPopup();
590 // Create the popup child control.
591 // Return true for success.
592 virtual bool Create(wxWindow
* parent
) = 0;
594 // We must have an associated control which is subclassed by the combobox.
595 virtual wxWindow
*GetControl() = 0;
597 // Called immediately after the popup is shown
598 virtual void OnPopup();
600 // Called when popup is dismissed
601 virtual void OnDismiss();
603 // Called just prior to displaying popup.
604 // Default implementation does nothing.
605 virtual void SetStringValue( const wxString
& value
);
607 // Gets displayed string representation of the value.
608 virtual wxString
GetStringValue() const = 0;
610 // This is called to custom paint in the combo control itself (ie. not the popup).
611 // Default implementation draws value as string.
612 virtual void PaintComboControl( wxDC
& dc
, const wxRect
& rect
);
614 // Receives key events from the parent wxComboCtrl.
615 // Events not handled should be skipped, as usual.
616 virtual void OnComboKeyEvent( wxKeyEvent
& event
);
618 // Implement if you need to support special action when user
619 // double-clicks on the parent wxComboCtrl.
620 virtual void OnComboDoubleClick();
622 // Return final size of popup. Called on every popup, just prior to OnShow.
623 // minWidth = preferred minimum width for window
624 // prefHeight = preferred height. Only applies if > 0,
625 // maxHeight = max height for window, as limited by screen size
626 // and should only be rounded down, if necessary.
627 virtual wxSize
GetAdjustedSize( int minWidth
, int prefHeight
, int maxHeight
);
629 // Return true if you want delay call to Create until the popup is shown
630 // for the first time. It is more efficient, but note that it is often
631 // more convenient to have the control created immediately.
632 // Default returns false.
633 virtual bool LazyCreate();
642 // Returns true if Create has been called.
643 bool IsCreated() const
645 return (m_iFlags
& wxCP_IFLAG_CREATED
) ? true : false;
648 // Default PaintComboControl behaviour
649 static void DefaultPaintComboControl( wxComboCtrlBase
* combo
,
651 const wxRect
& rect
);
654 wxComboCtrlBase
* m_combo
;
658 // Called in wxComboCtrlBase::SetPopupControl
659 void InitBase(wxComboCtrlBase
*combo
)
666 // ----------------------------------------------------------------------------
667 // include the platform-dependent header defining the real class
668 // ----------------------------------------------------------------------------
670 #if defined(__WXUNIVERSAL__)
671 // No native universal (but it must still be first in the list)
672 #elif defined(__WXMSW__)
673 #include "wx/msw/combo.h"
676 // Any ports may need generic as an alternative
677 #include "wx/generic/combo.h"
679 #endif // wxUSE_COMBOCTRL
682 // _WX_COMBOCONTROL_H_BASE_