]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/ribbon/bar.h
Add files necessary to run Expat configure.
[wxWidgets.git] / interface / wx / ribbon / bar.h
CommitLineData
3c3ead1d
PC
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*/
21class wxRibbonBarEvent : public wxNotifyEvent
22{
23public:
24 /**
25 Constructor.
26 */
dc735b40
FM
27 wxRibbonBarEvent(wxEventType command_type = wxEVT_NULL,
28 int win_id = 0,
29 wxRibbonPage* page = NULL);
3c3ead1d
PC
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 |
7c70331e 67 wxRIBBON_BAR_SHOW_PAGE_LABELS | wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS |
42d73941 68 wxRIBBON_BAR_SHOW_TOGGLE_BUTTON | wxRIBBON_BAR_SHOW_HELP_BUTTON.
3c3ead1d
PC
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).
7c70331e
VZ
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.
7be2a7af 90 @style{wxRIBBON_BAR_SHOW_HELP_BUTTON}
42d73941
VZ
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.
3c3ead1d
PC
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.
a65b84f4
VZ
111 @event{EVT_RIBBONBAR_TAB_LEFT_DCLICK(id, func)}
112 Triggered when the left mouse button is double clicked on a tab.
42d73941 113 @event{EVT_RIBBONBAR_TOGGLED(id, func)}
7c70331e
VZ
114 Triggered when the button triggering the ribbon bar is clicked. This
115 event is new since wxWidgets 2.9.5.
42d73941
VZ
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.
3c3ead1d
PC
119 @endEventTable
120
121 @library{wxribbon}
122 @category{ribbon}
123*/
124class wxRibbonBar : public wxRibbonControl
125{
126public:
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
57ab6f23 180 sufficient. Also, unlike other ribbon controls, the ribbon bar takes
3c3ead1d
PC
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
c21b99e0
VZ
222 /**
223 Get the number of pages in this bar.
224
225 @since 2.9.4
226 */
227 size_t GetPageCount() const;
228
3c3ead1d
PC
229 /**
230 Dismiss the expanded panel of the currently active page.
231
c21b99e0 232 Calls and returns the value from wxRibbonPage::DismissExpandedPanel()
3c3ead1d
PC
233 for the currently active page, or @false if there is no active page.
234 */
235 bool DismissExpandedPanel();
3603e565 236
5c14ec26
VZ
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
c21b99e0
VZ
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
5c14ec26
VZ
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
70f86ded
VZ
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
3603e565
VZ
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;
3c3ead1d
PC
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};