interface/wx/combo.h

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