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