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
 128         @param parent
 129             Parent window for the button bar (typically a wxRibbonPanel).
 130         @param id
 131             An identifier for the button bar. @c wxID_ANY is taken to mean a default.
 132         @param pos
 133             Initial position of the button bar.
 134         @param size
 135             Initial size of the button bar.
 136         @param style
 137             Button bar style, currently unused.
 138     */
 139     wxRibbonButtonBar(wxWindow* parent,
 140                   wxWindowID id = wxID_ANY,
 141                   const wxPoint& pos = wxDefaultPosition,
 142                   const wxSize& size = wxDefaultSize,
 143                   long style = 0);
 144
 145     /**
 146         Destructor.
 147     */
 148     virtual ~wxRibbonButtonBar();
 149
 150     /**
 151         Create a button bar in two-step button bar construction.
 152         Should only be called when the default constructor is used, and
 153         arguments have the same meaning as in the full constructor.
 154     */
 155     bool Create(wxWindow* parent,
 156                 wxWindowID id = wxID_ANY,
 157                 const wxPoint& pos = wxDefaultPosition,
 158                 const wxSize& size = wxDefaultSize,
 159                 long style = 0);
 160
 161     /**
 162         Add a button to the button bar (simple version).
 163     */
 164     virtual wxRibbonButtonBarButtonBase* AddButton(
 165                 int button_id,
 166                 const wxString& label,
 167                 const wxBitmap& bitmap,
 168                 const wxString& help_string,
 169                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL);
 170
 171     /**
 172         Add a dropdown button to the button bar (simple version).
 173
 174         @see AddButton()
 175     */
 176     virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
 177                 int button_id,
 178                 const wxString& label,
 179                 const wxBitmap& bitmap,
 180                 const wxString& help_string = wxEmptyString);
 181
 182     /**
 183         Add a hybrid button to the button bar (simple version).
 184
 185         @see AddButton()
 186     */
 187     virtual wxRibbonButtonBarButtonBase* AddHybridButton(
 188                 int button_id,
 189                 const wxString& label,
 190                 const wxBitmap& bitmap,
 191                 const wxString& help_string = wxEmptyString);
 192
 193     /**
 194         Add a button to the button bar.
 195
 196         @param button_id
 197             ID of the new button (used for event callbacks).
 198         @param label
 199             Label of the new button.
 200         @param bitmap
 201             Large bitmap of the new button. Must be the same size as all other
 202             large bitmaps used on the button bar.
 203         @param bitmap_small
 204             Small bitmap of the new button. If left as null, then a small
 205             bitmap will be automatically generated. Must be the same size as
 206             all other small bitmaps used on the button bar.
 207         @param bitmap_disabled
 208             Large bitmap of the new button when it is disabled. If left as
 209             null, then a bitmap will be automatically generated from @a bitmap.
 210         @param bitmap_small_disabled
 211             Small bitmap of the new button when it is disabled. If left as
 212             null, then a bitmap will be automatically generated from @a
 213             bitmap_small.
 214         @param kind
 215             The kind of button to add.
 216         @param help_string
 217             The UI help string to associate with the new button.
 218         @param client_data
 219             Client data to associate with the new button.
 220
 221         @return An opaque pointer which can be used only with other button bar
 222             methods.
 223
 224         @see AddDropdownButton()
 225         @see AddHybridButton()
 226     */
 227     virtual wxRibbonButtonBarButtonBase* AddButton(
 228                 int button_id,
 229                 const wxString& label,
 230                 const wxBitmap& bitmap,
 231                 const wxBitmap& bitmap_small = wxNullBitmap,
 232                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 233                 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
 234                 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
 235                 const wxString& help_string = wxEmptyString,
 236                 wxObject* client_data = NULL);
 237
 238     /**
 239         Calculate button layouts and positions.
 240
 241         Must be called after buttons are added to the button bar, as otherwise
 242         the newly added buttons will not be displayed. In normal situations, it
 243         will be called automatically when wxRibbonBar::Realize() is called.
 244     */
 245     virtual bool Realize();
 246
 247     /**
 248         Delete all buttons from the button bar.
 249
 250         @see DeleteButton()
 251     */
 252     virtual void ClearButtons();
 253
 254     /**
 255         Delete a single button from the button bar.
 256
 257         @see ClearButtons()
 258     */
 259     virtual bool DeleteButton(int button_id);
 260
 261     /**
 262         Enable or disable a single button on the bar.
 263
 264         @param button_id
 265             ID of the button to enable or disable.
 266         @param enable
 267             @true to enable the button, @false to disable it.
 268     */
 269     virtual void EnableButton(int button_id, bool enable = true);
 270 };
 271
 272 /**
 273     @class wxRibbonButtonBarEvent
 274
 275     Event used to indicate various actions relating to a button on a
 276     wxRibbonButtonBar.
 277
 278     See wxRibbonButtonBar for available event types.
 279
 280     @library{wxribbon}
 281     @category{events,ribbon}
 282
 283     @see wxRibbonBar
 284 */
 285 class wxRibbonButtonBarEvent : public wxCommandEvent
 286 {
 287 public:
 288     /**
 289         Constructor.
 290     */
 291     wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
 292                        int win_id = 0,
 293                        wxRibbonButtonBar* bar = NULL);
 294
 295     /**
 296         Returns the bar which contains the button which the event relates to.
 297     */
 298     wxRibbonButtonBar* GetBar();
 299
 300     /**
 301         Sets the button bar relating to this event.
 302     */
 303     void SetBar(wxRibbonButtonBar* bar);
 304
 305     /**
 306         Display a popup menu as a result of this (dropdown clicked) event.
 307     */
 308     bool PopupMenu(wxMenu* menu);
 309 };