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     @endEventTable
 105
 106     @library{wxribbon}
 107     @category{ribbon}
 108 */
 109 class wxRibbonBar : public wxRibbonControl
 110 {
 111 public:
 112     /**
 113         Default constructor.
 114         With this constructor, Create() should be called in order to create
 115         the ribbon bar.
 116     */
 117     wxRibbonBar();
 118
 119     /**
 120         Construct a ribbon bar with the given parameters.
 121     */
 122     wxRibbonBar(wxWindow* parent,
 123                 wxWindowID id = wxID_ANY,
 124                 const wxPoint& pos = wxDefaultPosition,
 125                 const wxSize& size = wxDefaultSize,
 126                 long style = wxRIBBON_BAR_DEFAULT_STYLE);
 127
 128     /**
 129         Create a ribbon bar in two-step ribbon bar construction.
 130         Should only be called when the default constructor is used, and
 131         arguments have the same meaning as in the full constructor.
 132     */
 133     bool Create(wxWindow* parent,
 134                 wxWindowID id = wxID_ANY,
 135                 const wxPoint& pos = wxDefaultPosition,
 136                 const wxSize& size = wxDefaultSize,
 137                 long style = wxRIBBON_BAR_DEFAULT_STYLE);
 138
 139     /**
 140         Destructor.
 141     */
 142     virtual ~wxRibbonBar();
 143
 144     /**
 145         Set the margin widths (in pixels) on the left and right sides of the
 146         tab bar region of the ribbon bar. These margins will be painted with
 147         the tab background, but tabs and scroll buttons will never be painted
 148         in the margins.
 149
 150         The left margin could be used for rendering something equivalent to the
 151         "Office Button", though this is not currently implemented. The right
 152         margin could be used for rendering a help button, and/or MDI buttons,
 153         but again, this is not currently implemented.
 154     */
 155     void SetTabCtrlMargins(int left, int right);
 156
 157     /**
 158         Set the art provider to be used be the ribbon bar. Also sets the art
 159         provider on all current wxRibbonPage children, and any wxRibbonPage
 160         children added in the future.
 161
 162         Note that unlike most other ribbon controls, the ribbon bar creates a
 163         default art provider when initialised, so an explicit call to
 164         SetArtProvider() is not required if the default art provider is
 165         sufficient. Alos unlike other ribbon controls, the ribbon bar takes
 166         ownership of the given pointer, and will delete it when the art
 167         provider is changed or the bar is destroyed. If this behaviour is not
 168         desired, then clone the art provider before setting it.
 169     */
 170     void SetArtProvider(wxRibbonArtProvider* art);
 171
 172     /**
 173         Set the active page by index, without triggering any events.
 174
 175         @param page
 176             The zero-based index of the page to activate.
 177         @return @true if the specified page is now active, @false if it could
 178             not be activated (for example because the page index is invalid).
 179     */
 180     bool SetActivePage(size_t page);
 181
 182     /**
 183         Set the active page, without triggering any events.
 184
 185         @param page
 186             The page to activate.
 187         @return @true if the specified page is now active, @false if it could
 188             not be activated (for example because the given page is not a child
 189             of the ribbon bar).
 190     */
 191     bool SetActivePage(wxRibbonPage* page);
 192
 193     /**
 194         Get the index of the active page.
 195
 196         In the rare case of no page being active, -1 is returned.
 197     */
 198     int GetActivePage() const;
 199
 200     /**
 201         Get a page by index.
 202
 203         NULL will be returned if the given index is out of range.
 204     */
 205     wxRibbonPage* GetPage(int n);
 206
 207     /**
 208         Dismiss the expanded panel of the currently active page.
 209
 210         Calls and returns the value fromwxRibbonPage::DismissExpandedPanel()
 211         for the currently active page, or @false if there is no active page.
 212     */
 213     bool DismissExpandedPanel();
 214
 215     /**
 216         Perform initial layout and size calculations of the bar and its
 217         children. This must be called after all of the bar's children have been
 218         created (and their children created, etc.) - if it is not, then windows
 219         may not be laid out or sized correctly.
 220
 221         Also calls wxRibbonPage::Realize() on each child page.
 222     */
 223     virtual bool Realize();
 224 };