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 | wxRIBBON_BAR_SHOW_HELP_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     @style{wxRIBBON_BAR_SHOW_HELP_BUTTON)
  91         Causes a help button to appear on the ribbon bar at the top-right corner.
  92         This style is new since wxWidgets 2.9.5.
  93     @endStyleTable
  94
  95
  96     @beginEventEmissionTable{wxRibbonBarEvent}
  97     @event{EVT_RIBBONBAR_PAGE_CHANGED(id, func)}
  98         Triggered after the transition from one page being active to a different
  99         page being active.
 100     @event{EVT_RIBBONBAR_PAGE_CHANGING(id, func)}
 101         Triggered prior to the transition from one page being active to a
 102         different page being active, and can veto the change.
 103     @event{EVT_RIBBONBAR_TAB_MIDDLE_DOWN(id, func)}
 104         Triggered when the middle mouse button is pressed on a tab.
 105     @event{EVT_RIBBONBAR_TAB_MIDDLE_UP(id, func)}
 106         Triggered when the middle mouse button is released on a tab.
 107     @event{EVT_RIBBONBAR_TAB_RIGHT_DOWN(id, func)}
 108         Triggered when the right mouse button is pressed on a tab.
 109     @event{EVT_RIBBONBAR_TAB_RIGHT_UP(id, func)}
 110         Triggered when the right mouse button is released on a tab.
 111     @event{EVT_RIBBONBAR_TAB_LEFT_DCLICK(id, func)}
 112         Triggered when the left mouse button is double clicked on a tab.
 113     @event{EVT_RIBBONBAR_TOGGLED(id, func)}
 114         Triggered when the button triggering the ribbon bar is clicked. This
 115         event is new since wxWidgets 2.9.5.
 116     @event{EVT_RIBBONBAR_HELP_CLICK(id, func)}
 117         Triggered when the help button is clicked. This even is new since
 118         wxWidgets 2.9.5.
 119     @endEventTable
 120
 121     @library{wxribbon}
 122     @category{ribbon}
 123 */
 124 class wxRibbonBar : public wxRibbonControl
 125 {
 126 public:
 127     /**
 128         Default constructor.
 129         With this constructor, Create() should be called in order to create
 130         the ribbon bar.
 131     */
 132     wxRibbonBar();
 133
 134     /**
 135         Construct a ribbon bar with the given parameters.
 136     */
 137     wxRibbonBar(wxWindow* parent,
 138                 wxWindowID id = wxID_ANY,
 139                 const wxPoint& pos = wxDefaultPosition,
 140                 const wxSize& size = wxDefaultSize,
 141                 long style = wxRIBBON_BAR_DEFAULT_STYLE);
 142
 143     /**
 144         Create a ribbon bar in two-step ribbon bar construction.
 145         Should only be called when the default constructor is used, and
 146         arguments have the same meaning as in the full constructor.
 147     */
 148     bool Create(wxWindow* parent,
 149                 wxWindowID id = wxID_ANY,
 150                 const wxPoint& pos = wxDefaultPosition,
 151                 const wxSize& size = wxDefaultSize,
 152                 long style = wxRIBBON_BAR_DEFAULT_STYLE);
 153
 154     /**
 155         Destructor.
 156     */
 157     virtual ~wxRibbonBar();
 158
 159     /**
 160         Set the margin widths (in pixels) on the left and right sides of the
 161         tab bar region of the ribbon bar. These margins will be painted with
 162         the tab background, but tabs and scroll buttons will never be painted
 163         in the margins.
 164
 165         The left margin could be used for rendering something equivalent to the
 166         "Office Button", though this is not currently implemented. The right
 167         margin could be used for rendering a help button, and/or MDI buttons,
 168         but again, this is not currently implemented.
 169     */
 170     void SetTabCtrlMargins(int left, int right);
 171
 172     /**
 173         Set the art provider to be used be the ribbon bar. Also sets the art
 174         provider on all current wxRibbonPage children, and any wxRibbonPage
 175         children added in the future.
 176
 177         Note that unlike most other ribbon controls, the ribbon bar creates a
 178         default art provider when initialised, so an explicit call to
 179         SetArtProvider() is not required if the default art provider is
 180         sufficient. Also, unlike other ribbon controls, the ribbon bar takes
 181         ownership of the given pointer, and will delete it when the art
 182         provider is changed or the bar is destroyed. If this behaviour is not
 183         desired, then clone the art provider before setting it.
 184     */
 185     void SetArtProvider(wxRibbonArtProvider* art);
 186
 187     /**
 188         Set the active page by index, without triggering any events.
 189
 190         @param page
 191             The zero-based index of the page to activate.
 192         @return @true if the specified page is now active, @false if it could
 193             not be activated (for example because the page index is invalid).
 194     */
 195     bool SetActivePage(size_t page);
 196
 197     /**
 198         Set the active page, without triggering any events.
 199
 200         @param page
 201             The page to activate.
 202         @return @true if the specified page is now active, @false if it could
 203             not be activated (for example because the given page is not a child
 204             of the ribbon bar).
 205     */
 206     bool SetActivePage(wxRibbonPage* page);
 207
 208     /**
 209         Get the index of the active page.
 210
 211         In the rare case of no page being active, -1 is returned.
 212     */
 213     int GetActivePage() const;
 214
 215     /**
 216         Get a page by index.
 217
 218         NULL will be returned if the given index is out of range.
 219     */
 220     wxRibbonPage* GetPage(int n);
 221
 222     /**
 223         Get the number of pages in this bar.
 224
 225         @since 2.9.4
 226     */
 227     size_t GetPageCount() const;
 228
 229     /**
 230         Dismiss the expanded panel of the currently active page.
 231
 232         Calls and returns the value from wxRibbonPage::DismissExpandedPanel()
 233         for the currently active page, or @false if there is no active page.
 234     */
 235     bool DismissExpandedPanel();
 236
 237     /**
 238         Returns the number for a given ribbon bar page.
 239
 240         The number can be used in other ribbon bar calls.
 241
 242         @since 2.9.5
 243     */
 244     int GetPageNumber(wxRibbonPage* page) const;
 245
 246     /**
 247         Delete a single page from this ribbon bar.
 248
 249         The user must call wxRibbonBar::Realize() after one (or more) calls to
 250         this function.
 251
 252         @since 2.9.4
 253     */
 254     void DeletePage(size_t n);
 255
 256     /**
 257         Delete all pages from the ribbon bar.
 258
 259         @since 2.9.4
 260     */
 261     void ClearPages();
 262
 263     /**
 264         Indicates whether the tab for the given page is shown to the user or
 265         not.
 266
 267         By default all page tabs are shown.
 268
 269         @since 2.9.5
 270     */
 271     bool IsPageShown(size_t page) const;
 272
 273     /**
 274         Show or hide the tab for a given page.
 275
 276         After showing or hiding a tab, you need to call wxRibbonBar::Realize().
 277         If you hide the tab for the currently active page (GetActivePage) then
 278         you should call SetActivePage to activate a different page.
 279
 280         @since 2.9.5
 281     */
 282     void ShowPage(size_t page, bool show_tab=true);
 283
 284     /**
 285         Hides the tab for a given page.
 286
 287         Equivalent to @c ShowPage(page, false).
 288
 289         @since 2.9.5
 290     */
 291     void HidePage(size_t page);
 292
 293     /**
 294         Indicates whether a tab is currently highlighted.
 295
 296         @see AddPageHighlight()
 297
 298         @since 2.9.5
 299     */
 300     bool IsPageHighlighted(size_t page) const;
 301
 302     /**
 303         Highlight the specified tab.
 304
 305         Highlighted tabs have a colour between that of the active tab
 306         and a tab over which the mouse is hovering. This can be used
 307         to make a tab (usually temporarily) more noticeable to the user.
 308
 309         @since 2.9.5
 310     */
 311     void AddPageHighlight(size_t page, bool highlight = true);
 312
 313     /**
 314         Changes a tab to not be highlighted.
 315
 316         @see AddPageHighlight()
 317
 318         @since 2.9.5
 319     */
 320     void RemovePageHighlight(size_t page);
 321
 322     /**
 323         Shows or hides the panel area of the ribbon bar.
 324
 325         If the panel area is hidden, then only the tab of the ribbon bar will
 326         be shown. This is useful for giving the user more screen space to work
 327         with when he/she doesn't need to see the ribbon's options.
 328
 329         @since 2.9.2
 330     */
 331     void ShowPanels(bool show = true);
 332
 333     /**
 334         Hides the panel area of the ribbon bar.
 335
 336         This method simply calls ShowPanels() with @false argument.
 337
 338         @since 2.9.2
 339     */
 340     void HidePanels();
 341
 342     /**
 343         Indicates whether the panel area of the ribbon bar is shown.
 344
 345         @see ShowPanels()
 346
 347         @since 2.9.2
 348     */
 349     bool ArePanelsShown() const;
 350
 351     /**
 352         Perform initial layout and size calculations of the bar and its
 353         children. This must be called after all of the bar's children have been
 354         created (and their children created, etc.) - if it is not, then windows
 355         may not be laid out or sized correctly.
 356
 357         Also calls wxRibbonPage::Realize() on each child page.
 358     */
 359     virtual bool Realize();
 360 };