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