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

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/page.h
// Purpose:     interface of wxRibbonPage
// Author:      Peter Cawley
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

/**
    @class wxRibbonPage

    Container for related ribbon panels, and a tab within a ribbon bar.
    
    @see wxRibbonBar
    @see wxRibbonPanel

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

    /**
        Constructs a ribbon page, which must be a child of a ribbon bar.
    
        @param parent
            Pointer to a parent wxRibbonBar (unlike most controls, a wxRibbonPage
            can only have wxRibbonBar as a parent).
        @param id
            Window identifier.
        @param label
            Label to be used in the wxRibbonBar's tab list for this page (if the
            ribbon bar is set to display labels).
        @param icon
            Icon to be used in the wxRibbonBar's tab list for this page (if the
            ribbon bar is set to display icons).
        @param style
            Currently unused, should be zero.
    */
    wxRibbonPage(wxRibbonBar* parent,
                wxWindowID id = wxID_ANY,
                const wxString& label = wxEmptyString,
                const wxBitmap& icon = wxNullBitmap,
                long style = 0);

    /**
        Destructor.
    */
    virtual ~wxRibbonPage();
    
    /**
        Create a ribbon page in two-step ribbon page construction.
        Should only be called when the default constructor is used, and
        arguments have the same meaning as in the full constructor.
    */
    bool Create(wxRibbonBar* parent,
                wxWindowID id = wxID_ANY,
                const wxString& label = wxEmptyString,
                const wxBitmap& icon = wxNullBitmap,
                long style = 0);

    /**
        Set the art provider to be used. Normally called automatically by
        wxRibbonBar when the page is created, or the art provider changed on the
        bar.
    
        The new art provider will be propagated to the children of the page.
    */
    void SetArtProvider(wxRibbonArtProvider* art);

    /**
        Get the icon used for the page in the ribbon bar tab area (only
        displayed if the ribbon bar is actually showing icons).
    */
    wxBitmap& GetIcon();
  
    /**
        Set the size of the page and the external scroll buttons (if any).
    
        When a page is too small to display all of its children, scroll buttons
        will appear (and if the page is sized up enough, they will disappear again).
        Slightly counter-intuitively, these buttons are created as siblings of the
        page rather than children of the page (to achieve correct cropping and
        paint ordering of the children and the buttons). When there are no scroll
        buttons, this function behaves the same as SetSize(), however when there
        are scroll buttons, it positions them at the edges of the given area, and
        then calls SetSize() with the remaining area.
    
        This is provided as a separate function to SetSize() rather than within
        the implementation of SetSize(), as interacting algorithms may not expect
        SetSize() to also set the size of siblings.
    */
    void SetSizeWithScrollButtonAdjustment(int x, int y, int width, int height);
    
    /**
        Expand a rectangle of the page to include external scroll buttons (if
        any). When no scroll buttons are shown, has no effect.
        
        @param[in,out] rect
            The rectangle to adjust. The width and height will not be reduced,
            and the x and y will not be increased.
    */
    void AdjustRectToIncludeScrollButtons(wxRect* rect) const;
    
    /**
        Dismiss the current externally expanded panel, if there is one.
        
        When a ribbon panel automatically minimises, it can be externally
        expanded into a floating window. When the user clicks a button in such
        a panel, the panel should generally re-minimise. Event handlers for
        buttons on ribbon panels should call this method to achieve this
        behaviour.
        
        @return @true if a panel was minimised, @false otherwise.
    */
    bool DismissExpandedPanel();
    
    /**
        Perform a full re-layout of all panels on the page.
        
        Should be called after panels are added to the page, or the sizing
        behaviour of a panel on the page changes (i.e. due to children being
        added to it). Usually called automatically when wxRibbonBar::Realize()
        is called.
        
        Will invoke wxRibbonPanel::Realize() for all child panels.
    */
    virtual bool Realize();

    /**
        Scroll the page by some amount up / down / left / right.
    
        When the page's children are too big to fit in the onscreen area given to
        the page, scroll buttons will appear, and the page can be programmatically
        scrolled. Positive values of @a lines will scroll right or down, while
        negative values will scroll up or left (depending on the direction in which
        panels are stacked). A line is equivalent to a constant number of pixels.
    
        @return @true if the page scrolled at least one pixel in the given
            direction, @false if it did not scroll.
    
        @see GetMajorAxis()
        @see ScrollPixels()
        @see ScrollSections()
    */
    virtual bool ScrollLines(int lines);
  
    /**
        Scroll the page by a set number of pixels up / down / left / right.
    
        When the page's children are too big to fit in the onscreen area given to
        the page, scroll buttons will appear, and the page can be programmatically
        scrolled. Positive values of @a lines will scroll right or down, while
        negative values will scroll up or left (depending on the direction in which
        panels are stacked).
    
        @return @true if the page scrolled at least one pixel in the given
            direction, @false if it did not scroll.
    
        @see GetMajorAxis()
        @see ScrollLines()
        @see ScrollSections()
    */
    bool ScrollPixels(int pixels);

    /**
        Scroll the page by an entire child section.

        The @a sections parameter value should be 1 or -1. This will scroll
        enough to uncover a partially visible child section or totally uncover
        the next child section that may not be visible at all.

        @return @true if the page scrolled at least one pixel in the given
            direction, @false if it did not scroll.

        @see ScrollPixels()
        @see ScrollSections()

        @since 2.9.5
    */
    bool ScrollSections(int sections);

    /**
        Get the direction in which ribbon panels are stacked within the page.
    
        This is controlled by the style of the containing wxRibbonBar, meaning
        that all pages within a bar will have the same major axis. As well as
        being the direction in which panels are stacked, it is also the axis in
        which scrolling will occur (when required).
    
        @return wxHORIZONTAL or wxVERTICAL (never wxBOTH).
    */
    wxOrientation GetMajorAxis() const;
};
Commit	Line	Data
3c3ead1d PC	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: ribbon/page.h
	3	// Purpose: interface of wxRibbonPage
	4	// Author: Peter Cawley
3c3ead1d PC	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
57ab6f23	79	displayed if the ribbon bar is actually showing icons).
3c3ead1d PC	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).
57ab6f23	88	Slightly counter-intuitively, these buttons are created as siblings of the
3c3ead1d PC	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
57ab6f23	96	the implementation of SetSize(), as interacting algorithms may not expect
3c3ead1d PC	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
57ab6f23	140	the page, scroll buttons will appear, and the page can be programmatically
3c3ead1d PC	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()
0a72cae7	150	@see ScrollSections()
3c3ead1d PC	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
57ab6f23	158	the page, scroll buttons will appear, and the page can be programmatically
3c3ead1d PC	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()
0a72cae7	168	@see ScrollSections()
3c3ead1d PC	169	*/
	170	bool ScrollPixels(int pixels);
	171
0a72cae7 VZ	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
3c3ead1d PC	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	};