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