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

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

/**
    @class wxRibbonControl

    wxRibbonControl serves as a base class for all controls which share the
    ribbon charactertics of having a ribbon art provider, and (optionally)
    non-continous resizing. Despite what the name may imply, it is not the
    top-level control for creating a ribbon interface - that is wxRibbonBar.
  
    Ribbon controls often have a region which is "transparent", and shows the
    contents of the ribbon page or panel behind it. If implementing a new
    ribbon control, then it may be useful to realise that this effect is done
    by the art provider when painting the background of the control, and hence
    in the paint handler for the new control, you should call a draw background
    method on the art provider (wxRibbonArtProvider::DrawButtonBarBackground()
    and wxRibbonArtProvider::DrawToolBarBackground() typically just redraw what
    is behind the rectangle being painted) if you want transparent regions.

    @library{wxribbon}
    @category{ribbon}
*/
class wxRibbonControl : public wxControl
{
public:
    /**
        Constructor.
    */
    wxRibbonControl();

    /**
        Constructor.
        
        If @a parent is a wxRibbonControl with a non-NULL art provider, then
        the art provider of new control is set to that of @a parent.
    */
    wxRibbonControl(wxWindow *parent, wxWindowID id,
                    const wxPoint& pos = wxDefaultPosition,
                    const wxSize& size = wxDefaultSize, long style = 0,
                    const wxValidator& validator = wxDefaultValidator,
                    const wxString& name = wxControlNameStr);

    /**
        Set the art provider to be used. In many cases, setting the art provider
        will also set the art provider on all child windows which extend
        wxRibbonControl.
        
        In most cases, controls will not take ownership of the given pointer,
        with the notable exception being wxRibbonBar::SetArtProvider().
    */
    virtual void SetArtProvider(wxRibbonArtProvider* art);
    
    /**
        Get the art provider to be used. Note that until an art provider has
        been set in some way, this function may return NULL.
    */
    wxRibbonArtProvider* GetArtProvider() const;

    /**
        @return @true if this window can take any size (greater than its minimum
        size), @false if it can only take certain sizes.
        
        @see GetNextSmallerSize()
        @see GetNextLargerSize()
    */
    virtual bool IsSizingContinuous() const;
    
    /**
        If sizing is not continuous, then return a suitable size for the control
        which is smaller than the current size.
    
        @param direction
            The direction(s) in which the size should reduce.
        @return
            The current size if there is no smaller size, otherwise a suitable
            size which is smaller in the given direction(s), and the same as the
            current size in the other direction (if any).
      
        @see IsSizingContinuous()
    */
    wxSize GetNextSmallerSize(wxOrientation direction) const;
    
    /**
        If sizing is not continuous, then return a suitable size for the control
        which is smaller than the given size.
    
        @param direction
            The direction(s) in which the size should reduce.
        @param relative_to
            The size for which a smaller size should be found.
        @return
            @a relative_to if there is no smaller size, otherwise a suitable
            size which is smaller in the given direction(s), and the same as
            @a relative_to in the other direction (if any).
      
        @see IsSizingContinuous()
        @see DoGetNextSmallerSize()
    */
    wxSize GetNextSmallerSize(wxOrientation direction, wxSize relative_to) const;
    
    /**
        If sizing is not continuous, then return a suitable size for the control
        which is larger then the current size.
    
        @param direction
            The direction(s) in which the size should increase.
        @return
            The current size if there is no larger size, otherwise a suitable
            size which is larger in the given direction(s), and the same as the
            current size in the other direction (if any).
    
        @see IsSizingContinuous()
    */
    wxSize GetNextLargerSize(wxOrientation direction) const;
    
    /**
        If sizing is not continuous, then return a suitable size for the control
        which is larger then the given size.
    
        @param direction
            The direction(s) in which the size should increase.
        @param relative_to
            The size for which a larger size should be found.
        @return
            @a relative_to if there is no larger size, otherwise a suitable
            size which is larger in the given direction(s), and the same as
            @a relative_to in the other direction (if any).
    
        @see IsSizingContinuous()
        @see DoGetNextLargerSize()
    */
    wxSize GetNextLargerSize(wxOrientation direction, wxSize relative_to) const;
    
    /**
        Perform initial size and layout calculations after children have been
        added, and/or realize children.
    */
    virtual bool Realize();
    
    /**
        Alias for Realize().
    */
    bool Realise();
    
protected:
    /**
        Implementation of GetNextSmallerSize().
        Controls which have non-continuous sizing must override this virtual
        function rather than GetNextSmallerSize().
    */
    virtual wxSize DoGetNextSmallerSize(wxOrientation direction,
                                        wxSize relative_to) const;

    /**
        Implementation of GetNextLargerSize().
        Controls which have non-continuous sizing must override this virtual
        function rather than GetNextLargerSize().
    */
    virtual wxSize DoGetNextLargerSize(wxOrientation direction,
                                       wxSize relative_to) const;
};
Commit	Line	Data
3c3ead1d PC	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: ribbon/control.h
	3	// Purpose: interface of wxRibbonControl
	4	// Author: Peter Cawley
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows licence
	7	///////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxRibbonControl
	11
	12	wxRibbonControl serves as a base class for all controls which share the
	13	ribbon charactertics of having a ribbon art provider, and (optionally)
	14	non-continous resizing. Despite what the name may imply, it is not the
	15	top-level control for creating a ribbon interface - that is wxRibbonBar.
	16
	17	Ribbon controls often have a region which is "transparent", and shows the
	18	contents of the ribbon page or panel behind it. If implementing a new
	19	ribbon control, then it may be useful to realise that this effect is done
	20	by the art provider when painting the background of the control, and hence
	21	in the paint handler for the new control, you should call a draw background
	22	method on the art provider (wxRibbonArtProvider::DrawButtonBarBackground()
	23	and wxRibbonArtProvider::DrawToolBarBackground() typically just redraw what
	24	is behind the rectangle being painted) if you want transparent regions.
	25
	26	@library{wxribbon}
	27	@category{ribbon}
	28	*/
	29	class wxRibbonControl : public wxControl
	30	{
	31	public:
	32	/**
	33	Constructor.
	34	*/
	35	wxRibbonControl();
	36
	37	/**
	38	Constructor.
	39
	40	If @a parent is a wxRibbonControl with a non-NULL art provider, then
	41	the art provider of new control is set to that of @a parent.
	42	*/
	43	wxRibbonControl(wxWindow *parent, wxWindowID id,
	44	const wxPoint& pos = wxDefaultPosition,
	45	const wxSize& size = wxDefaultSize, long style = 0,
	46	const wxValidator& validator = wxDefaultValidator,
	47	const wxString& name = wxControlNameStr);
	48
	49	/**
	50	Set the art provider to be used. In many cases, setting the art provider
	51	will also set the art provider on all child windows which extend
	52	wxRibbonControl.
	53
	54	In most cases, controls will not take ownership of the given pointer,
	55	with the notable exception being wxRibbonBar::SetArtProvider().
	56	*/
	57	virtual void SetArtProvider(wxRibbonArtProvider* art);
	58
	59	/**
	60	Get the art provider to be used. Note that until an art provider has
	61	been set in some way, this function may return NULL.
	62	*/
	63	wxRibbonArtProvider* GetArtProvider() const;
	64
65	/**
66	@return @true if this window can take any size (greater than its minimum
67	size), @false if it can only take certain sizes.
68
69	@see GetNextSmallerSize()
70	@see GetNextLargerSize()
71	*/
72	virtual bool IsSizingContinuous() const;
73
74	/**
75	If sizing is not continuous, then return a suitable size for the control
76	which is smaller than the current size.
77
78	@param direction
79	The direction(s) in which the size should reduce.
80	@return
81	The current size if there is no smaller size, otherwise a suitable
82	size which is smaller in the given direction(s), and the same as the
83	current size in the other direction (if any).
84
85	@see IsSizingContinuous()
86	*/
87	wxSize GetNextSmallerSize(wxOrientation direction) const;
88
89	/**
90	If sizing is not continuous, then return a suitable size for the control
91	which is smaller than the given size.
92
93	@param direction
94	The direction(s) in which the size should reduce.
95	@param relative_to
96	The size for which a smaller size should be found.
97	@return
98	@a relative_to if there is no smaller size, otherwise a suitable
99	size which is smaller in the given direction(s), and the same as
100	@a relative_to in the other direction (if any).
101
102	@see IsSizingContinuous()
103	@see DoGetNextSmallerSize()
104	*/
105	wxSize GetNextSmallerSize(wxOrientation direction, wxSize relative_to) const;
106
107	/**
108	If sizing is not continuous, then return a suitable size for the control
109	which is larger then the current size.
110
111	@param direction
112	The direction(s) in which the size should increase.
113	@return
114	The current size if there is no larger size, otherwise a suitable
115	size which is larger in the given direction(s), and the same as the
116	current size in the other direction (if any).
117
118	@see IsSizingContinuous()
119	*/
120	wxSize GetNextLargerSize(wxOrientation direction) const;
121
122	/**
123	If sizing is not continuous, then return a suitable size for the control
124	which is larger then the given size.
125
126	@param direction
127	The direction(s) in which the size should increase.
128	@param relative_to
129	The size for which a larger size should be found.
130	@return
131	@a relative_to if there is no larger size, otherwise a suitable
132	size which is larger in the given direction(s), and the same as
133	@a relative_to in the other direction (if any).
134
135	@see IsSizingContinuous()
136	@see DoGetNextLargerSize()
137	*/
138	wxSize GetNextLargerSize(wxOrientation direction, wxSize relative_to) const;
139
140	/**
141	Perform initial size and layout calculations after children have been
142	added, and/or realize children.
143	*/
144	virtual bool Realize();
145
146	/**
147	Alias for Realize().
148	*/
149	bool Realise();
150
151	protected:
152	/**
153	Implementation of GetNextSmallerSize().
154	Controls which have non-continuous sizing must override this virtual
155	function rather than GetNextSmallerSize().
156	*/
157	virtual wxSize DoGetNextSmallerSize(wxOrientation direction,
158	wxSize relative_to) const;
159
160	/**
161	Implementation of GetNextLargerSize().
162	Controls which have non-continuous sizing must override this virtual
163	function rather than GetNextLargerSize().
164	*/
165	virtual wxSize DoGetNextLargerSize(wxOrientation direction,
166	wxSize relative_to) const;
167	};