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

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