1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxRibbonBar
4 // Author: Peter Cawley
6 // Licence: wxWindows licence
7 ///////////////////////////////////////////////////////////////////////////////
10 @class wxRibbonBarEvent
12 Event used to indicate various actions relating to a wxRibbonBar.
14 See wxRibbonBar for available event types.
17 @category{events,ribbon}
21 class wxRibbonBarEvent
: public wxNotifyEvent
27 wxRibbonBarEvent(wxEventType command_type
= wxEVT_NULL
,
29 wxRibbonPage
* page
= NULL
);
32 Returns the page being changed to, or being clicked on.
34 wxRibbonPage
* GetPage();
37 Sets the page relating to this event.
39 void SetPage(wxRibbonPage
* page
);
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.
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.
58 After all pages have been created, and all controls and panels placed on
59 those pages, Realize() must be called.
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
83 @style{wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS}
84 Causes minimise buttons to be shown on panels (where the panel has
89 @beginEventEmissionTable{wxRibbonBarEvent}
90 @event{EVT_RIBBONBAR_PAGE_CHANGED(id, func)}
91 Triggered after the transition from one page being active to a different
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.
109 class wxRibbonBar
: public wxRibbonControl
114 With this constructor, Create() should be called in order to create
120 Construct a ribbon bar with the given parameters.
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
);
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.
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
);
142 virtual ~wxRibbonBar();
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
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.
155 void SetTabCtrlMargins(int left
, int right
);
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.
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.
170 void SetArtProvider(wxRibbonArtProvider
* art
);
173 Set the active page by index, without triggering any events.
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).
180 bool SetActivePage(size_t page
);
183 Set the active page, without triggering any events.
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
191 bool SetActivePage(wxRibbonPage
* page
);
194 Get the index of the active page.
196 In the rare case of no page being active, -1 is returned.
198 int GetActivePage() const;
203 NULL will be returned if the given index is out of range.
205 wxRibbonPage
* GetPage(int n
);
208 Dismiss the expanded panel of the currently active page.
210 Calls and returns the value fromwxRibbonPage::DismissExpandedPanel()
211 for the currently active page, or @false if there is no active page.
213 bool DismissExpandedPanel();
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.
221 Also calls wxRibbonPage::Realize() on each child page.
223 virtual bool Realize();