1 /////////////////////////////////////////////////////////////////////////////// 2 // Name: ribbon/bar.h 3 // Purpose: interface of wxRibbonBar 4 // Author: Peter Cawley 5 // Licence: wxWindows licence 6 /////////////////////////////////////////////////////////////////////////////// 7 8 9 enum wxRibbonBarOption 10 { 11 wxRIBBON_BAR_SHOW_PAGE_LABELS, 12 wxRIBBON_BAR_SHOW_PAGE_ICONS, 13 wxRIBBON_BAR_FLOW_HORIZONTAL, 14 wxRIBBON_BAR_FLOW_VERTICAL, 15 wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS, 16 wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS, 17 wxRIBBON_BAR_ALWAYS_SHOW_TABS, 18 wxRIBBON_BAR_SHOW_TOGGLE_BUTTON, 19 wxRIBBON_BAR_SHOW_HELP_BUTTON, 20 wxRIBBON_BAR_DEFAULT_STYLE, 21 wxRIBBON_BAR_FOLDBAR_STYLE 22 }; 23 24 25 /** 26 The possible display modes of the panel area of a wxRibbonBar widget. 27 28 @see wxRibbonBar::ShowPanels() 29 @see wxRibbonBar::GetDisplayMode() 30 31 @since 2.9.5 32 */ 33 enum wxRibbonDisplayMode 34 { 35 /** 36 The panel area is visible and pinned: it remains visible when the 37 ribbon bar loses the focus. 38 */ 39 wxRIBBON_BAR_PINNED, 40 41 /** 42 The panel area is hidden: only the pages tabs remain visible. 43 */ 44 wxRIBBON_BAR_MINIMIZED, 45 46 /** 47 The panel area is visible, but not pinned: it minimizes as soon as the 48 focus is lost. 49 */ 50 wxRIBBON_BAR_EXPANDED 51 }; 52 53 54 /** 55 @class wxRibbonBarEvent 56 57 Event used to indicate various actions relating to a wxRibbonBar. 58 59 See wxRibbonBar for available event types. 60 61 @library{wxribbon} 62 @category{events,ribbon} 63 64 @see wxRibbonBar 65 */ 66 class wxRibbonBarEvent : public wxNotifyEvent 67 { 68 public: 69 /** 70 Constructor. 71 */ 72 wxRibbonBarEvent(wxEventType command_type = wxEVT_NULL, 73 int win_id = 0, 74 wxRibbonPage* page = NULL); 75 76 /** 77 Returns the page being changed to, or being clicked on. 78 */ 79 wxRibbonPage* GetPage(); 80 81 /** 82 Sets the page relating to this event. 83 */ 84 void SetPage(wxRibbonPage* page); 85 }; 86 87 88 wxEventType wxEVT_RIBBONBAR_PAGE_CHANGED; 89 wxEventType wxEVT_RIBBONBAR_PAGE_CHANGING; 90 wxEventType wxEVT_RIBBONBAR_TAB_MIDDLE_DOWN; 91 wxEventType wxEVT_RIBBONBAR_TAB_MIDDLE_UP; 92 wxEventType wxEVT_RIBBONBAR_TAB_RIGHT_DOWN; 93 wxEventType wxEVT_RIBBONBAR_TAB_RIGHT_UP; 94 wxEventType wxEVT_RIBBONBAR_TAB_LEFT_DCLICK; 95 wxEventType wxEVT_RIBBONBAR_TOGGLED; 96 wxEventType wxEVT_RIBBONBAR_HELP_CLICK; 97 98 99 class wxRibbonPageTabInfo 100 { 101 public: 102 wxRect rect; 103 wxRibbonPage *page; 104 int ideal_width; 105 int small_begin_need_separator_width; 106 int small_must_have_separator_width; 107 int minimum_width; 108 bool active; 109 bool hovered; 110 bool highlight; 111 bool shown; 112 }; 113 114 115 116 /** 117 @class wxRibbonBar 118 119 Top-level control in a ribbon user interface. Serves as a tabbed container 120 for wxRibbonPage - a ribbon user interface typically has a ribbon bar, 121 which contains one or more wxRibbonPages, which in turn each contain one 122 or more wxRibbonPanels, which in turn contain controls. 123 124 While a wxRibbonBar has tabs similar to a wxNotebook, it does not follow 125 the same API for adding pages. Containers like wxNotebook can contain any 126 type of window as a page, hence the normal procedure is to create the 127 sub-window and then call wxBookCtrlBase::AddPage(). As wxRibbonBar can only 128 have wxRibbonPage as children (and a wxRibbonPage can only have a 129 wxRibbonBar as parent), when a page is created, it is automatically added 130 to the bar - there is no AddPage equivalent to call. 131 132 After all pages have been created, and all controls and panels placed on 133 those pages, Realize() must be called. 134 135 @sa wxRibbonPage 136 @sa wxRibbonPanel 137 138 @beginStyleTable 139 @style{wxRIBBON_BAR_DEFAULT_STYLE} 140 Defined as wxRIBBON_BAR_FLOW_HORIZONTAL | 141 wxRIBBON_BAR_SHOW_PAGE_LABELS | wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS | 142 wxRIBBON_BAR_SHOW_TOGGLE_BUTTON | wxRIBBON_BAR_SHOW_HELP_BUTTON. 143 @style{wxRIBBON_BAR_FOLDBAR_STYLE} 144 Defined as wxRIBBON_BAR_FLOW_VERTICAL | wxRIBBON_BAR_SHOW_PAGE_ICONS 145 | wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS | 146 wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS 147 @style{wxRIBBON_BAR_SHOW_PAGE_LABELS} 148 Causes labels to be shown on the tabs in the ribbon bar. 149 @style{wxRIBBON_BAR_SHOW_PAGE_ICONS} 150 Causes icons to be shown on the tabs in the ribbon bar. 151 @style{wxRIBBON_BAR_FLOW_HORIZONTAL} 152 Causes panels within pages to stack horizontally. 153 @style{wxRIBBON_BAR_FLOW_VERTICAL} 154 Causes panels within pages to stack vertically. 155 @style{wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS} 156 Causes extension buttons to be shown on panels (where the panel has 157 such a button). 158 @style{wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS} 159 Causes minimise buttons to be shown on panels (where the panel has 160 such a button). 161 @style{wxRIBBON_BAR_SHOW_TOGGLE_BUTTON} 162 Causes a toggle button to appear on the ribbon bar at top-right corner. 163 This style is new since wxWidgets 2.9.5. 164 @style{wxRIBBON_BAR_SHOW_HELP_BUTTON} 165 Causes a help button to appear on the ribbon bar at the top-right corner. 166 This style is new since wxWidgets 2.9.5. 167 @endStyleTable 168 169 170 @beginEventEmissionTable{wxRibbonBarEvent} 171 @event{EVT_RIBBONBAR_PAGE_CHANGED(id, func)} 172 Triggered after the transition from one page being active to a different 173 page being active. 174 @event{EVT_RIBBONBAR_PAGE_CHANGING(id, func)} 175 Triggered prior to the transition from one page being active to a 176 different page being active, and can veto the change. 177 @event{EVT_RIBBONBAR_TAB_MIDDLE_DOWN(id, func)} 178 Triggered when the middle mouse button is pressed on a tab. 179 @event{EVT_RIBBONBAR_TAB_MIDDLE_UP(id, func)} 180 Triggered when the middle mouse button is released on a tab. 181 @event{EVT_RIBBONBAR_TAB_RIGHT_DOWN(id, func)} 182 Triggered when the right mouse button is pressed on a tab. 183 @event{EVT_RIBBONBAR_TAB_RIGHT_UP(id, func)} 184 Triggered when the right mouse button is released on a tab. 185 @event{EVT_RIBBONBAR_TAB_LEFT_DCLICK(id, func)} 186 Triggered when the left mouse button is double clicked on a tab. 187 @event{EVT_RIBBONBAR_TOGGLED(id, func)} 188 Triggered when the button triggering the ribbon bar is clicked. This 189 event is new since wxWidgets 2.9.5. 190 @event{EVT_RIBBONBAR_HELP_CLICK(id, func)} 191 Triggered when the help button is clicked. This even is new since 192 wxWidgets 2.9.5. 193 @endEventTable 194 195 @library{wxribbon} 196 @category{ribbon} 197 */ 198 class wxRibbonBar : public wxRibbonControl 199 { 200 public: 201 /** 202 Default constructor. 203 With this constructor, Create() should be called in order to create 204 the ribbon bar. 205 */ 206 wxRibbonBar(); 207 208 /** 209 Construct a ribbon bar with the given parameters. 210 */ 211 wxRibbonBar(wxWindow* parent, 212 wxWindowID id = wxID_ANY, 213 const wxPoint& pos = wxDefaultPosition, 214 const wxSize& size = wxDefaultSize, 215 long style = wxRIBBON_BAR_DEFAULT_STYLE); 216 217 /** 218 Create a ribbon bar in two-step ribbon bar construction. 219 Should only be called when the default constructor is used, and 220 arguments have the same meaning as in the full constructor. 221 */ 222 bool Create(wxWindow* parent, 223 wxWindowID id = wxID_ANY, 224 const wxPoint& pos = wxDefaultPosition, 225 const wxSize& size = wxDefaultSize, 226 long style = wxRIBBON_BAR_DEFAULT_STYLE); 227 228 /** 229 Destructor. 230 */ 231 virtual ~wxRibbonBar(); 232 233 /** 234 Set the margin widths (in pixels) on the left and right sides of the 235 tab bar region of the ribbon bar. These margins will be painted with 236 the tab background, but tabs and scroll buttons will never be painted 237 in the margins. 238 239 The left margin could be used for rendering something equivalent to the 240 "Office Button", though this is not currently implemented. The right 241 margin could be used for rendering a help button, and/or MDI buttons, 242 but again, this is not currently implemented. 243 */ 244 void SetTabCtrlMargins(int left, int right); 245 246 /** 247 Set the art provider to be used be the ribbon bar. Also sets the art 248 provider on all current wxRibbonPage children, and any wxRibbonPage 249 children added in the future. 250 251 Note that unlike most other ribbon controls, the ribbon bar creates a 252 default art provider when initialised, so an explicit call to 253 SetArtProvider() is not required if the default art provider is 254 sufficient. Also, unlike other ribbon controls, the ribbon bar takes 255 ownership of the given pointer, and will delete it when the art 256 provider is changed or the bar is destroyed. If this behaviour is not 257 desired, then clone the art provider before setting it. 258 */ 259 void SetArtProvider(wxRibbonArtProvider* art); 260 261 /** 262 Set the active page by index, without triggering any events. 263 264 @param page 265 The zero-based index of the page to activate. 266 @return @true if the specified page is now active, @false if it could 267 not be activated (for example because the page index is invalid). 268 */ 269 bool SetActivePage(size_t page); 270 271 /** 272 Set the active page, without triggering any events. 273 274 @param page 275 The page to activate. 276 @return @true if the specified page is now active, @false if it could 277 not be activated (for example because the given page is not a child 278 of the ribbon bar). 279 */ 280 bool SetActivePage(wxRibbonPage* page); 281 282 /** 283 Get the index of the active page. 284 285 In the rare case of no page being active, -1 is returned. 286 */ 287 int GetActivePage() const; 288 289 /** 290 Get a page by index. 291 292 NULL will be returned if the given index is out of range. 293 */ 294 wxRibbonPage* GetPage(int n); 295 296 /** 297 Get the number of pages in this bar. 298 299 @since 2.9.4 300 */ 301 size_t GetPageCount() const; 302 303 /** 304 Dismiss the expanded panel of the currently active page. 305 306 Calls and returns the value from wxRibbonPage::DismissExpandedPanel() 307 for the currently active page, or @false if there is no active page. 308 */ 309 bool DismissExpandedPanel(); 310 311 /** 312 Returns the number for a given ribbon bar page. 313 314 The number can be used in other ribbon bar calls. 315 316 @since 2.9.5 317 */ 318 int GetPageNumber(wxRibbonPage* page) const; 319 320 /** 321 Delete a single page from this ribbon bar. 322 323 The user must call wxRibbonBar::Realize() after one (or more) calls to 324 this function. 325 326 @since 2.9.4 327 */ 328 void DeletePage(size_t n); 329 330 /** 331 Delete all pages from the ribbon bar. 332 333 @since 2.9.4 334 */ 335 void ClearPages(); 336 337 /** 338 Indicates whether the tab for the given page is shown to the user or 339 not. 340 341 By default all page tabs are shown. 342 343 @since 2.9.5 344 */ 345 bool IsPageShown(size_t page) const; 346 347 /** 348 Show or hide the tab for a given page. 349 350 After showing or hiding a tab, you need to call wxRibbonBar::Realize(). 351 If you hide the tab for the currently active page (GetActivePage) then 352 you should call SetActivePage to activate a different page. 353 354 @since 2.9.5 355 */ 356 void ShowPage(size_t page, bool show_tab=true); 357 358 /** 359 Hides the tab for a given page. 360 361 Equivalent to @c ShowPage(page, false). 362 363 @since 2.9.5 364 */ 365 void HidePage(size_t page); 366 367 /** 368 Indicates whether a tab is currently highlighted. 369 370 @see AddPageHighlight() 371 372 @since 2.9.5 373 */ 374 bool IsPageHighlighted(size_t page) const; 375 376 /** 377 Highlight the specified tab. 378 379 Highlighted tabs have a colour between that of the active tab 380 and a tab over which the mouse is hovering. This can be used 381 to make a tab (usually temporarily) more noticeable to the user. 382 383 @since 2.9.5 384 */ 385 void AddPageHighlight(size_t page, bool highlight = true); 386 387 /** 388 Changes a tab to not be highlighted. 389 390 @see AddPageHighlight() 391 392 @since 2.9.5 393 */ 394 void RemovePageHighlight(size_t page); 395 396 /** 397 Shows or hides the panel area of the ribbon bar. 398 399 If the panel area is hidden, then only the tab of the ribbon bar will 400 be shown. This is useful for giving the user more screen space to work 401 with when he/she doesn't need to see the ribbon's options. 402 403 @since 2.9.2 404 */ 405 void ShowPanels(bool show = true); 406 407 /** 408 Hides the panel area of the ribbon bar. 409 410 This method simply calls ShowPanels() with @false argument. 411 412 @since 2.9.2 413 */ 414 void HidePanels(); 415 416 /** 417 Indicates whether the panel area of the ribbon bar is shown. 418 419 @see ShowPanels() 420 421 @since 2.9.2 422 */ 423 bool ArePanelsShown() const; 424 425 /** 426 Perform initial layout and size calculations of the bar and its 427 children. This must be called after all of the bar's children have been 428 created (and their children created, etc.) - if it is not, then windows 429 may not be laid out or sized correctly. 430 431 Also calls wxRibbonPage::Realize() on each child page. 432 */ 433 virtual bool Realize(); 434 }; 435