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