1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxComboControl 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 wxComboControl 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 wxComboControl which can use any control as pop down
27 list and wxComboBox deriving from it which implements the standard wxWidgets
28 combobox API. wxComboControl 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.
43 #if wxUSE_COMBOCONTROL
46 #include "wx/textctrl.h"
47 #include "wx/button.h"
48 #include "wx/combobox.h"
49 #include "wx/renderer.h" // this is needed for wxCONTROL_XXX flags
52 class WXDLLEXPORT wxComboPopup
;
55 // New window styles for wxComboControlBase
59 // Double-clicking a read-only combo triggers call to popup's OnComboPopup.
60 // In wxOwnerDrawnComboBox, for instance, it cycles item.
61 wxCC_SPECIAL_DCLICK
= 0x0100,
63 // Use keyboard behaviour alternate to platform default:
64 // Up an down keys will show popup instead of cycling value.
65 wxCC_ALT_KEYS
= 0x0200,
67 // Dropbutton acts like standard push button.
68 wxCC_STD_BUTTON
= 0x0400
72 // wxComboControl internal flags
75 // First those that can be passed to Customize.
76 // It is Windows style for all flags to be clear.
78 // Button is preferred outside the border (GTK style)
79 wxCC_BUTTON_OUTSIDE_BORDER
= 0x0001,
80 // Show popup on mouse up instead of mouse down (which is the Windows style)
81 wxCC_POPUP_ON_MOUSE_UP
= 0x0002,
82 // All text is not automatically selected on click
83 wxCC_NO_TEXT_AUTO_SELECT
= 0x0004,
85 // Internal use: signals creation is complete
86 wxCC_IFLAG_CREATED
= 0x0100,
87 // Internal use: really put button outside
88 wxCC_IFLAG_BUTTON_OUTSIDE
= 0x0200,
89 // Internal use: SetTextIndent has been called
90 wxCC_IFLAG_INDENT_SET
= 0x0400,
91 // Internal use: Set wxTAB_TRAVERSAL to parent when popup is dismissed
92 wxCC_IFLAG_PARENT_TAB_TRAVERSAL
= 0x0800
96 // Flags used by PreprocessMouseEvent and HandleButtonMouseEvent
99 wxCC_MF_ON_BUTTON
= 0x0001 // cursor is on dropbutton area
103 // Namespace for wxComboControl feature flags
104 struct wxComboControlFeatures
108 MovableButton
= 0x0001, // Button can be on either side of control
109 BitmapButton
= 0x0002, // Button may be replaced with bitmap
110 ButtonSpacing
= 0x0004, // Button can have spacing from the edge
112 TextIndent
= 0x0008, // SetTextIndent can be used
113 PaintControl
= 0x0010, // Combo control itself can be custom painted
114 PaintWritable
= 0x0020, // A variable-width area in front of writable
115 // combo control's textctrl can be custom
117 Borderless
= 0x0040, // wxNO_BORDER window style works
119 // There are no feature flags for...
120 // PushButtonBitmapBackground - if its in wxRendererNative, then it should be
121 // not an issue to have it automatically under the bitmap.
123 All
= MovableButton
|BitmapButton
|
124 ButtonSpacing
|TextIndent
|
125 PaintControl
|PaintWritable
|
131 class WXDLLEXPORT wxComboControlBase
: public wxControl
133 friend class wxComboPopup
;
136 wxComboControlBase() : wxControl() { Init(); }
138 bool Create(wxWindow
*parent
,
140 const wxString
& value
,
144 const wxValidator
& validator
,
145 const wxString
& name
);
147 virtual ~wxComboControlBase();
149 // show/hide popup window
150 virtual void ShowPopup();
151 virtual void HidePopup();
153 // Override for totally custom combo action
154 virtual void OnButtonClick();
156 // return true if the popup is currently shown
157 bool IsPopupShown() const { return m_isPopupShown
; }
159 // set interface class instance derived from wxComboPopup
160 void SetPopupControl( wxComboPopup
* iface
);
162 // get interface class instance derived from wxComboPopup
163 wxComboPopup
* GetPopup() const { return m_popupInterface
; }
165 // get the popup window containing the popup control
166 wxWindow
*GetPopupWindow() const { return m_winPopup
; }
168 // get the popup control/panel in window
169 wxWindow
*GetPopupControl() const { return m_popup
; }
171 // Get the text control which is part of the combobox.
172 wxTextCtrl
*GetTextCtrl() const { return m_text
; }
174 // get the dropdown button which is part of the combobox
175 // note: its not necessarily a wxButton or wxBitmapButton
176 wxWindow
*GetButton() const { return m_btn
; }
178 // forward these methods to all subcontrols
179 virtual bool Enable(bool enable
= true);
180 virtual bool Show(bool show
= true);
181 virtual bool SetFont(const wxFont
& font
);
183 virtual void DoSetToolTip( wxToolTip
*tip
);
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
);
203 // Popup customization methods
206 // Sets minimum width of the popup. If wider than combo control, it will extend to the left.
208 // * Value -1 indicates the default.
209 // * Custom popup may choose to ignore this (wxOwnerDrawnComboBox does not).
210 void SetPopupMinWidth( int width
)
212 m_widthMinPopup
= width
;
215 // Sets preferred maximum height of the popup.
217 // * Value -1 indicates the default.
218 // * Custom popup may choose to ignore this (wxOwnerDrawnComboBox does not).
219 void SetPopupMaxHeight( int height
)
221 m_heightPopup
= height
;
224 // Extends popup size horizontally, relative to the edges of the combo control.
226 // * Popup minimum width may override extLeft (ie. it has higher precedence).
227 // * Values 0 indicate default.
228 // * Custom popup may not take this fully into account (wxOwnerDrawnComboBox takes).
229 void SetPopupExtents( int extLeft
, int extRight
)
232 m_extRight
= extRight
;
235 // Set width, in pixels, of custom paint area in writable combo.
236 // In read-only, used to indicate area that is not covered by the
237 // focus rectangle (which may or may not be drawn, depending on the
239 void SetCustomPaintWidth( int width
);
240 int GetCustomPaintWidth() const { return m_widthCustomPaint
; }
242 // Set side of the control to which the popup will align itself.
243 // Valid values are wxLEFT, wxRIGHT and 0. The default value 0 wmeans
244 // that the side of the button will be used.
245 void SetPopupAnchor( int anchorSide
)
247 m_anchorSide
= anchorSide
;
250 // Set position of dropdown button.
251 // width: 0 > for specific custom width, negative to adjust to smaller than default
252 // height: 0 > for specific custom height, negative to adjust to smaller than default
253 // side: wxLEFT or wxRIGHT, indicates on which side the button will be placed.
254 // spacingX: empty space on sides of the button. Default is 0.
256 // There is no spacingY - the button will be centered vertically.
257 void SetButtonPosition( int width
= 0, int height
= 0, int side
= wxRIGHT
,
258 int spacingX
= 0 /*, int spacingY = 0*/ );
262 // Sets dropbutton to be drawn with custom bitmaps.
264 // bmpNormal: drawn when cursor is not on button
265 // blankButtonBg: Draw blank button background below the image.
266 // NOTE! This is only properly supported on platforms with appropriate
267 // method in wxRendererNative.
268 // bmpPressed: drawn when button is depressed
269 // bmpHover: drawn when cursor hovers on button. This is ignored on platforms
270 // that do not generally display hover differently.
271 // bmpDisabled: drawn when combobox is disabled.
272 void SetButtonBitmaps( const wxBitmap
& bmpNormal
,
273 bool blankButtonBg
= false,
274 const wxBitmap
& bmpPressed
= wxNullBitmap
,
275 const wxBitmap
& bmpHover
= wxNullBitmap
,
276 const wxBitmap
& bmpDisabled
= wxNullBitmap
);
279 // This will set the space in pixels between left edge of the control and the
280 // text, regardless whether control is read-only (ie. no wxTextCtrl) or not.
281 // Platform-specific default can be set with value-1.
283 // * This method may do nothing on some native implementations.
284 void SetTextIndent( int indent
);
286 // Returns actual indentation in pixels.
287 wxCoord
GetTextIndent() const
293 // Utilies needed by the popups or native implementations
296 // Draws focus background (on combo control) in a way typical on platform.
297 // Unless you plan to paint your own focus indicator, you should always call this
298 // in your wxComboPopup::PaintComboControl implementation.
299 // In addition, it sets pen and text colour to what looks good and proper
300 // against the background.
301 // flags: wxRendererNative flags: wxCONTROL_ISSUBMENU: is drawing a list item instead of combo control
302 // wxCONTROL_SELECTED: list item is selected
303 // wxCONTROL_DISABLED: control/item is disabled
304 virtual void DrawFocusBackground( wxDC
& dc
, const wxRect
& rect
, int flags
);
306 // Returns true if focus indicator should be drawn.
307 bool ShouldDrawFocus() const
309 const wxWindow
* curFocus
= FindFocus();
310 return ( !m_isPopupShown
&&
311 (curFocus
== this || (m_btn
&& curFocus
== m_btn
)) &&
312 (m_windowStyle
& wxCB_READONLY
) );
315 // These methods return references to appropriate dropbutton bitmaps
316 const wxBitmap
& GetBitmapNormal() const { return m_bmpNormal
; }
317 const wxBitmap
& GetBitmapPressed() const { return m_bmpPressed
; }
318 const wxBitmap
& GetBitmapHover() const { return m_bmpHover
; }
319 const wxBitmap
& GetBitmapDisabled() const { return m_bmpDisabled
; }
321 // Return internal flags
322 wxUint32
GetInternalFlags() const { return m_iFlags
; }
324 // Return true if Create has finished
325 bool IsCreated() const { return m_iFlags
& wxCC_IFLAG_CREATED
? true : false; }
327 // Popup may use these as callbacks to measure and draw list items.
328 // (wxOwnerDrawnComboBox uses these, obviously)
329 // item: -1 means item is the combo control itself
330 // flags: wxCC_PAINTING_CONTROL is set if painting to combo control instead of list
331 // return value: OnDrawListItem must return true if it did anything
332 virtual bool OnDrawListItem( wxDC
& dc
, const wxRect
& rect
, int item
, int flags
);
334 // Return item height, or -1 for text height (default)
335 virtual wxCoord
OnMeasureListItem( int item
);
337 // Return item width, or -1 for calculating from text extent (default)
338 virtual wxCoord
OnMeasureListItemWidth( int item
);
341 // I basicly needed to add callback methods into wxComboControlBase - otherwise it
342 // will not be easily possible to use wxVListBoxComboPopup from simultaneously existing
343 // wxComboControl and wxGenericComboControl (since some native implementations
344 // might not have all the features, I really would like to have this options).
346 // common code to be called on popup hide/dismiss
347 void OnPopupDismiss();
352 // Override these for customization purposes
355 // called from wxSizeEvent handler
356 virtual void OnResize() = 0;
358 // Return native text identation (for pure text, not textctrl)
359 virtual wxCoord
GetNativeTextIndent() const;
361 // Called in syscolourchanged handler and base create
362 virtual void OnThemeChange();
364 // Creates wxTextCtrl.
365 // extraStyle: Extra style parameters
366 void CreateTextCtrl( int extraStyle
, const wxValidator
& validator
);
368 // Installs standard input handler to combo (and optionally to the textctrl)
369 void InstallInputHandlers( bool alsoTextCtrl
= true );
371 // Draws dropbutton. Using wxRenderer or bitmaps, as appropriate.
372 void DrawButton( wxDC
& dc
, const wxRect
& rect
, bool paintBg
= true );
374 // Call if cursor is on button area or mouse is captured for the button.
375 //bool HandleButtonMouseEvent( wxMouseEvent& event, bool isInside );
376 bool HandleButtonMouseEvent( wxMouseEvent
& event
, int flags
);
378 // Conversion to double-clicks and some basic filtering
379 // returns true if event was consumed or filtered (event type is also set to 0 in this case)
380 //bool PreprocessMouseEvent( wxMouseEvent& event, bool isOnButtonArea );
381 bool PreprocessMouseEvent( wxMouseEvent
& event
, int flags
);
384 // This will handle left_down and left_dclick events outside button in a Windows-like manner.
385 // If you need alternate behaviour, it is recommended you manipulate and filter events to it
386 // instead of building your own handling routine (for reference, on wxEVT_LEFT_DOWN it will
387 // toggle popup and on wxEVT_LEFT_DCLICK it will do the same or run the popup's dclick method,
388 // if defined - you should pass events of other types of it for common processing).
389 void HandleNormalMouseEvent( wxMouseEvent
& event
);
391 // Creates popup window, calls interface->Create(), etc
394 // override the base class virtuals involved in geometry calculations
395 virtual void DoMoveWindow(int x
, int y
, int width
, int height
);
396 virtual wxSize
DoGetBestSize() const;
398 // Recalculates button and textctrl areas. Called when size or button setup change.
399 // btnWidth: default/calculated width of the dropbutton. 0 means unchanged,
401 void CalculateAreas( int btnWidth
= 0 );
403 // Standard textctrl positioning routine. Just give it platform-dependant
404 // textctrl coordinate adjustment.
405 void PositionTextCtrl( int textCtrlXAdjust
, int textCtrlYAdjust
);
408 void OnSizeEvent( wxSizeEvent
& event
);
409 void OnFocusEvent(wxFocusEvent
& event
);
410 void OnTextCtrlEvent(wxCommandEvent
& event
);
411 void OnSysColourChanged(wxSysColourChangedEvent
& event
);
413 // Set customization flags (directs how wxComboControlBase helpers behave)
414 void Customize( wxUint32 flags
) { m_iFlags
|= flags
; }
416 // Dispatches size event and refreshes
417 void RecalcAndRefresh();
419 // Used by OnPaints of derived classes
420 wxBitmap
& GetBufferBitmap(const wxSize
& sz
) const;
422 // This is used when m_text is hidden (readonly).
423 wxString m_valueString
;
425 // the text control and button we show all the time
429 // wxPopupWindow or similar containing the window managed by the interface.
430 wxWindow
* m_winPopup
;
432 // the popup control/panel
436 wxComboPopup
* m_popupInterface
;
438 // this is for this control itself
439 wxEvtHandler
* m_extraEvtHandler
;
442 wxEvtHandler
* m_textEvtHandler
;
444 // this is for the top level window
445 wxEvtHandler
* m_toplevEvtHandler
;
447 // this is for the control in popup
448 wxEvtHandler
* m_popupExtraHandler
;
450 // needed for "instant" double-click handling
451 wxLongLong m_timeLastMouseUp
;
453 // used to prevent immediate re-popupping incase closed popup
454 // by clicking on the combo control (needed because of inconsistent
455 // transient implementation across platforms).
456 wxLongLong m_timeCanAcceptClick
;
458 // how much popup should expand to the left/right of the control
462 // minimum popup width
463 wxCoord m_widthMinPopup
;
465 // preferred popup height
466 wxCoord m_heightPopup
;
468 // how much of writable combo is custom-paint by callback?
469 // also used to indicate area that is not covered by "blue"
470 // selection indicator.
471 wxCoord m_widthCustomPaint
;
473 // absolute text indentation, in pixels
476 // side on which the popup is aligned
479 // Width of the "fake" border
480 wxCoord m_widthCustomBorder
;
482 // The button and textctrl click/paint areas
486 // current button state (uses renderer flags)
495 // last default button width
498 // custom dropbutton bitmaps
499 wxBitmap m_bmpNormal
;
500 wxBitmap m_bmpPressed
;
502 wxBitmap m_bmpDisabled
;
504 // area used by the button
507 // platform-dependant customization and other flags
510 // draw blank button background under bitmap?
511 bool m_blankButtonBg
;
513 // is the popup window currenty shown?
516 // Set to 1 on mouse down, 0 on mouse up. Used to eliminate down-less mouse ups.
522 DECLARE_EVENT_TABLE()
524 DECLARE_ABSTRACT_CLASS(wxComboControlBase
)
528 // ----------------------------------------------------------------------------
529 // wxComboPopup is the interface which must be implemented by a control to be
530 // used as a popup by wxComboControl
531 // ----------------------------------------------------------------------------
534 // wxComboPopup internal flags
537 // Set by wxComboControlBase after Create is called
538 wxCP_IFLAG_CREATED
= 0x0001
542 class WXDLLEXPORT wxComboPopup
544 friend class wxComboControlBase
;
546 wxComboPopup(wxComboControlBase
*combo
)
552 virtual ~wxComboPopup();
554 // Create the popup child control.
555 // Return true for success.
556 virtual bool Create(wxWindow
* parent
) = 0;
558 // We must have an associated control which is subclassed by the combobox.
559 virtual wxWindow
*GetControl() = 0;
561 // Called immediately after the popup is shown
562 virtual void OnPopup();
564 // Called when popup is dismissed
565 virtual void OnDismiss();
567 // Called just prior to displaying popup.
568 // Default implementation does nothing.
569 virtual void SetStringValue( const wxString
& value
);
571 // Gets displayed string representation of the value.
572 virtual wxString
GetStringValue() const = 0;
574 // This is called to custom paint in the combo control itself (ie. not the popup).
575 // Default implementation draws value as string.
576 virtual void PaintComboControl( wxDC
& dc
, const wxRect
& rect
);
578 // Receives key events from the parent wxComboControl.
579 // Events not handled should be skipped, as usual.
580 virtual void OnComboKeyEvent( wxKeyEvent
& event
);
582 // Implement if you need to support special action when user
583 // double-clicks on the parent wxComboControl.
584 virtual void OnComboDoubleClick();
586 // Return final size of popup. Called on every popup, just prior to OnShow.
587 // minWidth = preferred minimum width for window
588 // prefHeight = preferred height. Only applies if > 0,
589 // maxHeight = max height for window, as limited by screen size
590 // and should only be rounded down, if necessary.
591 virtual wxSize
GetAdjustedSize( int minWidth
, int prefHeight
, int maxHeight
);
593 // Return true if you want delay call to Create until the popup is shown
594 // for the first time. It is more efficient, but note that it is often
595 // more convenient to have the control created immediately.
596 // Default returns false.
597 virtual bool LazyCreate();
606 // Returns true if Create has been called.
607 bool IsCreated() const
609 return (m_iFlags
& wxCP_IFLAG_CREATED
) ? true : false;
613 wxComboControlBase
* m_combo
;
618 // ----------------------------------------------------------------------------
619 // include the platform-dependent header defining the real class
620 // ----------------------------------------------------------------------------
622 #if defined(__WXUNIVERSAL__)
623 // No native universal (but it must still be first in the list)
624 #elif defined(__WXMSW__)
625 #include "wx/msw/combo.h"
628 // Any ports may need generic as an alternative
629 #include "wx/generic/combo.h"
631 #endif // wxUSE_COMBOCONTROL
634 // _WX_COMBOCONTROL_H_BASE_