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