]>
git.saurik.com Git - wxWidgets.git/blob - interface/combo.h
1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxComboPopup
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
13 In order to use a custom popup with wxComboCtrl, an interface class must
14 be derived from wxComboPopup.
16 For more information on how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for
28 Default constructor. It is recommended that internal variables
29 are prepared in Init() instead
30 (because @ref mcombo() m_combo is not valid in constructor).
35 The derived class must implement this to create the popup control.
37 @returns @true if the call succeeded, @false otherwise.
39 bool Create(wxWindow
* parent
);
42 Utility function that hides the popup.
47 The derived class may implement this to return adjusted size
48 for the popup control, according to the variables given.
51 Preferred minimum width.
53 Preferred height. May be -1 to indicate
56 Max height for window, as limited by
59 @remarks Called each time popup is about to be shown.
61 wxSize
GetAdjustedSize(int minWidth
, int prefHeight
,
65 The derived class must implement this to return pointer
66 to the associated control created in Create().
68 wxWindow
* GetControl();
71 The derived class must implement this to return
72 string representation of the value.
74 wxString
GetStringValue() const;
77 The derived class must implement this to initialize
78 its internal variables. This method is called immediately
79 after construction finishes. @ref mcombo() m_combo
80 member variable has been initialized before the call.
85 Utility method that returns @true if Create has been called.
86 Useful in conjunction with LazyCreate().
88 bool IsCreated() const;
91 The derived class may implement this to return
92 @true if it wants to delay call to Create()
93 until the popup is shown for the first time. It is more
94 efficient, but on the other hand it is often more convenient
95 to have the control created immediately.
97 @remarks Base implementation returns @false.
102 The derived class may implement this to do something
103 when the parent wxComboCtrl gets double-clicked.
105 void OnComboDoubleClick();
108 The derived class may implement this to receive
109 key events from the parent wxComboCtrl.
110 Events not handled should be skipped, as usual.
112 void OnComboKeyEvent(wxKeyEvent
& event
);
115 The derived class may implement this to do
116 special processing when popup is hidden.
121 The derived class may implement this to do
122 special processing when popup is shown.
127 The derived class may implement this to paint
128 the parent wxComboCtrl.
129 Default implementation draws value as string.
131 void PaintComboControl(wxDC
& dc
, const wxRect
& rect
);
134 The derived class must implement this to receive
135 string value changes from wxComboCtrl.
137 void SetStringValue(const wxString
& value
);
141 Parent wxComboCtrl. This is parameter has
142 been prepared before Init() is called.
152 A combo control is a generic combobox that allows totally custom popup.
153 In addition it has other customization features.
154 For instance, position and size of the dropdown button can be changed.
156 @section wxcomboctrl_custompopup Setting Custom Popup for wxComboCtrl
158 wxComboCtrl needs to be told somehow which control to use and this is done
159 by SetPopupControl().
160 However, we need something more than just a wxControl in this method as,
161 for example, we need to call SetStringValue("initial text value") and
162 wxControl doesn't have such method. So we also need a wxComboPopup which
163 is an interface which must be implemented by a control to be usable as a popup.
165 We couldn't derive wxComboPopup from wxControl as this would make it
166 impossible to have a class deriving from a wxWidgets control and from it,
167 so instead it is just a mix-in.
169 Here's a minimal sample of wxListView popup:
172 #include <wx/combo.h>
173 #include <wx/listctrl.h>
175 class wxListViewComboPopup : public wxListView,
180 // Initialize member variables
186 // Create popup control
187 virtual bool Create(wxWindow* parent)
189 return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize);
192 // Return pointer to the created control
193 virtual wxWindow *GetControl() { return this; }
195 // Translate string into a list selection
196 virtual void SetStringValue(const wxString& s)
198 int n = wxListView::FindItem(-1,s);
199 if ( n >= 0 && n < wxListView::GetItemCount() )
200 wxListView::Select(n);
203 // Get list selection as a string
204 virtual wxString GetStringValue() const
207 return wxListView::GetItemText(m_value);
208 return wxEmptyString;
211 // Do mouse hot-tracking (which is typical in list popups)
212 void OnMouseMove(wxMouseEvent& event)
214 // TODO: Move selection to cursor
217 // On mouse left up, set the value and close the popup
218 void OnMouseClick(wxMouseEvent& WXUNUSED(event))
220 m_value = wxListView::GetFirstSelected();
222 // TODO: Send event as well
228 int m_value; // current item index
231 DECLARE_EVENT_TABLE()
234 BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
235 EVT_MOTION(wxListViewComboPopup::OnMouseMove)
236 EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
240 Here's how you would create and populate it in a dialog constructor:
243 wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString);
245 wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
247 comboCtrl->SetPopupControl(popupCtrl);
249 // Populate using wxListView methods
250 popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("First Item"));
251 popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Second Item"));
252 popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Third Item"));
256 @style{wxCB_READONLY}
257 Text will not be editable.
259 Sorts the entries in the list alphabetically.
260 @style{wxTE_PROCESS_ENTER}
261 The control will generate the event wxEVT_COMMAND_TEXT_ENTER
262 (otherwise pressing Enter key is either processed internally by the
263 control or used for navigation between dialog controls). Windows
265 @style{wxCC_SPECIAL_DCLICK}
266 Double-clicking triggers a call to popup's OnComboDoubleClick.
267 Actual behaviour is defined by a derived class. For instance,
268 wxOwnerDrawnComboBox will cycle an item. This style only applies if
269 wxCB_READONLY is used as well.
270 @style{wxCC_STD_BUTTON}
271 Drop button will behave more like a standard push button.
274 @beginEventTable{wxCommandEvent}
275 @event{EVT_TEXT(id, func)}
276 Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes.
277 @event{EVT_TEXT_ENTER(id, func)}
278 Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
284 @appearance{comboctrl.png}
286 @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent
288 class wxComboCtrl
: public wxControl
293 Constructor, creating and showing a combo control.
296 Parent window. Must not be @NULL.
298 Window identifier. The value wxID_ANY indicates a default value.
300 Initial selection string. An empty string indicates no selection.
304 Window size. If wxDefaultSize is specified then the window is
308 Window style. See wxComboCtrl.
314 @see Create(), wxValidator
317 wxComboCtrl(wxWindow
* parent
, wxWindowID id
,
318 const wxString
& value
= "",
319 const wxPoint
& pos
= wxDefaultPosition
,
320 const wxSize
& size
= wxDefaultSize
,
322 const wxValidator
& validator
= wxDefaultValidator
,
323 const wxString
& name
= "comboCtrl");
327 Destructor, destroying the combo control.
332 This member function is not normally called in application code.
333 Instead, it can be implemented in a derived class to create a
334 custom popup animation.
336 @returns @true if animation finishes before the function returns. @false
337 otherwise. In the latter case you need to manually call
338 DoShowPopup after the animation ends.
340 virtual bool AnimateShow(const wxRect
& rect
, int flags
);
343 Copies the selected text to the clipboard.
348 Creates the combo control for two-step construction. Derived classes
349 should call or replace this function. See wxComboCtrl()
352 bool Create(wxWindow
* parent
, wxWindowID id
,
353 const wxString
& value
= "",
354 const wxPoint
& pos
= wxDefaultPosition
,
355 const wxSize
& size
= wxDefaultSize
,
357 const wxValidator
& validator
= wxDefaultValidator
,
358 const wxString
& name
= "comboCtrl");
361 Copies the selected text to the clipboard and removes the selection.
366 This member function is not normally called in application code.
367 Instead, it can be implemented in a derived class to return
368 default wxComboPopup, incase @c popup is @NULL.
369 @note If you have implemented OnButtonClick to do
370 something else than show the popup, then DoSetPopupControl
371 must always return @NULL.
373 void DoSetPopupControl(wxComboPopup
* popup
);
376 This member function is not normally called in application code.
377 Instead, it must be called in a derived class to make sure popup
378 is properly shown after a popup animation has finished (but only
379 if AnimateShow() did not finish
380 the animation within it's function scope).
383 Position to show the popup window at, in screen coordinates.
385 Combination of any of the following:
387 virtual void DoShowPopup(const wxRect
& rect
, int flags
);
390 Enables or disables popup animation, if any, depending on the value of
393 void EnablePopupAnimation(bool enable
= true);
396 Returns disabled button bitmap that has been set with
399 @returns A reference to the disabled state bitmap.
401 const wxBitmap
GetBitmapDisabled() const;
404 Returns button mouse hover bitmap that has been set with
407 @returns A reference to the mouse hover state bitmap.
409 const wxBitmap
GetBitmapHover() const;
412 Returns default button bitmap that has been set with
415 @returns A reference to the normal state bitmap.
417 const wxBitmap
GetBitmapNormal() const;
420 Returns depressed button bitmap that has been set with
423 @returns A reference to the depressed state bitmap.
425 const wxBitmap
GetBitmapPressed() const;
428 Returns current size of the dropdown button.
430 wxSize
GetButtonSize();
433 Returns custom painted area in control.
435 @see SetCustomPaintWidth().
437 int GetCustomPaintWidth() const;
440 Returns features supported by wxComboCtrl. If needed feature is missing,
441 you need to instead use wxGenericComboCtrl, which however may lack
442 native look and feel (but otherwise sports identical API).
444 @returns Value returned is a combination of following flags:
446 static int GetFeatures();
449 Returns the insertion point for the combo control's text field.
450 @note Under wxMSW, this function always returns 0 if the combo control
451 doesn't have the focus.
453 long GetInsertionPoint() const;
456 Returns the last position in the combo control text field.
458 long GetLastPosition() const;
461 Returns current popup interface that has been set with SetPopupControl.
463 wxComboPopup
* GetPopupControl();
466 Returns popup window containing the popup control.
468 wxWindow
* GetPopupWindow() const;
471 Get the text control which is part of the combo control.
473 wxTextCtrl
* GetTextCtrl() const;
476 Returns actual indentation in pixels.
478 wxCoord
GetTextIndent() const;
481 Returns area covered by the text field (includes everything except
482 borders and the dropdown button).
484 const wxRect
GetTextRect() const;
487 Returns text representation of the current value. For writable
488 combo control it always returns the value in the text field.
490 wxString
GetValue() const;
493 Dismisses the popup window.
498 Returns @true if the popup is currently shown
500 bool IsPopupShown() const;
503 Returns @true if the popup window is in the given state.
508 Popup window is hidden.
512 Popup window is being shown, but the
513 popup animation has not yet finished.
517 Popup window is fully visible.
519 bool IsPopupWindowState(int state
) const;
522 Implement in a derived class to define what happens on
523 dropdown button click.
524 Default action is to show the popup.
525 @note If you implement this to do something else than
526 show the popup, you must then also implement
527 DoSetPopupControl() to always
530 void OnButtonClick();
533 Pastes text from the clipboard to the text field.
538 Removes the text between the two positions in the combo control text field.
545 void Remove(long from
, long to
);
548 Replaces the text between two positions with the given text, in the combo
558 void Replace(long from
, long to
, const wxString
& value
);
561 Sets custom dropdown button graphics.
564 Default button image.
566 If @true, blank push button background is painted
569 Depressed button image.
571 Button image when mouse hovers above it. This
572 should be ignored on platforms and themes that do not generally draw
573 different kind of button on mouse hover.
575 Disabled button image.
577 void SetButtonBitmaps(const wxBitmap
& bmpNormal
,
578 bool pushButtonBg
= false,
579 const wxBitmap
& bmpPressed
= wxNullBitmap
,
580 const wxBitmap
& bmpHover
= wxNullBitmap
,
581 const wxBitmap
& bmpDisabled
= wxNullBitmap
);
584 Sets size and position of dropdown button.
587 Button width. Value = 0 specifies default.
589 Button height. Value = 0 specifies default.
591 Indicates which side the button will be placed.
592 Value can be wxLEFT or wxRIGHT.
594 Horizontal spacing around the button. Default is 0.
596 void SetButtonPosition(int width
= -1, int height
= -1,
601 Set width, in pixels, of custom painted area in control without @c wxCB_READONLY
602 style. In read-only wxOwnerDrawnComboBox, this is used
603 to indicate area that is not covered by the focus rectangle.
605 void SetCustomPaintWidth(int width
);
608 Sets the insertion point in the text field.
611 The new insertion point.
613 void SetInsertionPoint(long pos
);
616 Sets the insertion point at the end of the combo control text field.
618 void SetInsertionPointEnd();
621 Set side of the control to which the popup will align itself. Valid values are
622 @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that the most appropriate
623 side is used (which, currently, is always @c wxLEFT).
625 void SetPopupAnchor(int anchorSide
);
628 Set popup interface class derived from wxComboPopup.
629 This method should be called as soon as possible after the control
630 has been created, unless OnButtonClick()
633 void SetPopupControl(wxComboPopup
* popup
);
636 Extends popup size horizontally, relative to the edges of the combo control.
639 How many pixel to extend beyond the left edge of the
640 control. Default is 0.
642 How many pixel to extend beyond the right edge of the
643 control. Default is 0.
645 @remarks Popup minimum width may override arguments.
647 void SetPopupExtents(int extLeft
, int extRight
);
650 Sets preferred maximum height of the popup.
652 @remarks Value -1 indicates the default.
654 void SetPopupMaxHeight(int height
);
657 Sets minimum width of the popup. If wider than combo control, it will extend to
660 @remarks Value -1 indicates the default.
662 void SetPopupMinWidth(int width
);
665 Selects the text between the two positions, in the combo control text field.
672 void SetSelection(long from
, long to
);
675 Sets the text for the text field without affecting the
676 popup. Thus, unlike SetValue(), it works
677 equally well with combo control using @c wxCB_READONLY style.
679 void SetText(const wxString
& value
);
682 This will set the space in pixels between left edge of the control and the
683 text, regardless whether control is read-only or not. Value -1 can be
684 given to indicate platform default.
686 void SetTextIndent(int indent
);
689 Sets the text for the combo control text field.
690 @note For a combo control with @c wxCB_READONLY style the
691 string must be accepted by the popup (for instance, exist in the dropdown
692 list), otherwise the call to SetValue() is ignored
694 void SetValue(const wxString
& value
);
697 Same as SetValue, but also sends wxCommandEvent of type
698 wxEVT_COMMAND_TEXT_UPDATED
699 if @c withEvent is @true.
701 void SetValueWithEvent(const wxString
& value
,
702 bool withEvent
= true);
710 Undoes the last edit in the text field. Windows only.
715 Enable or disable usage of an alternative popup window, which guarantees
716 ability to focus the popup control, and allows common native controls to
717 function normally. This alternative popup window is usually a wxDialog,
718 and as such, when it is shown, its parent top-level window will appear
719 as if the focus has been lost from it.
721 void UseAltPopupWindow(bool enable
= true);