| 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 | }; |