interface/wx/ribbon/bar.h

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