interface/combo.h

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