]> git.saurik.com Git - wxWidgets.git/blob - interface/combo.h
implement EnableMonthChange() by restricting the dates range to the current month...
[wxWidgets.git] / interface / combo.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: combo.h
3 // Purpose: interface of 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
14 be derived from wxComboPopup.
15
16 For more information on how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for
17 wxComboCtrl".
18
19 @library{wxcore}
20 @category{FIXME}
21
22 @see wxComboCtrl
23 */
24 class wxComboPopup
25 {
26 public:
27 /**
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).
31 */
32 wxComboPopup();
33
34 /**
35 The derived class must implement this to create the popup control.
36
37 @returns @true if the call succeeded, @false otherwise.
38 */
39 bool Create(wxWindow* parent);
40
41 /**
42 Utility function that hides the popup.
43 */
44 void Dismiss();
45
46 /**
47 The derived class may implement this to return adjusted size
48 for the popup control, according to the variables given.
49
50 @param minWidth
51 Preferred minimum width.
52 @param prefHeight
53 Preferred height. May be -1 to indicate
54 no preference.
55 @param maxWidth
56 Max height for window, as limited by
57 screen size.
58
59 @remarks Called each time popup is about to be shown.
60 */
61 wxSize GetAdjustedSize(int minWidth, int prefHeight,
62 int maxHeight);
63
64 /**
65 The derived class must implement this to return pointer
66 to the associated control created in Create().
67 */
68 wxWindow* GetControl();
69
70 /**
71 The derived class must implement this to return
72 string representation of the value.
73 */
74 wxString GetStringValue() const;
75
76 /**
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.
81 */
82 void Init();
83
84 /**
85 Utility method that returns @true if Create has been called.
86 Useful in conjunction with LazyCreate().
87 */
88 bool IsCreated() const;
89
90 /**
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.
96
97 @remarks Base implementation returns @false.
98 */
99 bool LazyCreate();
100
101 /**
102 The derived class may implement this to do something
103 when the parent wxComboCtrl gets double-clicked.
104 */
105 void OnComboDoubleClick();
106
107 /**
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.
111 */
112 void OnComboKeyEvent(wxKeyEvent& event);
113
114 /**
115 The derived class may implement this to do
116 special processing when popup is hidden.
117 */
118 void OnDismiss();
119
120 /**
121 The derived class may implement this to do
122 special processing when popup is shown.
123 */
124 void OnPopup();
125
126 /**
127 The derived class may implement this to paint
128 the parent wxComboCtrl.
129 Default implementation draws value as string.
130 */
131 void PaintComboControl(wxDC& dc, const wxRect& rect);
132
133 /**
134 The derived class must implement this to receive
135 string value changes from wxComboCtrl.
136 */
137 void SetStringValue(const wxString& value);
138
139 /**
140 wxComboCtrl m_combo
141 Parent wxComboCtrl. This is parameter has
142 been prepared before Init() is called.
143 */
144 };
145
146
147
148 /**
149 @class wxComboCtrl
150 @wxheader{combo.h}
151
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.
155
156 @section wxcomboctrl_custompopup Setting Custom Popup for wxComboCtrl
157
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.
164
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.
168
169 Here's a minimal sample of wxListView popup:
170
171 @code
172 #include <wx/combo.h>
173 #include <wx/listctrl.h>
174
175 class wxListViewComboPopup : public wxListView,
176 public wxComboPopup
177 {
178 public:
179
180 // Initialize member variables
181 virtual void Init()
182 {
183 m_value = -1;
184 }
185
186 // Create popup control
187 virtual bool Create(wxWindow* parent)
188 {
189 return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize);
190 }
191
192 // Return pointer to the created control
193 virtual wxWindow *GetControl() { return this; }
194
195 // Translate string into a list selection
196 virtual void SetStringValue(const wxString& s)
197 {
198 int n = wxListView::FindItem(-1,s);
199 if ( n >= 0 && n < wxListView::GetItemCount() )
200 wxListView::Select(n);
201 }
202
203 // Get list selection as a string
204 virtual wxString GetStringValue() const
205 {
206 if ( m_value >= 0 )
207 return wxListView::GetItemText(m_value);
208 return wxEmptyString;
209 }
210
211 // Do mouse hot-tracking (which is typical in list popups)
212 void OnMouseMove(wxMouseEvent& event)
213 {
214 // TODO: Move selection to cursor
215 }
216
217 // On mouse left up, set the value and close the popup
218 void OnMouseClick(wxMouseEvent& WXUNUSED(event))
219 {
220 m_value = wxListView::GetFirstSelected();
221
222 // TODO: Send event as well
223
224 Dismiss();
225 }
226
227 protected:
228 int m_value; // current item index
229
230 private:
231 DECLARE_EVENT_TABLE()
232 };
233
234 BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
235 EVT_MOTION(wxListViewComboPopup::OnMouseMove)
236 EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
237 END_EVENT_TABLE()
238 @endcode
239
240 Here's how you would create and populate it in a dialog constructor:
241
242 @code
243 wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString);
244
245 wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
246
247 comboCtrl->SetPopupControl(popupCtrl);
248
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"));
253 @endcode
254
255 @beginStyleTable
256 @style{wxCB_READONLY}:
257 Text will not be editable.
258 @style{wxCB_SORT}:
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
264 only.
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.
272 @endStyleTable
273
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
279 the combo control.
280 @endEventTable
281
282 @library{wxbase}
283 @category{ctrl}
284 @appearance{comboctrl.png}
285
286 @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent
287 */
288 class wxComboCtrl : public wxControl
289 {
290 public:
291 //@{
292 /**
293 Constructor, creating and showing a combo control.
294
295 @param parent
296 Parent window. Must not be @NULL.
297 @param id
298 Window identifier. The value wxID_ANY indicates a default value.
299 @param value
300 Initial selection string. An empty string indicates no selection.
301 @param pos
302 Window position.
303 @param size
304 Window size. If wxDefaultSize is specified then the window is
305 sized
306 appropriately.
307 @param style
308 Window style. See wxComboCtrl.
309 @param validator
310 Window validator.
311 @param name
312 Window name.
313
314 @see Create(), wxValidator
315 */
316 wxComboCtrl();
317 wxComboCtrl(wxWindow* parent, wxWindowID id,
318 const wxString& value = "",
319 const wxPoint& pos = wxDefaultPosition,
320 const wxSize& size = wxDefaultSize,
321 long style = 0,
322 const wxValidator& validator = wxDefaultValidator,
323 const wxString& name = "comboCtrl");
324 //@}
325
326 /**
327 Destructor, destroying the combo control.
328 */
329 ~wxComboCtrl();
330
331 /**
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.
335
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.
339 */
340 virtual bool AnimateShow(const wxRect& rect, int flags);
341
342 /**
343 Copies the selected text to the clipboard.
344 */
345 void Copy();
346
347 /**
348 Creates the combo control for two-step construction. Derived classes
349 should call or replace this function. See wxComboCtrl()
350 for further details.
351 */
352 bool Create(wxWindow* parent, wxWindowID id,
353 const wxString& value = "",
354 const wxPoint& pos = wxDefaultPosition,
355 const wxSize& size = wxDefaultSize,
356 long style = 0,
357 const wxValidator& validator = wxDefaultValidator,
358 const wxString& name = "comboCtrl");
359
360 /**
361 Copies the selected text to the clipboard and removes the selection.
362 */
363 void Cut();
364
365 /**
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.
372 */
373 void DoSetPopupControl(wxComboPopup* popup);
374
375 /**
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).
381
382 @param rect
383 Position to show the popup window at, in screen coordinates.
384 @param flags
385 Combination of any of the following:
386 */
387 virtual void DoShowPopup(const wxRect& rect, int flags);
388
389 /**
390 Enables or disables popup animation, if any, depending on the value of
391 the argument.
392 */
393 void EnablePopupAnimation(bool enable = true);
394
395 /**
396 Returns disabled button bitmap that has been set with
397 SetButtonBitmaps().
398
399 @returns A reference to the disabled state bitmap.
400 */
401 const wxBitmap GetBitmapDisabled() const;
402
403 /**
404 Returns button mouse hover bitmap that has been set with
405 SetButtonBitmaps().
406
407 @returns A reference to the mouse hover state bitmap.
408 */
409 const wxBitmap GetBitmapHover() const;
410
411 /**
412 Returns default button bitmap that has been set with
413 SetButtonBitmaps().
414
415 @returns A reference to the normal state bitmap.
416 */
417 const wxBitmap GetBitmapNormal() const;
418
419 /**
420 Returns depressed button bitmap that has been set with
421 SetButtonBitmaps().
422
423 @returns A reference to the depressed state bitmap.
424 */
425 const wxBitmap GetBitmapPressed() const;
426
427 /**
428 Returns current size of the dropdown button.
429 */
430 wxSize GetButtonSize();
431
432 /**
433 Returns custom painted area in control.
434
435 @see SetCustomPaintWidth().
436 */
437 int GetCustomPaintWidth() const;
438
439 /**
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).
443
444 @returns Value returned is a combination of following flags:
445 */
446 static int GetFeatures();
447
448 /**
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.
452 */
453 long GetInsertionPoint() const;
454
455 /**
456 Returns the last position in the combo control text field.
457 */
458 long GetLastPosition() const;
459
460 /**
461 Returns current popup interface that has been set with SetPopupControl.
462 */
463 wxComboPopup* GetPopupControl();
464
465 /**
466 Returns popup window containing the popup control.
467 */
468 wxWindow* GetPopupWindow() const;
469
470 /**
471 Get the text control which is part of the combo control.
472 */
473 wxTextCtrl* GetTextCtrl() const;
474
475 /**
476 Returns actual indentation in pixels.
477 */
478 wxCoord GetTextIndent() const;
479
480 /**
481 Returns area covered by the text field (includes everything except
482 borders and the dropdown button).
483 */
484 const wxRect GetTextRect() const;
485
486 /**
487 Returns text representation of the current value. For writable
488 combo control it always returns the value in the text field.
489 */
490 wxString GetValue() const;
491
492 /**
493 Dismisses the popup window.
494 */
495 void HidePopup();
496
497 /**
498 Returns @true if the popup is currently shown
499 */
500 bool IsPopupShown() const;
501
502 /**
503 Returns @true if the popup window is in the given state.
504 Possible values are:
505
506 @c Hidden()
507
508 Popup window is hidden.
509
510 @c Animating()
511
512 Popup window is being shown, but the
513 popup animation has not yet finished.
514
515 @c Visible()
516
517 Popup window is fully visible.
518 */
519 bool IsPopupWindowState(int state) const;
520
521 /**
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
528 return @NULL.
529 */
530 void OnButtonClick();
531
532 /**
533 Pastes text from the clipboard to the text field.
534 */
535 void Paste();
536
537 /**
538 Removes the text between the two positions in the combo control text field.
539
540 @param from
541 The first position.
542 @param to
543 The last position.
544 */
545 void Remove(long from, long to);
546
547 /**
548 Replaces the text between two positions with the given text, in the combo
549 control text field.
550
551 @param from
552 The first position.
553 @param to
554 The second position.
555 @param text
556 The text to insert.
557 */
558 void Replace(long from, long to, const wxString& value);
559
560 /**
561 Sets custom dropdown button graphics.
562
563 @param bmpNormal
564 Default button image.
565 @param pushButtonBg
566 If @true, blank push button background is painted
567 below the image.
568 @param bmpPressed
569 Depressed button image.
570 @param bmpHover
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.
574 @param bmpDisabled
575 Disabled button image.
576 */
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);
582
583 /**
584 Sets size and position of dropdown button.
585
586 @param width
587 Button width. Value = 0 specifies default.
588 @param height
589 Button height. Value = 0 specifies default.
590 @param side
591 Indicates which side the button will be placed.
592 Value can be wxLEFT or wxRIGHT.
593 @param spacingX
594 Horizontal spacing around the button. Default is 0.
595 */
596 void SetButtonPosition(int width = -1, int height = -1,
597 int side = wxRIGHT,
598 int spacingX = 0);
599
600 /**
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.
604 */
605 void SetCustomPaintWidth(int width);
606
607 /**
608 Sets the insertion point in the text field.
609
610 @param pos
611 The new insertion point.
612 */
613 void SetInsertionPoint(long pos);
614
615 /**
616 Sets the insertion point at the end of the combo control text field.
617 */
618 void SetInsertionPointEnd();
619
620 /**
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).
624 */
625 void SetPopupAnchor(int anchorSide);
626
627 /**
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()
631 has been overridden.
632 */
633 void SetPopupControl(wxComboPopup* popup);
634
635 /**
636 Extends popup size horizontally, relative to the edges of the combo control.
637
638 @param extLeft
639 How many pixel to extend beyond the left edge of the
640 control. Default is 0.
641 @param extRight
642 How many pixel to extend beyond the right edge of the
643 control. Default is 0.
644
645 @remarks Popup minimum width may override arguments.
646 */
647 void SetPopupExtents(int extLeft, int extRight);
648
649 /**
650 Sets preferred maximum height of the popup.
651
652 @remarks Value -1 indicates the default.
653 */
654 void SetPopupMaxHeight(int height);
655
656 /**
657 Sets minimum width of the popup. If wider than combo control, it will extend to
658 the left.
659
660 @remarks Value -1 indicates the default.
661 */
662 void SetPopupMinWidth(int width);
663
664 /**
665 Selects the text between the two positions, in the combo control text field.
666
667 @param from
668 The first position.
669 @param to
670 The second position.
671 */
672 void SetSelection(long from, long to);
673
674 /**
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.
678 */
679 void SetText(const wxString& value);
680
681 /**
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.
685 */
686 void SetTextIndent(int indent);
687
688 /**
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
693 */
694 void SetValue(const wxString& value);
695
696 /**
697 Same as SetValue, but also sends wxCommandEvent of type
698 wxEVT_COMMAND_TEXT_UPDATED
699 if @c withEvent is @true.
700 */
701 void SetValueWithEvent(const wxString& value,
702 bool withEvent = true);
703
704 /**
705 Show the popup.
706 */
707 void ShowPopup();
708
709 /**
710 Undoes the last edit in the text field. Windows only.
711 */
712 void Undo();
713
714 /**
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.
720 */
721 void UseAltPopupWindow(bool enable = true);
722 };
723