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         A mask to extract button state from a combination of flags.
  83     */
  84     wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK        = 0xF8,
  85 };
  86
  87 /**
  88     @class wxRibbonButtonBar
  89
  90     A ribbon button bar is similar to a traditional toolbar. It contains one or
  91     more buttons (button bar buttons, not wxButtons), each of which has a label
  92     and an icon. It differs from a wxRibbonToolBar in several ways:
  93       @li Individual buttons can grow and contract.
  94       @li Buttons have labels as well as bitmaps.
  95       @li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
  96         compared to a tool bar (which typically has 16x15).
  97       @li There is no grouping of buttons on a button bar
  98       @li A button bar typically has a border around each individual button,
  99         whereas a tool bar typically has a border around each group of buttons.
 100
 101     @beginEventEmissionTable{wxRibbonButtonBarEvent}
 102     @event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
 103         Triggered when the normal (non-dropdown) region of a button on the
 104         button bar is clicked.
 105     @event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
 106         Triggered when the dropdown region of a button on the button bar is
 107         clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
 108         event handler if it wants to display a popup menu (which is what most
 109         dropdown buttons should be doing).
 110     @endEventTable
 111
 112     @library{wxribbon}
 113     @category{ribbon}
 114 */
 115 class wxRibbonButtonBar : public wxRibbonControl
 116 {
 117 public:
 118     /**
 119         Default constructor.
 120         With this constructor, Create() should be called in order to create
 121         the button bar.
 122     */
 123     wxRibbonButtonBar();
 124
 125     /**
 126         Construct a ribbon button bar with the given parameters.
 127         @param parent
 128             Parent window for the button bar (typically a wxRibbonPanel).
 129         @param pos
 130             Initial position of the button bar.
 131         @param size
 132             Initial size of the button bar.
 133         @param style
 134             Button bar style, currently unused.
 135     */
 136     wxRibbonButtonBar(wxWindow* parent,
 137                   wxWindowID id = wxID_ANY,
 138                   const wxPoint& pos = wxDefaultPosition,
 139                   const wxSize& size = wxDefaultSize,
 140                   long style = 0);
 141
 142     /**
 143         Destructor.
 144     */
 145     virtual ~wxRibbonButtonBar();
 146
 147     /**
 148         Create a button bar in two-step button bar construction.
 149         Should only be called when the default constructor is used, and
 150         arguments have the same meaning as in the full constructor.
 151     */
 152     bool Create(wxWindow* parent,
 153                 wxWindowID id = wxID_ANY,
 154                 const wxPoint& pos = wxDefaultPosition,
 155                 const wxSize& size = wxDefaultSize,
 156                 long style = 0);
 157
 158     /**
 159         Add a button to the button bar (simple version).
 160     */
 161     virtual wxRibbonButtonBarButtonBase* AddButton(
 162                 int button_id,
 163                 const wxString& label,
 164                 const wxBitmap& bitmap,
 165                 const wxString& help_string,
 166                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL);
 167
 168     /**
 169         Add a dropdown button to the button bar (simple version).
 170
 171         @see AddButton()
 172     */
 173     virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
 174                 int button_id,
 175                 const wxString& label,
 176                 const wxBitmap& bitmap,
 177                 const wxString& help_string = wxEmptyString);
 178
 179     /**
 180         Add a hybrid button to the button bar (simple version).
 181
 182         @see AddButton()
 183     */
 184     virtual wxRibbonButtonBarButtonBase* AddHybridButton(
 185                 int button_id,
 186                 const wxString& label,
 187                 const wxBitmap& bitmap,
 188                 const wxString& help_string = wxEmptyString);
 189
 190     /**
 191         Add a button to the button bar.
 192
 193         @param button_id
 194             ID of the new button (used for event callbacks).
 195         @param label
 196             Label of the new button.
 197         @param bitmap
 198             Large bitmap of the new button. Must be the same size as all other
 199             large bitmaps used on the button bar.
 200         @param bitmap_small
 201             Small bitmap of the new button. If left as null, then a small
 202             bitmap will be automatically generated. Must be the same size as
 203             all other small bitmaps used on the button bar.
 204         @param bitmap_disabled
 205             Large bitmap of the new button when it is disabled. If left as
 206             null, then a bitmap will be automatically generated from @a bitmap.
 207         @param bitmap_small_disabled
 208             Small bitmap of the new button when it is disabled. If left as
 209             null, then a bitmap will be automatically generated from @a
 210             bitmap_small.
 211         @param kind
 212             The kind of button to add.
 213         @param help_string
 214             The UI help string to associate with the new button.
 215         @param client_data
 216             Client data to associate with the new button.
 217
 218         @return An opaque pointer which can be used only with other button bar
 219             methods.
 220
 221         @see AddDropdownButton()
 222         @see AddHybridButton()
 223     */
 224     virtual wxRibbonButtonBarButtonBase* AddButton(
 225                 int button_id,
 226                 const wxString& label,
 227                 const wxBitmap& bitmap,
 228                 const wxBitmap& bitmap_small = wxNullBitmap,
 229                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 230                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 231                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
 232                 const wxString& help_string = wxEmptyString,
 233                 wxObject* client_data = NULL);
 234
 235     /**
 236         Calculate button layouts and positions.
 237
 238         Must be called after buttons are added to the button bar, as otherwise
 239         the newly added buttons will not be displayed. In normal situations, it
 240         will be called automatically when wxRibbonBar::Realize() is called.
 241     */
 242     virtual bool Realize();
 243
 244     /**
 245         Delete all buttons from the button bar.
 246
 247         @see DeleteButton()
 248     */
 249     virtual void ClearButtons();
 250
 251     /**
 252         Delete a single button from the button bar.
 253
 254         @see ClearButtons()
 255     */
 256     virtual bool DeleteButton(int button_id);
 257
 258     /**
 259         Enable or disable a single button on the bar.
 260
 261         @param button_id
 262             ID of the button to enable or disable.
 263         @param enable
 264             @true to enable the button, @false to disable it.
 265     */
 266     virtual void EnableButton(int button_id, bool enable = true);
 267 };
 268
 269 /**
 270     @class wxRibbonButtonBarEvent
 271
 272     Event used to indicate various actions relating to a button on a
 273     wxRibbonButtonBar.
 274
 275     See wxRibbonButtonBar for available event types.
 276
 277     @library{wxribbon}
 278     @category{events,ribbon}
 279
 280     @see wxRibbonBar
 281 */
 282 class wxRibbonButtonBarEvent : public wxCommandEvent
 283 {
 284 public:
 285     /**
 286         Constructor.
 287     */
 288     wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
 289                        int win_id = 0,
 290                        wxRibbonButtonBar* bar = NULL);
 291
 292     /**
 293         Returns the bar which contains the button which the event relates to.
 294     */
 295     wxRibbonButtonBar* GetBar();
 296
 297     /**
 298         Sets the button bar relating to this event.
 299     */
 300     void SetBar(wxRibbonButtonBar* bar);
 301
 302     /**
 303         Display a popup menu as a result of this (dropdown clicked) event.
 304     */
 305     bool PopupMenu(wxMenu* menu);
 306 };