interface/combo.h

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