interface/wx/ribbon/buttonbar.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/buttonbar.h
   3 // Purpose:     interface of wxRibbonButtonBar
   4 // Author:      Peter Cawley
   5 // Licence:     wxWindows licence
   6 ///////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     Flags for button bar button size and state.
  10
  11     Buttons on a ribbon button bar can each come in three sizes: small, medium,
  12     and large. In some places this is called the size class, and the term size
  13     used for the pixel width and height associated with a particular size
  14     class.
  15
  16     A button can also be in zero or more hovered or active states, or in the
  17     disabled state.
  18 */
  19 enum wxRibbonButtonBarButtonState
  20 {
  21     /**
  22         Button is small (the interpretation of small is dependent upon the art
  23         provider, but it will be smaller than medium).
  24     */
  25     wxRIBBON_BUTTONBAR_BUTTON_SMALL     = 0 << 0,
  26
  27     /**
  28         Button is medium sized (the interpretation of medium is dependent upon
  29         the art provider, but it will be between small and large).
  30     */
  31     wxRIBBON_BUTTONBAR_BUTTON_MEDIUM    = 1 << 0,
  32
  33     /**
  34         Button is large (the interpretation of large is dependent upon the art
  35         provider, but it will be larger than medium).
  36     */
  37     wxRIBBON_BUTTONBAR_BUTTON_LARGE     = 2 << 0,
  38
  39     /**
  40         A mask to extract button size from a combination of flags.
  41     */
  42     wxRIBBON_BUTTONBAR_BUTTON_SIZE_MASK = 3 << 0,
  43
  44     /**
  45         The normal (non-dropdown) region of the button is being hovered over by
  46         the mouse cursor. Only applicable to normal and hybrid buttons.
  47     */
  48     wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED    = 1 << 3,
  49
  50     /**
  51         The dropdown region of the button is being hovered over by the mouse
  52         cursor. Only applicable to dropdown and hybrid buttons.
  53     */
  54     wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED  = 1 << 4,
  55
  56     /**
  57         A mask to extract button hover state from a combination of flags.
  58     */
  59     wxRIBBON_BUTTONBAR_BUTTON_HOVER_MASK        = wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED | wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED,
  60
  61     /**
  62         The normal (non-dropdown) region of the button is being pressed.
  63         Only applicable to normal and hybrid buttons.
  64     */
  65     wxRIBBON_BUTTONBAR_BUTTON_NORMAL_ACTIVE     = 1 << 5,
  66
  67     /**
  68         The dropdown region of the button is being pressed.
  69         Only applicable to dropdown and hybrid buttons.
  70     */
  71     wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_ACTIVE   = 1 << 6,
  72
  73     /**
  74         The button is disabled. Hover flags may still be set when a button
  75         is disabled, but should be ignored during drawing if the button is
  76         disabled.
  77     */
  78     wxRIBBON_BUTTONBAR_BUTTON_DISABLED          = 1 << 7,
  79
  80     /**
  81         The button is a toggle button which is currently in the toggled state.
  82     */
  83     wxRIBBON_BUTTONBAR_BUTTON_TOGGLED           = 1 << 8,
  84
  85     /**
  86         A mask to extract button state from a combination of flags.
  87     */
  88     wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK        = 0x1F8,
  89 };
  90
  91 /**
  92     @class wxRibbonButtonBar
  93
  94     A ribbon button bar is similar to a traditional toolbar. It contains one or
  95     more buttons (button bar buttons, not wxButtons), each of which has a label
  96     and an icon. It differs from a wxRibbonToolBar in several ways:
  97       @li Individual buttons can grow and contract.
  98       @li Buttons have labels as well as bitmaps.
  99       @li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
 100         compared to a tool bar (which typically has 16x15).
 101       @li There is no grouping of buttons on a button bar
 102       @li A button bar typically has a border around each individual button,
 103         whereas a tool bar typically has a border around each group of buttons.
 104
 105     @beginEventEmissionTable{wxRibbonButtonBarEvent}
 106     @event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
 107         Triggered when the normal (non-dropdown) region of a button on the
 108         button bar is clicked.
 109     @event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
 110         Triggered when the dropdown region of a button on the button bar is
 111         clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
 112         event handler if it wants to display a popup menu (which is what most
 113         dropdown buttons should be doing).
 114     @endEventTable
 115
 116     @library{wxribbon}
 117     @category{ribbon}
 118 */
 119 class wxRibbonButtonBar : public wxRibbonControl
 120 {
 121 public:
 122     /**
 123         Default constructor.
 124         With this constructor, Create() should be called in order to create
 125         the button bar.
 126     */
 127     wxRibbonButtonBar();
 128
 129     /**
 130         Construct a ribbon button bar with the given parameters.
 131
 132         @param parent
 133             Parent window for the button bar (typically a wxRibbonPanel).
 134         @param id
 135             An identifier for the button bar. @c wxID_ANY is taken to mean a default.
 136         @param pos
 137             Initial position of the button bar.
 138         @param size
 139             Initial size of the button bar.
 140         @param style
 141             Button bar style, currently unused.
 142     */
 143     wxRibbonButtonBar(wxWindow* parent,
 144                   wxWindowID id = wxID_ANY,
 145                   const wxPoint& pos = wxDefaultPosition,
 146                   const wxSize& size = wxDefaultSize,
 147                   long style = 0);
 148
 149     /**
 150         Destructor.
 151     */
 152     virtual ~wxRibbonButtonBar();
 153
 154     /**
 155         Create a button bar in two-step button bar construction.
 156         Should only be called when the default constructor is used, and
 157         arguments have the same meaning as in the full constructor.
 158     */
 159     bool Create(wxWindow* parent,
 160                 wxWindowID id = wxID_ANY,
 161                 const wxPoint& pos = wxDefaultPosition,
 162                 const wxSize& size = wxDefaultSize,
 163                 long style = 0);
 164
 165     /**
 166         Add a button to the button bar (simple version).
 167     */
 168     virtual wxRibbonButtonBarButtonBase* AddButton(
 169                 int button_id,
 170                 const wxString& label,
 171                 const wxBitmap& bitmap,
 172                 const wxString& help_string,
 173                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
 174
 175     /**
 176         Add a dropdown button to the button bar (simple version).
 177
 178         @see AddButton()
 179     */
 180     virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
 181                 int button_id,
 182                 const wxString& label,
 183                 const wxBitmap& bitmap,
 184                 const wxString& help_string = wxEmptyString);
 185
 186     /**
 187         Add a hybrid button to the button bar (simple version).
 188
 189         @see AddButton()
 190     */
 191     virtual wxRibbonButtonBarButtonBase* AddHybridButton(
 192                 int button_id,
 193                 const wxString& label,
 194                 const wxBitmap& bitmap,
 195                 const wxString& help_string = wxEmptyString);
 196
 197     /**
 198         Add a toggle button to the button bar (simple version).
 199
 200         @see AddButton()
 201     */
 202     virtual wxRibbonButtonBarButtonBase* AddToggleButton(
 203                 int button_id,
 204                 const wxString& label,
 205                 const wxBitmap& bitmap,
 206                 const wxString& help_string = wxEmptyString);
 207
 208     /**
 209         Add a button to the button bar.
 210
 211         @param button_id
 212             ID of the new button (used for event callbacks).
 213         @param label
 214             Label of the new button.
 215         @param bitmap
 216             Large bitmap of the new button. Must be the same size as all other
 217             large bitmaps used on the button bar.
 218         @param bitmap_small
 219             Small bitmap of the new button. If left as null, then a small
 220             bitmap will be automatically generated. Must be the same size as
 221             all other small bitmaps used on the button bar.
 222         @param bitmap_disabled
 223             Large bitmap of the new button when it is disabled. If left as
 224             null, then a bitmap will be automatically generated from @a bitmap.
 225         @param bitmap_small_disabled
 226             Small bitmap of the new button when it is disabled. If left as
 227             null, then a bitmap will be automatically generated from @a
 228             bitmap_small.
 229         @param kind
 230             The kind of button to add.
 231         @param help_string
 232             The UI help string to associate with the new button.
 233
 234         @return An opaque pointer which can be used only with other button bar
 235             methods.
 236
 237         @see AddDropdownButton()
 238         @see AddHybridButton()
 239         @see AddToggleButton()
 240     */
 241     virtual wxRibbonButtonBarButtonBase* AddButton(
 242                 int button_id,
 243                 const wxString& label,
 244                 const wxBitmap& bitmap,
 245                 const wxBitmap& bitmap_small = wxNullBitmap,
 246                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 247                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 248                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 249                 const wxString& help_string = wxEmptyString);
 250
 251     /**
 252         Inserts a button to the button bar (simple version) at the given position.
 253
 254         @see AddButton()
 255
 256         @since 2.9.4
 257     */
 258     virtual wxRibbonButtonBarButtonBase* InsertButton(
 259                 size_t pos,
 260                 int button_id,
 261                 const wxString& label,
 262                 const wxBitmap& bitmap,
 263                 const wxString& help_string,
 264                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
 265
 266     /**
 267         Inserts a dropdown button to the button bar (simple version) at the
 268             given position.
 269
 270         @see InsertButton()
 271         @see AddDropdownButton()
 272         @see AddButton()
 273
 274         @since 2.9.4
 275     */
 276     virtual wxRibbonButtonBarButtonBase* InsertDropdownButton(
 277                 size_t pos,
 278                 int button_id,
 279                 const wxString& label,
 280                 const wxBitmap& bitmap,
 281                 const wxString& help_string = wxEmptyString);
 282
 283     /**
 284         Inserts a hybrid button to the button bar (simple version) at the given
 285             position.
 286
 287         @see InsertButton()
 288         @see AddHybridButton()
 289         @see AddButton()
 290
 291         @since 2.9.4
 292     */
 293     virtual wxRibbonButtonBarButtonBase* InsertHybridButton(
 294                 size_t pos,
 295                 int button_id,
 296                 const wxString& label,
 297                 const wxBitmap& bitmap,
 298                 const wxString& help_string = wxEmptyString);
 299
 300     /**
 301         Inserts a toggle button to the button bar (simple version) at the given
 302             position.
 303
 304         @see InsertButton()
 305         @see AddToggleButton()
 306         @see AddButton()
 307
 308         @since 2.9.4
 309     */
 310     virtual wxRibbonButtonBarButtonBase* InsertToggleButton(
 311                 size_t pos,
 312                 int button_id,
 313                 const wxString& label,
 314                 const wxBitmap& bitmap,
 315                 const wxString& help_string = wxEmptyString);
 316
 317     /**
 318         Insert a button to the button bar at the given position.
 319
 320         @param pos
 321             Position of the new button in the button bar.
 322         @param button_id
 323             ID of the new button (used for event callbacks).
 324         @param label
 325             Label of the new button.
 326         @param bitmap
 327             Large bitmap of the new button. Must be the same size as all other
 328             large bitmaps used on the button bar.
 329         @param bitmap_small
 330             Small bitmap of the new button. If left as null, then a small
 331             bitmap will be automatically generated. Must be the same size as
 332             all other small bitmaps used on the button bar.
 333         @param bitmap_disabled
 334             Large bitmap of the new button when it is disabled. If left as
 335             null, then a bitmap will be automatically generated from @a bitmap.
 336         @param bitmap_small_disabled
 337             Small bitmap of the new button when it is disabled. If left as
 338             null, then a bitmap will be automatically generated from @a
 339             bitmap_small.
 340         @param kind
 341             The kind of button to add.
 342         @param help_string
 343             The UI help string to associate with the new button.
 344
 345         @return An opaque pointer which can be used only with other button bar
 346             methods.
 347
 348         @see InsertDropdownButton()
 349         @see InsertHybridButton()
 350         @see InsertToggleButton()
 351         @see AddButton()
 352
 353         @since 2.9.4
 354     */
 355     virtual wxRibbonButtonBarButtonBase* InsertButton(
 356                 size_t pos,
 357                 int button_id,
 358                 const wxString& label,
 359                 const wxBitmap& bitmap,
 360                 const wxBitmap& bitmap_small = wxNullBitmap,
 361                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 362                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 363                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 364                 const wxString& help_string = wxEmptyString);
 365
 366     /**
 367         Returns the number of buttons in this button bar.
 368
 369         @since 2.9.4
 370     */
 371     virtual size_t GetButtonCount() const;
 372
 373     /**
 374         Set the client object associated with a button. The button bar
 375         owns the given object and takes care of its deletion.
 376         Please, note that you cannot use both client object and client data.
 377
 378         @since 2.9.5
 379     */
 380     void SetItemClientObject(wxRibbonButtonBarButtonBase* item, wxClientData* data);
 381
 382     /**
 383         Get the client object associated with a button.
 384
 385         @since 2.9.5
 386     */
 387     wxClientData* GetItemClientObject(const wxRibbonButtonBarButtonBase* item) const;
 388
 389     /**
 390         Set the client data associated with a button.
 391         Please, note that you cannot use both client object and client data.
 392
 393         @since 2.9.5
 394     */
 395     void SetItemClientData(wxRibbonButtonBarButtonBase* item, void* data);
 396
 397     /**
 398         Get the client data associated with a button.
 399
 400         @since 2.9.5
 401     */
 402     void* GetItemClientData(const wxRibbonButtonBarButtonBase* item) const;
 403
 404     /**
 405         Returns the N-th button of the bar.
 406
 407         @see GetButtonCount()
 408
 409         @since 2.9.5
 410     */
 411     virtual wxRibbonButtonBarButtonBase *GetItem(size_t n) const;
 412
 413     /**
 414         Returns the first button having a given id or NULL if none matches.
 415
 416         @since 2.9.5
 417     */
 418     virtual wxRibbonButtonBarButtonBase *GetItemById(int id) const;
 419
 420     /**
 421         Returns the id of a button.
 422
 423         @since 2.9.5
 424     */
 425     virtual int GetItemId(wxRibbonButtonBarButtonBase *) const;
 426
 427     /**
 428         Calculate button layouts and positions.
 429
 430         Must be called after buttons are added to the button bar, as otherwise
 431         the newly added buttons will not be displayed. In normal situations, it
 432         will be called automatically when wxRibbonBar::Realize() is called.
 433     */
 434     virtual bool Realize();
 435
 436     /**
 437         Delete all buttons from the button bar.
 438
 439         @see DeleteButton()
 440     */
 441     virtual void ClearButtons();
 442
 443     /**
 444         Delete a single button from the button bar.
 445
 446         @see ClearButtons()
 447     */
 448     virtual bool DeleteButton(int button_id);
 449
 450     /**
 451         Enable or disable a single button on the bar.
 452
 453         @param button_id
 454             ID of the button to enable or disable.
 455         @param enable
 456             @true to enable the button, @false to disable it.
 457     */
 458     virtual void EnableButton(int button_id, bool enable = true);
 459
 460     /**
 461         Set a toggle button to the checked or unchecked state.
 462
 463         @param button_id
 464             ID of the toggle button to manipulate.
 465         @param checked
 466             @true to set the button to the toggled/pressed/checked state,
 467             @false to set it to the untoggled/unpressed/unchecked state.
 468     */
 469     virtual void ToggleButton(int button_id, bool checked);
 470
 471     /**
 472         Returns the active item of the button bar or NULL if there is none.
 473         The active button is the one being clicked.
 474
 475         @since 2.9.5
 476     */
 477     virtual wxRibbonButtonBarButtonBase *GetActiveItem() const;
 478
 479     /**
 480         Returns the hovered item of the button bar or NULL if there is none.
 481         The hovered button is the one the mouse is over.
 482
 483         @since 2.9.5
 484     */
 485     virtual wxRibbonButtonBarButtonBase *GetHoveredItem() const;
 486
 487     /**
 488         Indicates whether tooltips are shown for disabled buttons.
 489
 490         By default they are not shown.
 491
 492         @since 2.9.5
 493     */
 494     void SetShowToolTipsForDisabled(bool show);
 495
 496     /**
 497         Sets whether tooltips should be shown for disabled buttons or not.
 498
 499         You may wish to show it to explain why a button is disabled or
 500         what it normally does when enabled.
 501
 502         @since 2.9.5
 503     */
 504     bool GetShowToolTipsForDisabled() const;
 505
 506 };
 507
 508 /**
 509     @class wxRibbonButtonBarEvent
 510
 511     Event used to indicate various actions relating to a button on a
 512     wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
 513     the state of the button.
 514
 515     See wxRibbonButtonBar for available event types.
 516
 517     @library{wxribbon}
 518     @category{events,ribbon}
 519
 520     @see wxRibbonBar
 521 */
 522 class wxRibbonButtonBarEvent : public wxCommandEvent
 523 {
 524 public:
 525     /**
 526         Constructor.
 527     */
 528     wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
 529                        int win_id = 0,
 530                        wxRibbonButtonBar* bar = NULL,
 531                        wxRibbonButtonBarButtonBase* button = NULL);
 532
 533     /**
 534         Returns the bar which contains the button which the event relates to.
 535     */
 536     wxRibbonButtonBar* GetBar();
 537
 538     /**
 539         Sets the button bar relating to this event.
 540     */
 541     void SetBar(wxRibbonButtonBar* bar);
 542
 543     /**
 544         Returns the button which the event relates to.
 545
 546         @since 2.9.5
 547     */
 548     wxRibbonButtonBarButtonBase* GetButton();
 549
 550     /**
 551         Sets the button relating to this event.
 552
 553         @since 2.9.5
 554     */
 555     void SetButton(wxRibbonButtonBarButtonBase* bar);
 556
 557     /**
 558         Display a popup menu as a result of this (dropdown clicked) event.
 559     */
 560     bool PopupMenu(wxMenu* menu);
 561 };