]> git.saurik.com Git - wxWidgets.git/blob - interface/combo.h
Finished initial review of the rest of the [co*] interface headers.
[wxWidgets.git] / interface / combo.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: combo.h
3 // Purpose: interface of wxComboCtrl and wxComboPopup
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxComboPopup
11 @wxheader{combo.h}
12
13 In order to use a custom popup with wxComboCtrl, an interface class must be
14 derived from wxComboPopup.
15
16 For more information on how to use it, see @ref comboctrl_custompopup.
17
18 @library{wxcore}
19 @category{ctrl}
20
21 @see wxComboCtrl
22 */
23 class wxComboPopup
24 {
25 public:
26 /**
27 Default constructor. It is recommended that internal variables are
28 prepared in Init() instead (because m_combo is not valid in
29 constructor).
30 */
31 wxComboPopup();
32
33 /**
34 The derived class must implement this to create the popup control.
35
36 @returns @true if the call succeeded, @false otherwise.
37 */
38 virtual bool Create(wxWindow* parent);
39
40 /**
41 Utility function that hides the popup.
42 */
43 void Dismiss();
44
45 /**
46 The derived class may implement this to return adjusted size for the
47 popup control, according to the variables given.
48
49 @param minWidth
50 Preferred minimum width.
51 @param prefHeight
52 Preferred height. May be -1 to indicate no preference.
53 @param maxWidth
54 Max height for window, as limited by screen size.
55
56 @remarks This function is called each time popup is about to be shown.
57 */
58 virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight);
59
60 /**
61 The derived class must implement this to return pointer to the
62 associated control created in Create().
63 */
64 virtual wxWindow* GetControl();
65
66 /**
67 The derived class must implement this to return string representation
68 of the value.
69 */
70 virtual wxString GetStringValue() const;
71
72 /**
73 The derived class must implement this to initialize its internal
74 variables. This method is called immediately after construction
75 finishes. m_combo member variable has been initialized before the call.
76 */
77 virtual void Init();
78
79 /**
80 Utility method that returns @true if Create has been called.
81
82 Useful in conjunction with LazyCreate().
83 */
84 bool IsCreated() const;
85
86 /**
87 The derived class may implement this to return @true if it wants to
88 delay call to Create() until the popup is shown for the first time. It
89 is more efficient, but on the other hand it is often more convenient to
90 have the control created immediately.
91
92 @remarks Base implementation returns @false.
93 */
94 virtual bool LazyCreate();
95
96 /**
97 The derived class may implement this to do something when the parent
98 wxComboCtrl gets double-clicked.
99 */
100 virtual void OnComboDoubleClick();
101
102 /**
103 The derived class may implement this to receive key events from the
104 parent wxComboCtrl.
105
106 Events not handled should be skipped, as usual.
107 */
108 virtual void OnComboKeyEvent(wxKeyEvent& event);
109
110 /**
111 The derived class may implement this to do special processing when
112 popup is hidden.
113 */
114 virtual void OnDismiss();
115
116 /**
117 The derived class may implement this to do special processing when
118 popup is shown.
119 */
120 virtual void OnPopup();
121
122 /**
123 The derived class may implement this to paint the parent wxComboCtrl.
124
125 Default implementation draws value as string.
126 */
127 virtual void PaintComboControl(wxDC& dc, const wxRect& rect);
128
129 /**
130 The derived class must implement this to receive string value changes
131 from wxComboCtrl.
132 */
133 virtual void SetStringValue(const wxString& value);
134
135 /**
136 Parent wxComboCtrl. This is parameter has been prepared before Init()
137 is called.
138 */
139 wxComboCtrl m_combo;
140 };
141
142
143
144 /**
145 Features enabled for wxComboCtrl.
146
147 @see wxComboCtrl::GetFeatures()
148 */
149 struct wxComboCtrlFeatures
150 {
151 enum
152 {
153 MovableButton = 0x0001, ///< Button can be on either side of control.
154 BitmapButton = 0x0002, ///< Button may be replaced with bitmap.
155 ButtonSpacing = 0x0004, ///< Button can have spacing from the edge
156 ///< of the control.
157 TextIndent = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used.
158 PaintControl = 0x0010, ///< Combo control itself can be custom painted.
159 PaintWritable = 0x0020, ///< A variable-width area in front of writable
160 ///< combo control's textctrl can be custom
161 ///< painted.
162 Borderless = 0x0040, ///< wxNO_BORDER window style works.
163
164 All = MovableButton | BitmapButton | ButtonSpacing |
165 TextIndent | PaintControl | PaintWritable |
166 Borderless ///< All features.
167 };
168 };
169
170
171 /**
172 @class wxComboCtrl
173 @wxheader{combo.h}
174
175 A combo control is a generic combobox that allows totally custom popup. In
176 addition it has other customization features. For instance, position and
177 size of the dropdown button can be changed.
178
179 @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl
180
181 wxComboCtrl needs to be told somehow which control to use and this is done
182 by SetPopupControl(). However, we need something more than just a wxControl
183 in this method as, for example, we need to call
184 SetStringValue("initial text value") and wxControl doesn't have such
185 method. So we also need a wxComboPopup which is an interface which must be
186 implemented by a control to be usable as a popup.
187
188 We couldn't derive wxComboPopup from wxControl as this would make it
189 impossible to have a class deriving from a wxWidgets control and from it,
190 so instead it is just a mix-in.
191
192 Here's a minimal sample of wxListView popup:
193
194 @code
195 #include <wx/combo.h>
196 #include <wx/listctrl.h>
197
198 class wxListViewComboPopup : public wxListView, public wxComboPopup
199 {
200 public:
201 // Initialize member variables
202 virtual void Init()
203 {
204 m_value = -1;
205 }
206
207 // Create popup control
208 virtual bool Create(wxWindow* parent)
209 {
210 return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize);
211 }
212
213 // Return pointer to the created control
214 virtual wxWindow *GetControl() { return this; }
215
216 // Translate string into a list selection
217 virtual void SetStringValue(const wxString& s)
218 {
219 int n = wxListView::FindItem(-1,s);
220 if ( n >= 0 && n < wxListView::GetItemCount() )
221 wxListView::Select(n);
222 }
223
224 // Get list selection as a string
225 virtual wxString GetStringValue() const
226 {
227 if ( m_value >= 0 )
228 return wxListView::GetItemText(m_value);
229 return wxEmptyString;
230 }
231
232 // Do mouse hot-tracking (which is typical in list popups)
233 void OnMouseMove(wxMouseEvent& event)
234 {
235 // TODO: Move selection to cursor
236 }
237
238 // On mouse left up, set the value and close the popup
239 void OnMouseClick(wxMouseEvent& WXUNUSED(event))
240 {
241 m_value = wxListView::GetFirstSelected();
242
243 // TODO: Send event as well
244
245 Dismiss();
246 }
247
248 protected:
249
250 int m_value; // current item index
251
252 private:
253 DECLARE_EVENT_TABLE()
254 };
255
256 BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
257 EVT_MOTION(wxListViewComboPopup::OnMouseMove)
258 EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
259 END_EVENT_TABLE()
260 @endcode
261
262 Here's how you would create and populate it in a dialog constructor:
263
264 @code
265 wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString);
266
267 wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
268
269 comboCtrl->SetPopupControl(popupCtrl);
270
271 // Populate using wxListView methods
272 popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item");
273 popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item");
274 popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item");
275 @endcode
276
277 @beginStyleTable
278 @style{wxCB_READONLY}
279 Text will not be editable.
280 @style{wxCB_SORT}
281 Sorts the entries in the list alphabetically.
282 @style{wxTE_PROCESS_ENTER}
283 The control will generate the event wxEVT_COMMAND_TEXT_ENTER
284 (otherwise pressing Enter key is either processed internally by the
285 control or used for navigation between dialog controls). Windows
286 only.
287 @style{wxCC_SPECIAL_DCLICK}
288 Double-clicking triggers a call to popup's OnComboDoubleClick.
289 Actual behaviour is defined by a derived class. For instance,
290 wxOwnerDrawnComboBox will cycle an item. This style only applies if
291 wxCB_READONLY is used as well.
292 @style{wxCC_STD_BUTTON}
293 Drop button will behave more like a standard push button.
294 @endStyleTable
295
296 @beginEventTable{wxCommandEvent}
297 @event{EVT_TEXT(id, func)}
298 Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes.
299 @event{EVT_TEXT_ENTER(id, func)}
300 Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
301 the combo control.
302 @endEventTable
303
304 @library{wxbase}
305 @category{ctrl}
306 <!-- @appearance{comboctrl.png} -->
307
308 @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
309 wxCommandEvent
310 */
311 class wxComboCtrl : public wxControl
312 {
313 public:
314 /**
315 Default constructor.
316 */
317 wxComboCtrl();
318
319 /**
320 Constructor, creating and showing a combo control.
321
322 @param parent
323 Parent window. Must not be @NULL.
324 @param id
325 Window identifier. The value wxID_ANY indicates a default value.
326 @param value
327 Initial selection string. An empty string indicates no selection.
328 @param pos
329 Window position.
330 @param size
331 Window size. If wxDefaultSize is specified then the window is sized
332 appropriately.
333 @param style
334 Window style. See wxComboCtrl.
335 @param validator
336 Window validator.
337 @param name
338 Window name.
339
340 @see Create(), wxValidator
341 */
342 wxComboCtrl(wxWindow* parent, wxWindowID id,
343 const wxString& value = "",
344 const wxPoint& pos = wxDefaultPosition,
345 const wxSize& size = wxDefaultSize,
346 long style = 0,
347 const wxValidator& validator = wxDefaultValidator,
348 const wxString& name = "comboCtrl");
349
350 /**
351 Destructor, destroying the combo control.
352 */
353 virtual ~wxComboCtrl();
354
355 /**
356 This member function is not normally called in application code.
357 Instead, it can be implemented in a derived class to create a custom
358 popup animation.
359
360 The parameters are the same as those for DoShowPopup().
361
362 @returns @true if animation finishes before the function returns,
363 @false otherwise. In the latter case you need to manually call
364 DoShowPopup() after the animation ends.
365 */
366 virtual bool AnimateShow(const wxRect& rect, int flags);
367
368 /**
369 Copies the selected text to the clipboard.
370 */
371 virtual void Copy();
372
373 /**
374 Creates the combo control for two-step construction. Derived classes
375 should call or replace this function. See wxComboCtrl() for further
376 details.
377 */
378 bool Create(wxWindow* parent, wxWindowID id,
379 const wxString& value = "",
380 const wxPoint& pos = wxDefaultPosition,
381 const wxSize& size = wxDefaultSize,
382 long style = 0,
383 const wxValidator& validator = wxDefaultValidator,
384 const wxString& name = "comboCtrl");
385
386 /**
387 Copies the selected text to the clipboard and removes the selection.
388 */
389 virtual void Cut();
390
391 /**
392 This member function is not normally called in application code.
393 Instead, it can be implemented in a derived class to return default
394 wxComboPopup, incase @a popup is @NULL.
395
396 @note If you have implemented OnButtonClick() to do something else than
397 show the popup, then DoSetPopupControl() must always set @a popup
398 to @NULL.
399 */
400 void DoSetPopupControl(wxComboPopup* popup);
401
402 /**
403 This member function is not normally called in application code.
404 Instead, it must be called in a derived class to make sure popup is
405 properly shown after a popup animation has finished (but only if
406 AnimateShow() did not finish the animation within its function scope).
407
408 @param rect
409 Position to show the popup window at, in screen coordinates.
410 @param flags
411 Combination of any of the following:
412 @beginTable
413 @row2col{wxComboCtrl::ShowAbove,
414 Popup is shown above the control instead of below.}
415 @row2col{wxComboCtrl::CanDeferShow,
416 Showing the popup can be deferred to happen sometime after
417 ShowPopup() has finished. In this case, AnimateShow() must
418 return false.}
419 @endTable
420 */
421 virtual void DoShowPopup(const wxRect& rect, int flags);
422
423 /**
424 Enables or disables popup animation, if any, depending on the value of
425 the argument.
426 */
427 void EnablePopupAnimation(bool enable = true);
428
429 /**
430 Returns disabled button bitmap that has been set with
431 SetButtonBitmaps().
432
433 @returns A reference to the disabled state bitmap.
434 */
435 const wxBitmap GetBitmapDisabled() const;
436
437 /**
438 Returns button mouse hover bitmap that has been set with
439 SetButtonBitmaps().
440
441 @returns A reference to the mouse hover state bitmap.
442 */
443 const wxBitmap GetBitmapHover() const;
444
445 /**
446 Returns default button bitmap that has been set with
447 SetButtonBitmaps().
448
449 @returns A reference to the normal state bitmap.
450 */
451 const wxBitmap GetBitmapNormal() const;
452
453 /**
454 Returns depressed button bitmap that has been set with
455 SetButtonBitmaps().
456
457 @returns A reference to the depressed state bitmap.
458 */
459 const wxBitmap GetBitmapPressed() const;
460
461 /**
462 Returns current size of the dropdown button.
463 */
464 wxSize GetButtonSize();
465
466 /**
467 Returns custom painted area in control.
468
469 @see SetCustomPaintWidth().
470 */
471 int GetCustomPaintWidth() const;
472
473 /**
474 Returns features supported by wxComboCtrl. If needed feature is
475 missing, you need to instead use wxGenericComboCtrl, which however may
476 lack a native look and feel (but otherwise sports identical API).
477
478 @returns Value returned is a combination of the flags defined in
479 wxComboCtrlFeatures.
480 */
481 static int GetFeatures();
482
483 /**
484 Returns the insertion point for the combo control's text field.
485
486 @note Under Windows, this function always returns 0 if the combo
487 control doesn't have the focus.
488 */
489 virtual long GetInsertionPoint() const;
490
491 /**
492 Returns the last position in the combo control text field.
493 */
494 virtual long GetLastPosition() const;
495
496 /**
497 Returns current popup interface that has been set with
498 SetPopupControl().
499 */
500 wxComboPopup* GetPopupControl();
501
502 /**
503 Returns popup window containing the popup control.
504 */
505 wxWindow* GetPopupWindow() const;
506
507 /**
508 Get the text control which is part of the combo control.
509 */
510 wxTextCtrl* GetTextCtrl() const;
511
512 /**
513 Returns actual indentation in pixels.
514 */
515 wxCoord GetTextIndent() const;
516
517 /**
518 Returns area covered by the text field (includes everything except
519 borders and the dropdown button).
520 */
521 const wxRect GetTextRect() const;
522
523 /**
524 Returns text representation of the current value. For writable combo
525 control it always returns the value in the text field.
526 */
527 virtual wxString GetValue() const;
528
529 /**
530 Dismisses the popup window.
531 */
532 virtual void HidePopup();
533
534 /**
535 Returns @true if the popup is currently shown
536 */
537 bool IsPopupShown() const;
538
539 /**
540 Returns @true if the popup window is in the given state. Possible
541 values are:
542
543 @beginTable
544 @row2col{wxComboCtrl::Hidden, Popup window is hidden.}
545 @row2col{wxComboCtrl::Animating, Popup window is being shown, but the
546 popup animation has not yet finished.}
547 @row2col{wxComboCtrl::Visible, Popup window is fully visible.}
548 @endTable
549 */
550 bool IsPopupWindowState(int state) const;
551
552 /**
553 Implement in a derived class to define what happens on dropdown button
554 click. Default action is to show the popup.
555
556 @note If you implement this to do something else than show the popup,
557 you must then also implement DoSetPopupControl() to always return
558 @NULL.
559 */
560 virtual void OnButtonClick();
561
562 /**
563 Pastes text from the clipboard to the text field.
564 */
565 virtual void Paste();
566
567 /**
568 Removes the text between the two positions in the combo control text
569 field.
570
571 @param from
572 The first position.
573 @param to
574 The last position.
575 */
576 virtual void Remove(long from, long to);
577
578 /**
579 Replaces the text between two positions with the given text, in the
580 combo control text field.
581
582 @param from
583 The first position.
584 @param to
585 The second position.
586 @param text
587 The text to insert.
588 */
589 virtual void Replace(long from, long to, const wxString& value);
590
591 /**
592 Sets custom dropdown button graphics.
593
594 @param bmpNormal
595 Default button image.
596 @param pushButtonBg
597 If @true, blank push button background is painted below the image.
598 @param bmpPressed
599 Depressed button image.
600 @param bmpHover
601 Button image when mouse hovers above it. This should be ignored on
602 platforms and themes that do not generally draw different kind of
603 button on mouse hover.
604 @param bmpDisabled
605 Disabled button image.
606 */
607 void SetButtonBitmaps(const wxBitmap& bmpNormal,
608 bool pushButtonBg = false,
609 const wxBitmap& bmpPressed = wxNullBitmap,
610 const wxBitmap& bmpHover = wxNullBitmap,
611 const wxBitmap& bmpDisabled = wxNullBitmap);
612
613 /**
614 Sets size and position of dropdown button.
615
616 @param width
617 Button width. Value = 0 specifies default.
618 @param height
619 Button height. Value = 0 specifies default.
620 @param side
621 Indicates which side the button will be placed. Value can be wxLEFT
622 or wxRIGHT.
623 @param spacingX
624 Horizontal spacing around the button. Default is 0.
625 */
626 void SetButtonPosition(int width = -1, int height = -1,
627 int side = wxRIGHT, int spacingX = 0);
628
629 /**
630 Set width, in pixels, of custom painted area in control without
631 @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used
632 to indicate area that is not covered by the focus rectangle.
633 */
634 void SetCustomPaintWidth(int width);
635
636 /**
637 Sets the insertion point in the text field.
638
639 @param pos
640 The new insertion point.
641 */
642 virtual void SetInsertionPoint(long pos);
643
644 /**
645 Sets the insertion point at the end of the combo control text field.
646 */
647 virtual void SetInsertionPointEnd();
648
649 /**
650 Set side of the control to which the popup will align itself. Valid
651 values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that
652 the most appropriate side is used (which, currently, is always
653 @c wxLEFT).
654 */
655 void SetPopupAnchor(int anchorSide);
656
657 /**
658 Set popup interface class derived from wxComboPopup. This method should
659 be called as soon as possible after the control has been created,
660 unless OnButtonClick() has been overridden.
661 */
662 void SetPopupControl(wxComboPopup* popup);
663
664 /**
665 Extends popup size horizontally, relative to the edges of the combo
666 control.
667
668 @param extLeft
669 How many pixel to extend beyond the left edge of the control.
670 Default is 0.
671 @param extRight
672 How many pixel to extend beyond the right edge of the control.
673 Default is 0.
674
675 @remarks Popup minimum width may override arguments. It is up to the
676 popup to fully take this into account.
677 */
678 void SetPopupExtents(int extLeft, int extRight);
679
680 /**
681 Sets preferred maximum height of the popup.
682
683 @remarks Value -1 indicates the default.
684 */
685 void SetPopupMaxHeight(int height);
686
687 /**
688 Sets minimum width of the popup. If wider than combo control, it will
689 extend to the left.
690
691 @remarks Value -1 indicates the default. Also, popup implementation may
692 choose to ignore this.
693 */
694 void SetPopupMinWidth(int width);
695
696 /**
697 Selects the text between the two positions, in the combo control text
698 field.
699
700 @param from
701 The first position.
702 @param to
703 The second position.
704 */
705 virtual void SetSelection(long from, long to);
706
707 /**
708 Sets the text for the text field without affecting the popup. Thus,
709 unlike SetValue(), it works equally well with combo control using
710 @c wxCB_READONLY style.
711 */
712 void SetText(const wxString& value);
713
714 /**
715 This will set the space in pixels between left edge of the control and
716 the text, regardless whether control is read-only or not. Value -1 can
717 be given to indicate platform default.
718 */
719 void SetTextIndent(int indent);
720
721 /**
722 Sets the text for the combo control text field.
723
724 @note For a combo control with @c wxCB_READONLY style the string must
725 be accepted by the popup (for instance, exist in the dropdown
726 list), otherwise the call to SetValue() is ignored.
727 */
728 virtual void SetValue(const wxString& value);
729
730 /**
731 Same as SetValue(), but also sends wxCommandEvent of type
732 wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
733 */
734 void SetValueWithEvent(const wxString& value, bool withEvent = true);
735
736 /**
737 Show the popup.
738 */
739 virtual void ShowPopup();
740
741 /**
742 Undoes the last edit in the text field. Windows only.
743 */
744 virtual void Undo();
745
746 /**
747 Enable or disable usage of an alternative popup window, which
748 guarantees ability to focus the popup control, and allows common native
749 controls to function normally. This alternative popup window is usually
750 a wxDialog, and as such, when it is shown, its parent top-level window
751 will appear as if the focus has been lost from it.
752 */
753 void UseAltPopupWindow(bool enable = true);
754 };
755