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