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 protected:
 135     /**
 136         Parent wxComboCtrl. This member variable is prepared automatically
 137         before Init() 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
 174     A combo control is a generic combobox that allows totally custom popup. In
 175     addition it has other customization features. For instance, position and
 176     size of the dropdown button can be changed.
 177
 178     @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl
 179
 180     wxComboCtrl needs to be told somehow which control to use and this is done
 181     by SetPopupControl(). However, we need something more than just a wxControl
 182     in this method as, for example, we need to call
 183     SetStringValue("initial text value") and wxControl doesn't have such
 184     method. So we also need a wxComboPopup which is an interface which must be
 185     implemented by a control to be usable as a popup.
 186
 187     We couldn't derive wxComboPopup from wxControl as this would make it
 188     impossible to have a class deriving from a wxWidgets control and from it,
 189     so instead it is just a mix-in.
 190
 191     Here's a minimal sample of wxListView popup:
 192
 193     @code
 194     #include <wx/combo.h>
 195     #include <wx/listctrl.h>
 196
 197     class wxListViewComboPopup : public wxListView, public wxComboPopup
 198     {
 199     public:
 200         // Initialize member variables
 201         virtual void Init()
 202         {
 203             m_value = -1;
 204         }
 205
 206         // Create popup control
 207         virtual bool Create(wxWindow* parent)
 208         {
 209             return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize);
 210         }
 211
 212         // Return pointer to the created control
 213         virtual wxWindow *GetControl() { return this; }
 214
 215         // Translate string into a list selection
 216         virtual void SetStringValue(const wxString& s)
 217         {
 218             int n = wxListView::FindItem(-1,s);
 219             if ( n >= 0 && n < wxListView::GetItemCount() )
 220                 wxListView::Select(n);
 221         }
 222
 223         // Get list selection as a string
 224         virtual wxString GetStringValue() const
 225         {
 226             if ( m_value >= 0 )
 227             return wxListView::GetItemText(m_value);
 228             return wxEmptyString;
 229         }
 230
 231         // Do mouse hot-tracking (which is typical in list popups)
 232         void OnMouseMove(wxMouseEvent& event)
 233         {
 234             // TODO: Move selection to cursor
 235         }
 236
 237         // On mouse left up, set the value and close the popup
 238         void OnMouseClick(wxMouseEvent& WXUNUSED(event))
 239         {
 240             m_value = wxListView::GetFirstSelected();
 241
 242             // TODO: Send event as well
 243
 244             Dismiss();
 245         }
 246
 247     protected:
 248
 249         int m_value; // current item index
 250
 251     private:
 252         DECLARE_EVENT_TABLE()
 253     };
 254
 255     BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
 256         EVT_MOTION(wxListViewComboPopup::OnMouseMove)
 257         EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
 258     END_EVENT_TABLE()
 259     @endcode
 260
 261     Here's how you would create and populate it in a dialog constructor:
 262
 263     @code
 264     wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString);
 265
 266     wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
 267
 268     // It is important to call SetPopupControl() as soon as possible
 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     @beginEventEmissionTable{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 = wxID_ANY,
 343                 const wxString& value = wxEmptyString,
 344                 const wxPoint& pos = wxDefaultPosition,
 345                 const wxSize& size = wxDefaultSize,
 346                 long style = 0,
 347                 const wxValidator& validator = wxDefaultValidator,
 348                 const wxString& name = wxComboBoxNameStr);
 349
 350     /**
 351         Destructor, destroying the combo control.
 352     */
 353     virtual ~wxComboCtrl();
 354
 355     /**
 356         Copies the selected text to the clipboard.
 357     */
 358     virtual void Copy();
 359
 360     /**
 361         Creates the combo control for two-step construction. Derived classes
 362         should call or replace this function. See wxComboCtrl() for further
 363         details.
 364     */
 365     bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
 366                 const wxString& value = wxEmptyString,
 367                 const wxPoint& pos = wxDefaultPosition,
 368                 const wxSize& size = wxDefaultSize,
 369                 long style = 0,
 370                 const wxValidator& validator = wxDefaultValidator,
 371                 const wxString& name = wxComboBoxNameStr);
 372
 373     /**
 374         Copies the selected text to the clipboard and removes the selection.
 375     */
 376     virtual void Cut();
 377
 378     /**
 379         Enables or disables popup animation, if any, depending on the value of
 380         the argument.
 381     */
 382     void EnablePopupAnimation(bool enable = true);
 383
 384     /**
 385         Returns disabled button bitmap that has been set with
 386         SetButtonBitmaps().
 387
 388         @return A reference to the disabled state bitmap.
 389     */
 390     const wxBitmap& GetBitmapDisabled() const;
 391
 392     /**
 393         Returns button mouse hover bitmap that has been set with
 394         SetButtonBitmaps().
 395
 396         @return A reference to the mouse hover state bitmap.
 397     */
 398     const wxBitmap& GetBitmapHover() const;
 399
 400     /**
 401         Returns default button bitmap that has been set with
 402         SetButtonBitmaps().
 403
 404         @return A reference to the normal state bitmap.
 405     */
 406     const wxBitmap& GetBitmapNormal() const;
 407
 408     /**
 409         Returns depressed button bitmap that has been set with
 410         SetButtonBitmaps().
 411
 412         @return A reference to the depressed state bitmap.
 413     */
 414     const wxBitmap& GetBitmapPressed() const;
 415
 416     /**
 417         Returns current size of the dropdown button.
 418     */
 419     wxSize GetButtonSize();
 420
 421     /**
 422         Returns custom painted area in control.
 423
 424         @see SetCustomPaintWidth().
 425     */
 426     int GetCustomPaintWidth() const;
 427
 428     /**
 429         Returns features supported by wxComboCtrl. If needed feature is
 430         missing, you need to instead use wxGenericComboCtrl, which however may
 431         lack a native look and feel (but otherwise sports identical API).
 432
 433         @return Value returned is a combination of the flags defined in
 434                 wxComboCtrlFeatures.
 435     */
 436     static int GetFeatures();
 437
 438     /**
 439         Returns the insertion point for the combo control's text field.
 440
 441         @note Under Windows, this function always returns 0 if the combo
 442               control doesn't have the focus.
 443     */
 444     virtual long GetInsertionPoint() const;
 445
 446     /**
 447         Returns the last position in the combo control text field.
 448     */
 449     virtual long GetLastPosition() const;
 450
 451     /**
 452         Returns current popup interface that has been set with
 453         SetPopupControl().
 454     */
 455     wxComboPopup* GetPopupControl();
 456
 457     /**
 458         Returns popup window containing the popup control.
 459     */
 460     wxWindow* GetPopupWindow() const;
 461
 462     /**
 463         Get the text control which is part of the combo control.
 464     */
 465     wxTextCtrl* GetTextCtrl() const;
 466
 467     /**
 468         Returns actual indentation in pixels.
 469     */
 470     wxCoord GetTextIndent() const;
 471
 472     /**
 473         Returns area covered by the text field (includes everything except
 474         borders and the dropdown button).
 475     */
 476     const wxRect& GetTextRect() const;
 477
 478     /**
 479         Returns text representation of the current value. For writable combo
 480         control it always returns the value in the text field.
 481     */
 482     virtual wxString GetValue() const;
 483
 484     /**
 485         Dismisses the popup window.
 486     */
 487     virtual void HidePopup();
 488
 489     /**
 490         Returns @true if the popup is currently shown
 491     */
 492     bool IsPopupShown() const;
 493
 494     /**
 495         Returns @true if the popup window is in the given state. Possible
 496         values are:
 497
 498         @beginTable
 499         @row2col{wxComboCtrl::Hidden,    Popup window is hidden.}
 500         @row2col{wxComboCtrl::Animating, Popup window is being shown, but the
 501                                          popup animation has not yet finished.}
 502         @row2col{wxComboCtrl::Visible,   Popup window is fully visible.}
 503         @endTable
 504     */
 505     bool IsPopupWindowState(int state) const;
 506
 507     /**
 508         Implement in a derived class to define what happens on dropdown button
 509         click. Default action is to show the popup.
 510
 511         @note If you implement this to do something else than show the popup,
 512               you must then also implement DoSetPopupControl() to always return
 513               @NULL.
 514     */
 515     virtual void OnButtonClick();
 516
 517     /**
 518         Pastes text from the clipboard to the text field.
 519     */
 520     virtual void Paste();
 521
 522     /**
 523         Removes the text between the two positions in the combo control text
 524         field.
 525
 526         @param from
 527             The first position.
 528         @param to
 529             The last position.
 530     */
 531     virtual void Remove(long from, long to);
 532
 533     /**
 534         Replaces the text between two positions with the given text, in the
 535         combo control text field.
 536
 537         @param from
 538             The first position.
 539         @param to
 540             The second position.
 541         @param text
 542             The text to insert.
 543     */
 544     virtual void Replace(long from, long to, const wxString& text);
 545
 546     /**
 547         Sets custom dropdown button graphics.
 548
 549         @param bmpNormal
 550             Default button image.
 551         @param pushButtonBg
 552             If @true, blank push button background is painted below the image.
 553         @param bmpPressed
 554             Depressed button image.
 555         @param bmpHover
 556             Button image when mouse hovers above it. This should be ignored on
 557             platforms and themes that do not generally draw different kind of
 558             button on mouse hover.
 559         @param bmpDisabled
 560             Disabled button image.
 561     */
 562     void SetButtonBitmaps(const wxBitmap& bmpNormal,
 563                           bool pushButtonBg = false,
 564                           const wxBitmap& bmpPressed = wxNullBitmap,
 565                           const wxBitmap& bmpHover = wxNullBitmap,
 566                           const wxBitmap& bmpDisabled = wxNullBitmap);
 567
 568     /**
 569         Sets size and position of dropdown button.
 570
 571         @param width
 572             Button width. Value = 0 specifies default.
 573         @param height
 574             Button height. Value = 0 specifies default.
 575         @param side
 576             Indicates which side the button will be placed. Value can be wxLEFT
 577             or wxRIGHT.
 578         @param spacingX
 579             Horizontal spacing around the button. Default is 0.
 580     */
 581     void SetButtonPosition(int width = -1, int height = -1,
 582                            int side = wxRIGHT, int spacingX = 0);
 583
 584     /**
 585         Set width, in pixels, of custom painted area in control without
 586         @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used
 587         to indicate area that is not covered by the focus rectangle.
 588     */
 589     void SetCustomPaintWidth(int width);
 590
 591     /**
 592         Sets the insertion point in the text field.
 593
 594         @param pos
 595             The new insertion point.
 596     */
 597     virtual void SetInsertionPoint(long pos);
 598
 599     /**
 600         Sets the insertion point at the end of the combo control text field.
 601     */
 602     virtual void SetInsertionPointEnd();
 603
 604     /**
 605         Set side of the control to which the popup will align itself. Valid
 606         values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that
 607         the most appropriate side is used (which, currently, is always
 608         @c wxLEFT).
 609     */
 610     void SetPopupAnchor(int anchorSide);
 611
 612     /**
 613         Set popup interface class derived from wxComboPopup. This method should
 614         be called as soon as possible after the control has been created,
 615         unless OnButtonClick() has been overridden.
 616     */
 617     void SetPopupControl(wxComboPopup* popup);
 618
 619     /**
 620         Extends popup size horizontally, relative to the edges of the combo
 621         control.
 622
 623         @param extLeft
 624             How many pixel to extend beyond the left edge of the control.
 625             Default is 0.
 626         @param extRight
 627             How many pixel to extend beyond the right edge of the control.
 628             Default is 0.
 629
 630         @remarks Popup minimum width may override arguments. It is up to the
 631                  popup to fully take this into account.
 632     */
 633     void SetPopupExtents(int extLeft, int extRight);
 634
 635     /**
 636         Sets preferred maximum height of the popup.
 637
 638         @remarks Value -1 indicates the default.
 639     */
 640     void SetPopupMaxHeight(int height);
 641
 642     /**
 643         Sets minimum width of the popup. If wider than combo control, it will
 644         extend to the left.
 645
 646         @remarks Value -1 indicates the default. Also, popup implementation may
 647                  choose to ignore this.
 648     */
 649     void SetPopupMinWidth(int width);
 650
 651     /**
 652         Selects the text between the two positions, in the combo control text
 653         field.
 654
 655         @param from
 656             The first position.
 657         @param to
 658             The second position.
 659     */
 660     virtual void SetSelection(long from, long to);
 661
 662     /**
 663         Sets the text for the text field without affecting the popup. Thus,
 664         unlike SetValue(), it works equally well with combo control using
 665         @c wxCB_READONLY style.
 666     */
 667     void SetText(const wxString& value);
 668
 669     /**
 670         This will set the space in pixels between left edge of the control and
 671         the text, regardless whether control is read-only or not. Value -1 can
 672         be given to indicate platform default.
 673     */
 674     void SetTextIndent(int indent);
 675
 676     /**
 677         Sets the text for the combo control text field.
 678
 679         @note For a combo control with @c wxCB_READONLY style the string must
 680               be accepted by the popup (for instance, exist in the dropdown
 681               list), otherwise the call to SetValue() is ignored.
 682     */
 683     virtual void SetValue(const wxString& value);
 684
 685     /**
 686         Same as SetValue(), but also sends wxCommandEvent of type
 687         wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.
 688     */
 689     void SetValueWithEvent(const wxString& value, bool withEvent = true);
 690
 691     /**
 692         Show the popup.
 693     */
 694     virtual void ShowPopup();
 695
 696     /**
 697         Undoes the last edit in the text field. Windows only.
 698     */
 699     virtual void Undo();
 700
 701     /**
 702         Enable or disable usage of an alternative popup window, which
 703         guarantees ability to focus the popup control, and allows common native
 704         controls to function normally. This alternative popup window is usually
 705         a wxDialog, and as such, when it is shown, its parent top-level window
 706         will appear as if the focus has been lost from it.
 707     */
 708     void UseAltPopupWindow(bool enable = true);
 709
 710 protected:
 711
 712     /**
 713         This member function is not normally called in application code.
 714         Instead, it can be implemented in a derived class to create a custom
 715         popup animation.
 716
 717         The parameters are the same as those for DoShowPopup().
 718
 719         @return @true if animation finishes before the function returns,
 720                 @false otherwise. In the latter case you need to manually call
 721                 DoShowPopup() after the animation ends.
 722     */
 723     virtual bool AnimateShow(const wxRect& rect, int flags);
 724
 725     /**
 726         This member function is not normally called in application code.
 727         Instead, it can be implemented in a derived class to return default
 728         wxComboPopup, incase @a popup is @NULL.
 729
 730         @note If you have implemented OnButtonClick() to do something else than
 731               show the popup, then DoSetPopupControl() must always set @a popup
 732               to @NULL.
 733     */
 734     virtual void DoSetPopupControl(wxComboPopup* popup);
 735
 736     /**
 737         This member function is not normally called in application code.
 738         Instead, it must be called in a derived class to make sure popup is
 739         properly shown after a popup animation has finished (but only if
 740         AnimateShow() did not finish the animation within its function scope).
 741
 742         @param rect
 743             Position to show the popup window at, in screen coordinates.
 744         @param flags
 745             Combination of any of the following:
 746             @beginTable
 747             @row2col{wxComboCtrl::ShowAbove,
 748                      Popup is shown above the control instead of below.}
 749             @row2col{wxComboCtrl::CanDeferShow,
 750                      Showing the popup can be deferred to happen sometime after
 751                      ShowPopup() has finished. In this case, AnimateShow() must
 752                      return false.}
 753             @endTable
 754     */
 755     virtual void DoShowPopup(const wxRect& rect, int flags);
 756 };
 757