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         @param client_data
 235             Client data to associate with the new button.
 236
 237         @return An opaque pointer which can be used only with other button bar
 238             methods.
 239
 240         @see AddDropdownButton()
 241         @see AddHybridButton()
 242         @see AddToggleButton()
 243     */
 244     virtual wxRibbonButtonBarButtonBase* AddButton(
 245                 int button_id,
 246                 const wxString& label,
 247                 const wxBitmap& bitmap,
 248                 const wxBitmap& bitmap_small = wxNullBitmap,
 249                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 250                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 251                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 252                 const wxString& help_string = wxEmptyString,
 253                 wxObject* client_data = NULL);
 254
 255     /**
 256         Inserts a button to the button bar (simple version) at the given position.
 257
 258         @see AddButton()
 259
 260         @since 2.9.4
 261     */
 262     virtual wxRibbonButtonBarButtonBase* InsertButton(
 263                 size_t pos,
 264                 int button_id,
 265                 const wxString& label,
 266                 const wxBitmap& bitmap,
 267                 const wxString& help_string,
 268                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
 269
 270     /**
 271         Inserts a dropdown button to the button bar (simple version) at the
 272             given position.
 273
 274         @see InsertButton()
 275         @see AddDropdownButton()
 276         @see AddButton()
 277
 278         @since 2.9.4
 279     */
 280     virtual wxRibbonButtonBarButtonBase* InsertDropdownButton(
 281                 size_t pos,
 282                 int button_id,
 283                 const wxString& label,
 284                 const wxBitmap& bitmap,
 285                 const wxString& help_string = wxEmptyString);
 286
 287     /**
 288         Inserts a hybrid button to the button bar (simple version) at the given
 289             position.
 290
 291         @see InsertButton()
 292         @see AddHybridButton()
 293         @see AddButton()
 294
 295         @since 2.9.4
 296     */
 297     virtual wxRibbonButtonBarButtonBase* InsertHybridButton(
 298                 size_t pos,
 299                 int button_id,
 300                 const wxString& label,
 301                 const wxBitmap& bitmap,
 302                 const wxString& help_string = wxEmptyString);
 303
 304     /**
 305         Inserts a toggle button to the button bar (simple version) at the given
 306             position.
 307
 308         @see InsertButton()
 309         @see AddToggleButton()
 310         @see AddButton()
 311
 312         @since 2.9.4
 313     */
 314     virtual wxRibbonButtonBarButtonBase* InsertToggleButton(
 315                 size_t pos,
 316                 int button_id,
 317                 const wxString& label,
 318                 const wxBitmap& bitmap,
 319                 const wxString& help_string = wxEmptyString);
 320
 321     /**
 322         Insert a button to the button bar at the given position.
 323
 324         @param pos
 325             Position of the new button in the button bar.
 326         @param button_id
 327             ID of the new button (used for event callbacks).
 328         @param label
 329             Label of the new button.
 330         @param bitmap
 331             Large bitmap of the new button. Must be the same size as all other
 332             large bitmaps used on the button bar.
 333         @param bitmap_small
 334             Small bitmap of the new button. If left as null, then a small
 335             bitmap will be automatically generated. Must be the same size as
 336             all other small bitmaps used on the button bar.
 337         @param bitmap_disabled
 338             Large bitmap of the new button when it is disabled. If left as
 339             null, then a bitmap will be automatically generated from @a bitmap.
 340         @param bitmap_small_disabled
 341             Small bitmap of the new button when it is disabled. If left as
 342             null, then a bitmap will be automatically generated from @a
 343             bitmap_small.
 344         @param kind
 345             The kind of button to add.
 346         @param help_string
 347             The UI help string to associate with the new button.
 348         @param client_data
 349             Client data to associate with the new button.
 350
 351         @return An opaque pointer which can be used only with other button bar
 352             methods.
 353
 354         @see InsertDropdownButton()
 355         @see InsertHybridButton()
 356         @see InsertToggleButton()
 357         @see AddButton()
 358
 359         @since 2.9.4
 360     */
 361     virtual wxRibbonButtonBarButtonBase* InsertButton(
 362                 size_t pos,
 363                 int button_id,
 364                 const wxString& label,
 365                 const wxBitmap& bitmap,
 366                 const wxBitmap& bitmap_small = wxNullBitmap,
 367                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 368                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 369                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 370                 const wxString& help_string = wxEmptyString,
 371                 wxObject* client_data = NULL);
 372
 373     /**
 374         Returns the number of buttons in this button bar.
 375
 376         @since 2.9.4
 377     */
 378     virtual size_t GetButtonCount() const;
 379
 380     /**
 381         Returns the N-th button of the bar.
 382
 383         @see GetButtonCount()
 384
 385         @since 2.9.5
 386     */
 387     virtual wxRibbonButtonBarButtonBase *GetItem(size_t n) const;
 388
 389     /**
 390         Returns the first button having a given id or NULL if none matches.
 391
 392         @since 2.9.5
 393     */
 394     virtual wxRibbonButtonBarButtonBase *GetItemById(int id) const;
 395
 396     /**
 397         Returns the id of a button.
 398
 399         @since 2.9.5
 400     */
 401     virtual int GetItemId(wxRibbonButtonBarButtonBase *) const;
 402
 403     /**
 404         Calculate button layouts and positions.
 405
 406         Must be called after buttons are added to the button bar, as otherwise
 407         the newly added buttons will not be displayed. In normal situations, it
 408         will be called automatically when wxRibbonBar::Realize() is called.
 409     */
 410     virtual bool Realize();
 411
 412     /**
 413         Delete all buttons from the button bar.
 414
 415         @see DeleteButton()
 416     */
 417     virtual void ClearButtons();
 418
 419     /**
 420         Delete a single button from the button bar.
 421
 422         @see ClearButtons()
 423     */
 424     virtual bool DeleteButton(int button_id);
 425
 426     /**
 427         Enable or disable a single button on the bar.
 428
 429         @param button_id
 430             ID of the button to enable or disable.
 431         @param enable
 432             @true to enable the button, @false to disable it.
 433     */
 434     virtual void EnableButton(int button_id, bool enable = true);
 435
 436     /**
 437         Set a toggle button to the checked or unchecked state.
 438
 439         @param button_id
 440             ID of the toggle button to manipulate.
 441         @param checked
 442             @true to set the button to the toggled/pressed/checked state,
 443             @false to set it to the untoggled/unpressed/unchecked state.
 444     */
 445     virtual void ToggleButton(int button_id, bool checked);
 446
 447     /**
 448         Returns the active item of the button bar or NULL if there is none.
 449         The active button is the one being clicked.
 450
 451         @since 2.9.5
 452     */
 453     virtual wxRibbonButtonBarButtonBase *GetActiveItem() const;
 454
 455     /**
 456         Returns the hovered item of the button bar or NULL if there is none.
 457         The hovered button is the one the mouse is over.
 458
 459         @since 2.9.5
 460     */
 461     virtual wxRibbonButtonBarButtonBase *GetHoveredItem() const;
 462
 463 };
 464
 465 /**
 466     @class wxRibbonButtonBarEvent
 467
 468     Event used to indicate various actions relating to a button on a
 469     wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
 470     the state of the button.
 471
 472     See wxRibbonButtonBar for available event types.
 473
 474     @library{wxribbon}
 475     @category{events,ribbon}
 476
 477     @see wxRibbonBar
 478 */
 479 class wxRibbonButtonBarEvent : public wxCommandEvent
 480 {
 481 public:
 482     /**
 483         Constructor.
 484     */
 485     wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
 486                        int win_id = 0,
 487                        wxRibbonButtonBar* bar = NULL,
 488                        wxRibbonButtonBarButtonBase* button = NULL);
 489
 490     /**
 491         Returns the bar which contains the button which the event relates to.
 492     */
 493     wxRibbonButtonBar* GetBar();
 494
 495     /**
 496         Sets the button bar relating to this event.
 497     */
 498     void SetBar(wxRibbonButtonBar* bar);
 499
 500     /**
 501         Returns the button which the event relates to.
 502
 503         @since 2.9.5
 504     */
 505     wxRibbonButtonBarButtonBase* GetButton();
 506
 507     /**
 508         Sets the button relating to this event.
 509
 510         @since 2.9.5
 511     */
 512     void SetButton(wxRibbonButtonBarButtonBase* bar);
 513
 514     /**
 515         Display a popup menu as a result of this (dropdown clicked) event.
 516     */
 517     bool PopupMenu(wxMenu* menu);
 518 };