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 dependant 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 dependant 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 dependant 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                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_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                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
 252                 const wxString& help_string = wxEmptyString,
 253                 wxObject* client_data = NULL);
 254
 255     /**
 256         Calculate button layouts and positions.
 257
 258         Must be called after buttons are added to the button bar, as otherwise
 259         the newly added buttons will not be displayed. In normal situations, it
 260         will be called automatically when wxRibbonBar::Realize() is called.
 261     */
 262     virtual bool Realize();
 263
 264     /**
 265         Delete all buttons from the button bar.
 266
 267         @see DeleteButton()
 268     */
 269     virtual void ClearButtons();
 270
 271     /**
 272         Delete a single button from the button bar.
 273
 274         @see ClearButtons()
 275     */
 276     virtual bool DeleteButton(int button_id);
 277
 278     /**
 279         Enable or disable a single button on the bar.
 280
 281         @param button_id
 282             ID of the button to enable or disable.
 283         @param enable
 284             @true to enable the button, @false to disable it.
 285     */
 286     virtual void EnableButton(int button_id, bool enable = true);
 287
 288     /**
 289         Set a toggle button to the checked or unchecked state.
 290
 291         @param button_id
 292             ID of the toggle button to manipulate.
 293         @param checked
 294             @true to set the button to the toggled/pressed/checked state,
 295             @false to set it to the untoggled/unpressed/unchecked state.
 296     */
 297     virtual void ToggleButton(int button_id, bool checked);
 298 };
 299
 300 /**
 301     @class wxRibbonButtonBarEvent
 302
 303     Event used to indicate various actions relating to a button on a
 304     wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
 305     the state of the button.
 306
 307     See wxRibbonButtonBar for available event types.
 308
 309     @library{wxribbon}
 310     @category{events,ribbon}
 311
 312     @see wxRibbonBar
 313 */
 314 class wxRibbonButtonBarEvent : public wxCommandEvent
 315 {
 316 public:
 317     /**
 318         Constructor.
 319     */
 320     wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
 321                        int win_id = 0,
 322                        wxRibbonButtonBar* bar = NULL);
 323
 324     /**
 325         Returns the bar which contains the button which the event relates to.
 326     */
 327     wxRibbonButtonBar* GetBar();
 328
 329     /**
 330         Sets the button bar relating to this event.
 331     */
 332     void SetBar(wxRibbonButtonBar* bar);
 333
 334     /**
 335         Display a popup menu as a result of this (dropdown clicked) event.
 336     */
 337     bool PopupMenu(wxMenu* menu);
 338 };