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