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