[wxWidgets.git] / interface / wx / ribbon / bar.h

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/bar.h
// Purpose:     interface of wxRibbonBar
// Author:      Peter Cawley
// RCS-ID:      $Id$
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

/**
    @class wxRibbonBarEvent

    Event used to indicate various actions relating to a wxRibbonBar.

    See wxRibbonBar for available event types.

    @library{wxribbon}
    @category{events,ribbon}

    @see wxRibbonBar
*/
class wxRibbonBarEvent : public wxNotifyEvent
{
public:
    /**
        Constructor.
    */
    wxRibbonBarEvent(wxEventType command_type = wxEVT_NULL,
                     int win_id = 0,
                     wxRibbonPage* page = NULL);

    /**
        Returns the page being changed to, or being clicked on.
    */
    wxRibbonPage* GetPage();
    
    /**
        Sets the page relating to this event.
    */
    void SetPage(wxRibbonPage* page);
};

/**
    @class wxRibbonBar

    Top-level control in a ribbon user interface. Serves as a tabbed container
    for wxRibbonPage - a ribbon user interface typically has a ribbon bar,
    which contains one or more wxRibbonPages, which in turn each contain one
    or more wxRibbonPanels, which in turn contain controls.
    
    While a wxRibbonBar has tabs similar to a wxNotebook, it does not follow
    the same API for adding pages. Containers like wxNotebook can contain any
    type of window as a page, hence the normal procedure is to create the
    sub-window and then call wxBookCtrlBase::AddPage(). As wxRibbonBar can only
    have wxRibbonPage as children (and a wxRibbonPage can only have a
    wxRibbonBar as parent), when a page is created, it is automatically added
    to the bar - there is no AddPage equivalent to call.
    
    After all pages have been created, and all controls and panels placed on
    those pages, Realize() must be called.
    
    @sa wxRibbonPage
    @sa wxRibbonPanel
    
    @beginStyleTable
    @style{wxRIBBON_BAR_DEFAULT_STYLE}
        Defined as wxRIBBON_BAR_FLOW_HORIZONTAL |
        wxRIBBON_BAR_SHOW_PAGE_LABELS | wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS
    @style{wxRIBBON_BAR_FOLDBAR_STYLE}
        Defined as wxRIBBON_BAR_FLOW_VERTICAL | wxRIBBON_BAR_SHOW_PAGE_ICONS
        | wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS |
        wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS
    @style{wxRIBBON_BAR_SHOW_PAGE_LABELS}
        Causes labels to be shown on the tabs in the ribbon bar.
    @style{wxRIBBON_BAR_SHOW_PAGE_ICONS}
        Causes icons to be shown on the tabs in the ribbon bar.
    @style{wxRIBBON_BAR_FLOW_HORIZONTAL}
        Causes panels within pages to stack horizontally.
    @style{wxRIBBON_BAR_FLOW_VERTICAL}
        Causes panels within pages to stack vertically.
    @style{wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS}
        Causes extension buttons to be shown on panels (where the panel has
        such a button).
    @style{wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS}
        Causes minimise buttons to be shown on panels (where the panel has
        such a button).
    @endStyleTable


    @beginEventEmissionTable{wxRibbonBarEvent}
    @event{EVT_RIBBONBAR_PAGE_CHANGED(id, func)}
        Triggered after the transition from one page being active to a different
        page being active.
    @event{EVT_RIBBONBAR_PAGE_CHANGING(id, func)}
        Triggered prior to the transition from one page being active to a
        different page being active, and can veto the change.
    @event{EVT_RIBBONBAR_TAB_MIDDLE_DOWN(id, func)}
        Triggered when the middle mouse button is pressed on a tab.
    @event{EVT_RIBBONBAR_TAB_MIDDLE_UP(id, func)}
        Triggered when the middle mouse button is released on a tab.
    @event{EVT_RIBBONBAR_TAB_RIGHT_DOWN(id, func)}
        Triggered when the right mouse button is pressed on a tab.
    @event{EVT_RIBBONBAR_TAB_RIGHT_UP(id, func)}
        Triggered when the right mouse button is released on a tab.
    @endEventTable

    @library{wxribbon}
    @category{ribbon}
*/
class wxRibbonBar : public wxRibbonControl
{
public:
    /**
        Default constructor.
        With this constructor, Create() should be called in order to create
        the ribbon bar.
    */
    wxRibbonBar();

    /**
        Construct a ribbon bar with the given parameters.
    */
    wxRibbonBar(wxWindow* parent,
                wxWindowID id = wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = wxRIBBON_BAR_DEFAULT_STYLE);
    
    /**
        Create a ribbon bar in two-step ribbon bar construction.
        Should only be called when the default constructor is used, and
        arguments have the same meaning as in the full constructor.
    */
    bool Create(wxWindow* parent,
                wxWindowID id = wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = wxRIBBON_BAR_DEFAULT_STYLE);

    /**
        Destructor.
    */
    virtual ~wxRibbonBar();

    /**
        Set the margin widths (in pixels) on the left and right sides of the
        tab bar region of the ribbon bar. These margins will be painted with
        the tab background, but tabs and scroll buttons will never be painted
        in the margins.
        
        The left margin could be used for rendering something equivalent to the
        "Office Button", though this is not currently implemented. The right
        margin could be used for rendering a help button, and/or MDI buttons,
        but again, this is not currently implemented.
    */
    void SetTabCtrlMargins(int left, int right);

    /**
        Set the art provider to be used be the ribbon bar. Also sets the art
        provider on all current wxRibbonPage children, and any wxRibbonPage
        children added in the future.
        
        Note that unlike most other ribbon controls, the ribbon bar creates a
        default art provider when initialised, so an explicit call to
        SetArtProvider() is not required if the default art provider is
        sufficient. Alos unlike other ribbon controls, the ribbon bar takes
        ownership of the given pointer, and will delete it when the art
        provider is changed or the bar is destroyed. If this behaviour is not
        desired, then clone the art provider before setting it.
    */
    void SetArtProvider(wxRibbonArtProvider* art);

    /**
        Set the active page by index, without triggering any events.
        
        @param page
            The zero-based index of the page to activate.
        @return @true if the specified page is now active, @false if it could
            not be activated (for example because the page index is invalid).
    */
    bool SetActivePage(size_t page);
    
    /**
        Set the active page, without triggering any events.
        
        @param page
            The page to activate.
        @return @true if the specified page is now active, @false if it could
            not be activated (for example because the given page is not a child
            of the ribbon bar).
    */
    bool SetActivePage(wxRibbonPage* page);
    
    /**
        Get the index of the active page.
        
        In the rare case of no page being active, -1 is returned.
    */
    int GetActivePage() const;
    
    /**
        Get a page by index.
        
        NULL will be returned if the given index is out of range.
    */
    wxRibbonPage* GetPage(int n);
    
    /**
        Dismiss the expanded panel of the currently active page.
        
        Calls and returns the value fromwxRibbonPage::DismissExpandedPanel()
        for the currently active page, or @false if there is no active page.
    */
    bool DismissExpandedPanel();
    
    /**
        Perform initial layout and size calculations of the bar and its
        children. This must be called after all of the bar's children have been
        created (and their children created, etc.) - if it is not, then windows
        may not be laid out or sized correctly.
        
        Also calls wxRibbonPage::Realize() on each child page.
    */
    virtual bool Realize();
};
Commit	Line	Data
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	*/
	21	class wxRibbonBarEvent : public wxNotifyEvent
	22	{
	23	public:
	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 \|
	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	};