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