interface/wx/ribbon/bar.h

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