interface/wx/ribbon/buttonbar.h

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