git.saurik.com Git - wxWidgets.git/blame_incremental

... / ...

Commit	Line	Data
	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: ribbon/page.h
	3	// Purpose: interface of wxRibbonPage
	4	// Author: Peter Cawley
	5	// Licence: wxWindows licence
	6	///////////////////////////////////////////////////////////////////////////////
	7
	8	/**
	9	@class wxRibbonPage
	10
	11	Container for related ribbon panels, and a tab within a ribbon bar.
	12
	13	@see wxRibbonBar
	14	@see wxRibbonPanel
	15
	16	@library{wxribbon}
	17	@category{ribbon}
	18	*/
	19	class wxRibbonPage : public wxRibbonControl
	20	{
	21	public:
	22	/**
	23	Default constructor.
	24	With this constructor, Create() should be called in order to create
	25	the ribbon page.
	26	*/
	27	wxRibbonPage();
	28
	29	/**
	30	Constructs a ribbon page, which must be a child of a ribbon bar.
	31
	32	@param parent
	33	Pointer to a parent wxRibbonBar (unlike most controls, a wxRibbonPage
	34	can only have wxRibbonBar as a parent).
	35	@param id
	36	Window identifier.
	37	@param label
	38	Label to be used in the wxRibbonBar's tab list for this page (if the
	39	ribbon bar is set to display labels).
	40	@param icon
	41	Icon to be used in the wxRibbonBar's tab list for this page (if the
	42	ribbon bar is set to display icons).
	43	@param style
	44	Currently unused, should be zero.
	45	*/
	46	wxRibbonPage(wxRibbonBar* parent,
	47	wxWindowID id = wxID_ANY,
	48	const wxString& label = wxEmptyString,
	49	const wxBitmap& icon = wxNullBitmap,
	50	long style = 0);
	51
	52	/**
	53	Destructor.
	54	*/
	55	virtual ~wxRibbonPage();
	56
	57	/**
	58	Create a ribbon page in two-step ribbon page construction.
	59	Should only be called when the default constructor is used, and
	60	arguments have the same meaning as in the full constructor.
	61	*/
	62	bool Create(wxRibbonBar* parent,
	63	wxWindowID id = wxID_ANY,
	64	const wxString& label = wxEmptyString,
	65	const wxBitmap& icon = wxNullBitmap,
	66	long style = 0);
	67
	68	/**
	69	Set the art provider to be used. Normally called automatically by
	70	wxRibbonBar when the page is created, or the art provider changed on the
	71	bar.
	72
	73	The new art provider will be propagated to the children of the page.
	74	*/
	75	void SetArtProvider(wxRibbonArtProvider* art);
	76
	77	/**
	78	Get the icon used for the page in the ribbon bar tab area (only
	79	displayed if the ribbon bar is actually showing icons).
	80	*/
	81	wxBitmap& GetIcon();
	82
	83	/**
	84	Set the size of the page and the external scroll buttons (if any).
	85
	86	When a page is too small to display all of its children, scroll buttons
	87	will appear (and if the page is sized up enough, they will disappear again).
	88	Slightly counter-intuitively, these buttons are created as siblings of the
	89	page rather than children of the page (to achieve correct cropping and
	90	paint ordering of the children and the buttons). When there are no scroll
	91	buttons, this function behaves the same as SetSize(), however when there
	92	are scroll buttons, it positions them at the edges of the given area, and
	93	then calls SetSize() with the remaining area.
	94
	95	This is provided as a separate function to SetSize() rather than within
	96	the implementation of SetSize(), as interacting algorithms may not expect
	97	SetSize() to also set the size of siblings.
	98	*/
	99	void SetSizeWithScrollButtonAdjustment(int x, int y, int width, int height);
	100
	101	/**
	102	Expand a rectangle of the page to include external scroll buttons (if
	103	any). When no scroll buttons are shown, has no effect.
	104
	105	@param[in,out] rect
	106	The rectangle to adjust. The width and height will not be reduced,
	107	and the x and y will not be increased.
	108	*/
	109	void AdjustRectToIncludeScrollButtons(wxRect* rect) const;
	110
	111	/**
	112	Dismiss the current externally expanded panel, if there is one.
	113
	114	When a ribbon panel automatically minimises, it can be externally
	115	expanded into a floating window. When the user clicks a button in such
	116	a panel, the panel should generally re-minimise. Event handlers for
	117	buttons on ribbon panels should call this method to achieve this
	118	behaviour.
	119
	120	@return @true if a panel was minimised, @false otherwise.
	121	*/
	122	bool DismissExpandedPanel();
	123
	124	/**
	125	Perform a full re-layout of all panels on the page.
	126
	127	Should be called after panels are added to the page, or the sizing
	128	behaviour of a panel on the page changes (i.e. due to children being
	129	added to it). Usually called automatically when wxRibbonBar::Realize()
	130	is called.
	131
	132	Will invoke wxRibbonPanel::Realize() for all child panels.
	133	*/
	134	virtual bool Realize();
	135
	136	/**
	137	Scroll the page by some amount up / down / left / right.
	138
	139	When the page's children are too big to fit in the onscreen area given to
	140	the page, scroll buttons will appear, and the page can be programmatically
	141	scrolled. Positive values of @a lines will scroll right or down, while
	142	negative values will scroll up or left (depending on the direction in which
	143	panels are stacked). A line is equivalent to a constant number of pixels.
	144
	145	@return @true if the page scrolled at least one pixel in the given
	146	direction, @false if it did not scroll.
	147
	148	@see GetMajorAxis()
	149	@see ScrollPixels()
	150	@see ScrollSections()
	151	*/
	152	virtual bool ScrollLines(int lines);
	153
	154	/**
	155	Scroll the page by a set number of pixels up / down / left / right.
	156
	157	When the page's children are too big to fit in the onscreen area given to
	158	the page, scroll buttons will appear, and the page can be programmatically
	159	scrolled. Positive values of @a lines will scroll right or down, while
	160	negative values will scroll up or left (depending on the direction in which
	161	panels are stacked).
	162
	163	@return @true if the page scrolled at least one pixel in the given
	164	direction, @false if it did not scroll.
	165
	166	@see GetMajorAxis()
	167	@see ScrollLines()
	168	@see ScrollSections()
	169	*/
	170	bool ScrollPixels(int pixels);
	171
	172	/**
	173	Scroll the page by an entire child section.
	174
	175	The @a sections parameter value should be 1 or -1. This will scroll
	176	enough to uncover a partially visible child section or totally uncover
	177	the next child section that may not be visible at all.
	178
	179	@return @true if the page scrolled at least one pixel in the given
	180	direction, @false if it did not scroll.
	181
	182	@see ScrollPixels()
	183	@see ScrollSections()
	184
	185	@since 2.9.5
	186	*/
	187	bool ScrollSections(int sections);
	188
	189	/**
	190	Get the direction in which ribbon panels are stacked within the page.
	191
	192	This is controlled by the style of the containing wxRibbonBar, meaning
	193	that all pages within a bar will have the same major axis. As well as
	194	being the direction in which panels are stacked, it is also the axis in
	195	which scrolling will occur (when required).
	196
	197	@return wxHORIZONTAL or wxVERTICAL (never wxBOTH).
	198	*/
	199	wxOrientation GetMajorAxis() const;
	200	};