interface/combo.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        combo.h
   3 // Purpose:     documentation for wxComboPopup class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxComboPopup
  11     @wxheader{combo.h}
  12
  13     In order to use a custom popup with wxComboCtrl,
  14     an interface class must be derived from wxComboPopup. For more information
  15     how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for
  16     wxComboCtrl".
  17
  18     @library{wxcore}
  19     @category{FIXME}
  20
  21     @seealso
  22     wxComboCtrl
  23 */
  24 class wxComboPopup
  25 {
  26 public:
  27     /**
  28         Default constructor. It is recommended that internal variables
  29         are prepared in Init() instead
  30         (because @ref mcombo() m_combo is not valid in constructor).
  31     */
  32     wxComboPopup();
  33
  34     /**
  35         The derived class must implement this to create the popup control.
  36
  37         @returns @true if the call succeeded, @false otherwise.
  38     */
  39     bool Create(wxWindow* parent);
  40
  41     /**
  42         Utility function that hides the popup.
  43     */
  44     void Dismiss();
  45
  46     /**
  47         The derived class may implement this to return adjusted size
  48         for the popup control, according to the variables given.
  49
  50         @param minWidth
  51             Preferred minimum width.
  52         @param prefHeight
  53             Preferred height. May be -1 to indicate
  54             no preference.
  55         @param maxWidth
  56             Max height for window, as limited by
  57             screen size.
  58
  59         @remarks Called each time popup is about to be shown.
  60     */
  61     wxSize GetAdjustedSize(int minWidth, int prefHeight,
  62                            int maxHeight);
  63
  64     /**
  65         The derived class must implement this to return pointer
  66         to the associated control created in Create().
  67     */
  68     wxWindow* GetControl();
  69
  70     /**
  71         The derived class must implement this to return
  72         string representation of the value.
  73     */
  74     wxString GetStringValue() const;
  75
  76     /**
  77         The derived class must implement this to initialize
  78         its internal variables. This method is called immediately
  79         after construction finishes. @ref mcombo() m_combo
  80         member variable has been initialized before the call.
  81     */
  82     void Init();
  83
  84     /**
  85         Utility method that returns @true if Create has been called.
  86         Useful in conjunction with LazyCreate().
  87     */
  88     bool IsCreated() const;
  89
  90     /**
  91         The derived class may implement this to return
  92         @true if it wants to delay call to Create()
  93         until the popup is shown for the first time. It is more
  94         efficient, but on the other hand it is often more convenient
  95         to have the control created immediately.
  96
  97         @remarks Base implementation returns @false.
  98     */
  99     bool LazyCreate();
 100
 101     /**
 102         The derived class may implement this to do something
 103         when the parent wxComboCtrl gets double-clicked.
 104     */
 105     void OnComboDoubleClick();
 106
 107     /**
 108         The derived class may implement this to receive
 109         key events from the parent wxComboCtrl.
 110         Events not handled should be skipped, as usual.
 111     */
 112     void OnComboKeyEvent(wxKeyEvent& event);
 113
 114     /**
 115         The derived class may implement this to do
 116         special processing when popup is hidden.
 117     */
 118     void OnDismiss();
 119
 120     /**
 121         The derived class may implement this to do
 122         special processing when popup is shown.
 123     */
 124     void OnPopup();
 125
 126     /**
 127         The derived class may implement this to paint
 128         the parent wxComboCtrl.
 129         Default implementation draws value as string.
 130     */
 131     void PaintComboControl(wxDC& dc, const wxRect& rect);
 132
 133     /**
 134         The derived class must implement this to receive
 135         string value changes from wxComboCtrl.
 136     */
 137     void SetStringValue(const wxString& value);
 138
 139     /**
 140         wxComboCtrl m_combo
 141         Parent wxComboCtrl. This is parameter has
 142         been prepared before Init() is called.
 143     */
 144 };
 145
 146
 147 /**
 148     @class wxComboCtrl
 149     @wxheader{combo.h}
 150
 151     A combo control is a generic combobox that allows totally
 152     custom popup. In addition it has other customization features.
 153     For instance, position and size of the dropdown button
 154     can be changed.
 155
 156     @beginStyleTable
 157     @style{wxCB_READONLY}:
 158            Text will not be editable.
 159     @style{wxCB_SORT}:
 160            Sorts the entries in the list alphabetically.
 161     @style{wxTE_PROCESS_ENTER}:
 162            The control will generate the event wxEVT_COMMAND_TEXT_ENTER
 163            (otherwise pressing Enter key is either processed internally by the
 164            control or used for navigation between dialog controls). Windows
 165            only.
 166     @style{wxCC_SPECIAL_DCLICK}:
 167            Double-clicking triggers a call to popup's OnComboDoubleClick.
 168            Actual behaviour is defined by a derived class. For instance,
 169            wxOwnerDrawnComboBox will cycle an item. This style only applies if
 170            wxCB_READONLY is used as well.
 171     @style{wxCC_STD_BUTTON}:
 172            Drop button will behave more like a standard push button.
 173     @endStyleTable
 174
 175     @beginEventTable
 176     @event{EVT_TEXT(id, func)}:
 177            Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes.
 178     @event{EVT_TEXT_ENTER(id, func)}:
 179            Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
 180            the combo control.
 181     @endEventTable
 182
 183     @library{wxbase}
 184     @category{ctrl}
 185     @appearance{comboctrl.png}
 186
 187     @seealso
 188     wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent
 189 */
 190 class wxComboCtrl : public wxControl
 191 {
 192 public:
 193     //@{
 194     /**
 195         Constructor, creating and showing a combo control.
 196
 197         @param parent
 198             Parent window. Must not be @NULL.
 199         @param id
 200             Window identifier. The value wxID_ANY indicates a default value.
 201         @param value
 202             Initial selection string. An empty string indicates no selection.
 203         @param pos
 204             Window position.
 205         @param size
 206             Window size. If wxDefaultSize is specified then the window is
 207         sized
 208             appropriately.
 209         @param style
 210             Window style. See wxComboCtrl.
 211         @param validator
 212             Window validator.
 213         @param name
 214             Window name.
 215
 216         @see Create(), wxValidator
 217     */
 218     wxComboCtrl();
 219     wxComboCtrl(wxWindow* parent, wxWindowID id,
 220                 const wxString& value = "",
 221                 const wxPoint& pos = wxDefaultPosition,
 222                 const wxSize& size = wxDefaultSize,
 223                 long style = 0,
 224                 const wxValidator& validator = wxDefaultValidator,
 225                 const wxString& name = "comboCtrl");
 226     //@}
 227
 228     /**
 229         Destructor, destroying the combo control.
 230     */
 231     ~wxComboCtrl();
 232
 233     /**
 234         This member function is not normally called in application code.
 235         Instead, it can be implemented in a derived class to create a
 236         custom popup animation.
 237
 238         @returns @true if animation finishes before the function returns. @false
 239                  otherwise. In the latter case you need to manually call
 240                  DoShowPopup after the animation ends.
 241     */
 242     virtual bool AnimateShow(const wxRect& rect, int flags);
 243
 244     /**
 245         Copies the selected text to the clipboard.
 246     */
 247     void Copy();
 248
 249     /**
 250         Creates the combo control for two-step construction. Derived classes
 251         should call or replace this function. See wxComboCtrl()
 252         for further details.
 253     */
 254     bool Create(wxWindow* parent, wxWindowID id,
 255                 const wxString& value = "",
 256                 const wxPoint& pos = wxDefaultPosition,
 257                 const wxSize& size = wxDefaultSize,
 258                 long style = 0,
 259                 const wxValidator& validator = wxDefaultValidator,
 260                 const wxString& name = "comboCtrl");
 261
 262     /**
 263         Copies the selected text to the clipboard and removes the selection.
 264     */
 265     void Cut();
 266
 267     /**
 268         This member function is not normally called in application code.
 269         Instead, it can be implemented in a derived class to return
 270         default wxComboPopup, incase @c popup is @NULL.
 271         @b Note: If you have implemented OnButtonClick to do
 272         something else than show the popup, then DoSetPopupControl
 273         must always return @NULL.
 274     */
 275     void DoSetPopupControl(wxComboPopup* popup);
 276
 277     /**
 278         This member function is not normally called in application code.
 279         Instead, it must be called in a derived class to make sure popup
 280         is properly shown after a popup animation has finished (but only
 281         if AnimateShow() did not finish
 282         the animation within it's function scope).
 283
 284         @param rect
 285             Position to show the popup window at, in screen coordinates.
 286         @param flags
 287             Combination of any of the following:
 288     */
 289     virtual void DoShowPopup(const wxRect& rect, int flags);
 290
 291     /**
 292         Enables or disables popup animation, if any, depending on the value of
 293         the argument.
 294     */
 295     void EnablePopupAnimation(bool enable = true);
 296
 297     /**
 298         Returns disabled button bitmap that has been set with
 299         SetButtonBitmaps().
 300
 301         @returns A reference to the disabled state bitmap.
 302     */
 303     const wxBitmap GetBitmapDisabled() const;
 304
 305     /**
 306         Returns button mouse hover bitmap that has been set with
 307         SetButtonBitmaps().
 308
 309         @returns A reference to the mouse hover state bitmap.
 310     */
 311     const wxBitmap GetBitmapHover() const;
 312
 313     /**
 314         Returns default button bitmap that has been set with
 315         SetButtonBitmaps().
 316
 317         @returns A reference to the normal state bitmap.
 318     */
 319     const wxBitmap GetBitmapNormal() const;
 320
 321     /**
 322         Returns depressed button bitmap that has been set with
 323         SetButtonBitmaps().
 324
 325         @returns A reference to the depressed state bitmap.
 326     */
 327     const wxBitmap GetBitmapPressed() const;
 328
 329     /**
 330         Returns current size of the dropdown button.
 331     */
 332     wxSize GetButtonSize();
 333
 334     /**
 335         Returns custom painted area in control.
 336
 337         @see SetCustomPaintWidth().
 338     */
 339     int GetCustomPaintWidth() const;
 340
 341     /**
 342         Returns features supported by wxComboCtrl. If needed feature is missing,
 343         you need to instead use wxGenericComboCtrl, which however may lack
 344         native look and feel (but otherwise sports identical API).
 345
 346         @returns Value returned is a combination of following flags:
 347     */
 348     static int GetFeatures();
 349
 350     /**
 351         Returns the insertion point for the combo control's text field.
 352         @b Note: Under wxMSW, this function always returns 0 if the combo control
 353         doesn't have the focus.
 354     */
 355     long GetInsertionPoint() const;
 356
 357     /**
 358         Returns the last position in the combo control text field.
 359     */
 360     long GetLastPosition() const;
 361
 362     /**
 363         Returns current popup interface that has been set with SetPopupControl.
 364     */
 365     wxComboPopup* GetPopupControl();
 366
 367     /**
 368         Returns popup window containing the popup control.
 369     */
 370     wxWindow* GetPopupWindow() const;
 371
 372     /**
 373         Get the text control which is part of the combo control.
 374     */
 375     wxTextCtrl* GetTextCtrl() const;
 376
 377     /**
 378         Returns actual indentation in pixels.
 379     */
 380     wxCoord GetTextIndent() const;
 381
 382     /**
 383         Returns area covered by the text field (includes everything except
 384         borders and the dropdown button).
 385     */
 386     const wxRect GetTextRect() const;
 387
 388     /**
 389         Returns text representation of the current value. For writable
 390         combo control it always returns the value in the text field.
 391     */
 392     wxString GetValue() const;
 393
 394     /**
 395         Dismisses the popup window.
 396     */
 397     void HidePopup();
 398
 399     /**
 400         Returns @true if the popup is currently shown
 401     */
 402     bool IsPopupShown() const;
 403
 404     /**
 405         Returns @true if the popup window is in the given state.
 406         Possible values are:
 407
 408         @c Hidden()
 409
 410         Popup window is hidden.
 411
 412         @c Animating()
 413
 414         Popup window is being shown, but the
 415         popup animation has not yet finished.
 416
 417         @c Visible()
 418
 419         Popup window is fully visible.
 420     */
 421     bool IsPopupWindowState(int state) const;
 422
 423     /**
 424         Implement in a derived class to define what happens on
 425         dropdown button click.
 426         Default action is to show the popup.
 427         @b Note: If you implement this to do something else than
 428         show the popup, you must then also implement
 429         DoSetPopupControl() to always
 430         return @NULL.
 431     */
 432     void OnButtonClick();
 433
 434     /**
 435         Pastes text from the clipboard to the text field.
 436     */
 437     void Paste();
 438
 439     /**
 440         Removes the text between the two positions in the combo control text field.
 441
 442         @param from
 443             The first position.
 444         @param to
 445             The last position.
 446     */
 447     void Remove(long from, long to);
 448
 449     /**
 450         Replaces the text between two positions with the given text, in the combo
 451         control text field.
 452
 453         @param from
 454             The first position.
 455         @param to
 456             The second position.
 457         @param text
 458             The text to insert.
 459     */
 460     void Replace(long from, long to, const wxString& value);
 461
 462     /**
 463         Sets custom dropdown button graphics.
 464
 465         @param bmpNormal
 466             Default button image.
 467         @param pushButtonBg
 468             If @true, blank push button background is painted
 469             below the image.
 470         @param bmpPressed
 471             Depressed button image.
 472         @param bmpHover
 473             Button image when mouse hovers above it. This
 474             should be ignored on platforms and themes that do not generally draw
 475             different kind of button on mouse hover.
 476         @param bmpDisabled
 477             Disabled button image.
 478     */
 479     void SetButtonBitmaps(const wxBitmap& bmpNormal,
 480                           bool pushButtonBg = false,
 481                           const wxBitmap& bmpPressed = wxNullBitmap,
 482                           const wxBitmap& bmpHover = wxNullBitmap,
 483                           const wxBitmap& bmpDisabled = wxNullBitmap);
 484
 485     /**
 486         Sets size and position of dropdown button.
 487
 488         @param width
 489             Button width. Value = 0 specifies default.
 490         @param height
 491             Button height. Value = 0 specifies default.
 492         @param side
 493             Indicates which side the button will be placed.
 494             Value can be wxLEFT or wxRIGHT.
 495         @param spacingX
 496             Horizontal spacing around the button. Default is 0.
 497     */
 498     void SetButtonPosition(int width = -1, int height = -1,
 499                            int side = wxRIGHT,
 500                            int spacingX = 0);
 501
 502     /**
 503         Set width, in pixels, of custom painted area in control without @c wxCB_READONLY
 504         style. In read-only wxOwnerDrawnComboBox, this is used
 505         to indicate area that is not covered by the focus rectangle.
 506     */
 507     void SetCustomPaintWidth(int width);
 508
 509     /**
 510         Sets the insertion point in the text field.
 511
 512         @param pos
 513             The new insertion point.
 514     */
 515     void SetInsertionPoint(long pos);
 516
 517     /**
 518         Sets the insertion point at the end of the combo control text field.
 519     */
 520     void SetInsertionPointEnd();
 521
 522     /**
 523         Set side of the control to which the popup will align itself. Valid values are
 524         @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that the most appropriate
 525         side is used (which, currently, is always @c wxLEFT).
 526     */
 527     void SetPopupAnchor(int anchorSide);
 528
 529     /**
 530         Set popup interface class derived from wxComboPopup.
 531         This method should be called as soon as possible after the control
 532         has been created, unless OnButtonClick()
 533         has been overridden.
 534     */
 535     void SetPopupControl(wxComboPopup* popup);
 536
 537     /**
 538         Extends popup size horizontally, relative to the edges of the combo control.
 539
 540         @param extLeft
 541             How many pixel to extend beyond the left edge of the
 542             control. Default is 0.
 543         @param extRight
 544             How many pixel to extend beyond the right edge of the
 545             control. Default is 0.
 546
 547         @remarks Popup minimum width may override arguments.
 548     */
 549     void SetPopupExtents(int extLeft, int extRight);
 550
 551     /**
 552         Sets preferred maximum height of the popup.
 553
 554         @remarks Value -1 indicates the default.
 555     */
 556     void SetPopupMaxHeight(int height);
 557
 558     /**
 559         Sets minimum width of the popup. If wider than combo control, it will extend to
 560         the left.
 561
 562         @remarks Value -1 indicates the default.
 563     */
 564     void SetPopupMinWidth(int width);
 565
 566     /**
 567         Selects the text between the two positions, in the combo control text field.
 568
 569         @param from
 570             The first position.
 571         @param to
 572             The second position.
 573     */
 574     void SetSelection(long from, long to);
 575
 576     /**
 577         Sets the text for the text field without affecting the
 578         popup. Thus, unlike SetValue(), it works
 579         equally well with combo control using @c wxCB_READONLY style.
 580     */
 581     void SetText(const wxString& value);
 582
 583     /**
 584         This will set the space in pixels between left edge of the control and the
 585         text, regardless whether control is read-only or not. Value -1 can be
 586         given to indicate platform default.
 587     */
 588     void SetTextIndent(int indent);
 589
 590     /**
 591         Sets the text for the combo control text field.
 592         @b NB: For a combo control with @c wxCB_READONLY style the
 593         string must be accepted by the popup (for instance, exist in the dropdown
 594         list), otherwise the call to SetValue() is ignored
 595     */
 596     void SetValue(const wxString& value);
 597
 598     /**
 599         Same as SetValue, but also sends wxCommandEvent of type
 600         wxEVT_COMMAND_TEXT_UPDATED
 601         if @c withEvent is @true.
 602     */
 603     void SetValueWithEvent(const wxString& value,
 604                            bool withEvent = true);
 605
 606     /**
 607         Show the popup.
 608     */
 609     void ShowPopup();
 610
 611     /**
 612         Undoes the last edit in the text field. Windows only.
 613     */
 614     void Undo();
 615
 616     /**
 617         Enable or disable usage of an alternative popup window, which guarantees
 618         ability to focus the popup control, and allows common native controls to
 619         function normally. This alternative popup window is usually a wxDialog,
 620         and as such, when it is shown, its parent top-level window will appear
 621         as if the focus has been lost from it.
 622     */
 623     void UseAltPopupWindow(bool enable = true);
 624 };