[wxWidgets.git] / interface / layout.h

/////////////////////////////////////////////////////////////////////////////
// Name:        layout.h
// Purpose:     documentation for wxIndividualLayoutConstraint class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxIndividualLayoutConstraint
    @wxheader{layout.h}

    Objects of this class are stored in the wxLayoutConstraint class
    as one of eight possible constraints that a window can be involved in.

    Constraints are initially set to have the relationship wxUnconstrained,
    which means that their values should be calculated by looking at known
    constraints.

    @library{wxcore}
    @category{winlayout}

    @seealso
    @ref overview_constraintsoverview "Overview and examples", wxLayoutConstraints,
    wxWindow::SetConstraints.
*/
class wxIndividualLayoutConstraint : public wxObject
{
public:
    /**
        Constructor. Not used by the end-user.
    */
    wxIndividualLayoutConstraint();

    /**
        Constrains this edge to be above the given window, with an
        optional margin. Implicitly, this is relative to the top edge of the other
        window.
    */
    void Above(wxWindow * otherWin, int margin = 0);

    /**
        Constrains this edge or dimension to be the given absolute value.
    */
    void Absolute(int value);

    /**
        Sets this edge or constraint to be whatever the window's value is
        at the moment. If either of the width and height constraints
        are @e as is, the window will not be resized, but moved instead.
        This is important when considering panel items which are intended
        to have a default size, such as a button, which may take its size
        from the size of the button label.
    */
#define void AsIs()     /* implementation is private */

    /**
        Constrains this edge to be below the given window, with an
        optional margin. Implicitly, this is relative to the bottom edge of the other
        window.
    */
    void Below(wxWindow * otherWin, int margin = 0);

    /**
        The @e wxEdge enumerated type specifies the type of edge or dimension of a
        window.
        
        wxLeft
        
        
        The left edge.
        
        wxTop
        
        
        The top edge.
        
        wxRight
        
        
        The right edge.
        
        wxBottom
        
        
        The bottom edge.
        
        wxCentreX
        
        
        The x-coordinate of the centre of the window.
        
        wxCentreY
        
        
        The y-coordinate of the centre of the window.
        
        The @e wxRelationship enumerated type specifies the relationship that
        this edge or dimension has with another specified edge or dimension. Normally,
        the user
        doesn't use these directly because functions such as @e Below and @e RightOf
        are a convenience
        for using the more general @e Set function.
        
        wxUnconstrained
        
        
        The edge or dimension is unconstrained (the default for edges.
        
        wxAsIs
        
        
        The edge or dimension is to be taken from the current window position or size
        (the
        default for dimensions.
        
        wxAbove
        
        
        The edge should be above another edge.
        
        wxBelow
        
        
        The edge should be below another edge.
        
        wxLeftOf
        
        
        The edge should be to the left of another edge.
        
        wxRightOf
        
        
        The edge should be to the right of another edge.
        
        wxSameAs
        
        
        The edge or dimension should be the same as another edge or dimension.
        
        wxPercentOf
        
        
        The edge or dimension should be a percentage of another edge or dimension.
        
        wxAbsolute
        
        
        The edge or dimension should be a given absolute value.
    */


    /**
        Constrains this edge to be to the left of the given window, with an
        optional margin. Implicitly, this is relative to the left edge of the other
        window.
    */
    void LeftOf(wxWindow * otherWin, int margin = 0);

    /**
        Constrains this edge or dimension to be to a percentage of the given window,
        with an
        optional margin.
    */
    void PercentOf(wxWindow * otherWin, wxEdge edge, int per);

    /**
        Constrains this edge to be to the right of the given window, with an
        optional margin. Implicitly, this is relative to the right edge of the other
        window.
    */
    void RightOf(wxWindow * otherWin, int margin = 0);

    /**
        Constrains this edge or dimension to be to the same as the edge of the given
        window, with an
        optional margin.
    */
    void SameAs(wxWindow * otherWin, wxEdge edge, int margin = 0);

    /**
        Sets the properties of the constraint. Normally called by one of the convenience
        functions such as Above, RightOf, SameAs.
    */
#define void Set(wxRelationship rel, wxWindow * otherWin,
    wxEdge otherEdge, int value = 0,
                                  int margin = 0)     /* implementation is private */

    /**
        Sets this edge or dimension to be unconstrained, that is, dependent on
        other edges and dimensions from which this value can be deduced.
    */
    void Unconstrained();
};


/**
    @class wxLayoutConstraints
    @wxheader{layout.h}

    @b Note: constraints are now deprecated and you should use sizers instead.

    Objects of this class can be associated with a window to define its
    layout constraints, with respect to siblings or its parent.

    The class consists of the following eight constraints of class
    wxIndividualLayoutConstraint,
    some or all of which should be accessed directly to set the appropriate
    constraints.

     @b left: represents the left hand edge of the window
     @b right: represents the right hand edge of the window
     @b top: represents the top edge of the window
     @b bottom: represents the bottom edge of the window
     @b width: represents the width of the window
     @b height: represents the height of the window
     @b centreX: represents the horizontal centre point of the window
     @b centreY: represents the vertical centre point of the window

    Most constraints are initially set to have the relationship wxUnconstrained,
    which means that their values should be calculated by looking at known
    constraints.
    The exceptions are @e width and @e height, which are set to wxAsIs to
    ensure that if the user does not specify a constraint, the existing
    width and height will be used, to be compatible with panel items which often
    have take a default size. If the constraint is wxAsIs, the dimension will
    not be changed.

    @b wxPerl note: In wxPerl the constraints are accessed as

    @code
    constraint = Wx::LayoutConstraints-new();
      constraint-centreX-AsIs();
      constraint-centreY-Unconstrained();
    @endcode


    @library{wxcore}
    @category{winlayout}

    @seealso
    @ref overview_constraintsoverview "Overview and examples",
    wxIndividualLayoutConstraint, wxWindow::SetConstraints
*/
class wxLayoutConstraints : public wxObject
{
public:
    /**
        Constructor.
    */
    wxLayoutConstraints();

    /**
        wxIndividualLayoutConstraint bottom
        
        Constraint for the bottom edge.
    */


    /**
        wxIndividualLayoutConstraint centreX
        
        Constraint for the horizontal centre point.
    */


    /**
        wxIndividualLayoutConstraint centreY
        
        Constraint for the vertical centre point.
    */


    /**
        wxIndividualLayoutConstraint height
        
        Constraint for the height.
    */


    /**
        wxIndividualLayoutConstraint left
        
        Constraint for the left-hand edge.
    */


    /**
        wxIndividualLayoutConstraint right
        
        Constraint for the right-hand edge.
    */


    /**
        wxIndividualLayoutConstraint top
        
        Constraint for the top edge.
    */


    /**
        wxIndividualLayoutConstraint width
        
        Constraint for the width.
    */
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: layout.h
	3	// Purpose: documentation for wxIndividualLayoutConstraint class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxIndividualLayoutConstraint
	11	@wxheader{layout.h}
7c913512	12
23324ae1 FM	13	Objects of this class are stored in the wxLayoutConstraint class
23324ae1 FM	14	as one of eight possible constraints that a window can be involved in.
7c913512	15
23324ae1 FM	16	Constraints are initially set to have the relationship wxUnconstrained,
	17	which means that their values should be calculated by looking at known
	18	constraints.
7c913512	19
23324ae1 FM	20	@library{wxcore}
23324ae1 FM	21	@category{winlayout}
7c913512	22
23324ae1 FM	23	@seealso
	24	@ref overview_constraintsoverview "Overview and examples", wxLayoutConstraints,
	25	wxWindow::SetConstraints.
	26	*/
	27	class wxIndividualLayoutConstraint : public wxObject
	28	{
	29	public:
	30	/**
	31	Constructor. Not used by the end-user.
	32	*/
	33	wxIndividualLayoutConstraint();
	34
	35	/**
	36	Constrains this edge to be above the given window, with an
	37	optional margin. Implicitly, this is relative to the top edge of the other
	38	window.
	39	*/
	40	void Above(wxWindow * otherWin, int margin = 0);
	41
	42	/**
	43	Constrains this edge or dimension to be the given absolute value.
	44	*/
	45	void Absolute(int value);
	46
	47	/**
	48	Sets this edge or constraint to be whatever the window's value is
	49	at the moment. If either of the width and height constraints
	50	are @e as is, the window will not be resized, but moved instead.
	51	This is important when considering panel items which are intended
	52	to have a default size, such as a button, which may take its size
	53	from the size of the button label.
	54	*/
	55	#define void AsIs() /* implementation is private */
	56
	57	/**
	58	Constrains this edge to be below the given window, with an
	59	optional margin. Implicitly, this is relative to the bottom edge of the other
	60	window.
	61	*/
	62	void Below(wxWindow * otherWin, int margin = 0);
	63
	64	/**
	65	The @e wxEdge enumerated type specifies the type of edge or dimension of a
	66	window.
	67
	68	wxLeft
	69
	70
	71	The left edge.
	72
	73	wxTop
	74
	75
	76	The top edge.
	77
	78	wxRight
	79
	80
	81	The right edge.
	82
	83	wxBottom
	84
	85
	86	The bottom edge.
87
88	wxCentreX
89
90
91	The x-coordinate of the centre of the window.
92
93	wxCentreY
94
95
96	The y-coordinate of the centre of the window.
97
98	The @e wxRelationship enumerated type specifies the relationship that
99	this edge or dimension has with another specified edge or dimension. Normally,
100	the user
101	doesn't use these directly because functions such as @e Below and @e RightOf
102	are a convenience
103	for using the more general @e Set function.
104
105	wxUnconstrained
106
107
108	The edge or dimension is unconstrained (the default for edges.
109
110	wxAsIs
111
112
113	The edge or dimension is to be taken from the current window position or size
114	(the
115	default for dimensions.
116
117	wxAbove
118
119
120	The edge should be above another edge.
121
122	wxBelow
123
124
125	The edge should be below another edge.
126
127	wxLeftOf
128
129
130	The edge should be to the left of another edge.
131
132	wxRightOf
133
134
135	The edge should be to the right of another edge.
136
137	wxSameAs
138
139
140	The edge or dimension should be the same as another edge or dimension.
141
142	wxPercentOf
143
144
145	The edge or dimension should be a percentage of another edge or dimension.
146
147	wxAbsolute
148
149
150	The edge or dimension should be a given absolute value.
151	*/
152
153
154	/**
155	Constrains this edge to be to the left of the given window, with an
156	optional margin. Implicitly, this is relative to the left edge of the other
157	window.
158	*/
159	void LeftOf(wxWindow * otherWin, int margin = 0);
160
161	/**
162	Constrains this edge or dimension to be to a percentage of the given window,
163	with an
164	optional margin.
165	*/
166	void PercentOf(wxWindow * otherWin, wxEdge edge, int per);
167
168	/**
169	Constrains this edge to be to the right of the given window, with an
170	optional margin. Implicitly, this is relative to the right edge of the other
171	window.
172	*/
173	void RightOf(wxWindow * otherWin, int margin = 0);
174
175	/**
176	Constrains this edge or dimension to be to the same as the edge of the given
177	window, with an
178	optional margin.
179	*/
180	void SameAs(wxWindow * otherWin, wxEdge edge, int margin = 0);
181
182	/**
183	Sets the properties of the constraint. Normally called by one of the convenience
184	functions such as Above, RightOf, SameAs.
185	*/
186	#define void Set(wxRelationship rel, wxWindow * otherWin,
7c913512 FM	187	wxEdge otherEdge, int value = 0,
7c913512 FM	188	int margin = 0) /* implementation is private */
23324ae1 FM	189
	190	/**
	191	Sets this edge or dimension to be unconstrained, that is, dependent on
	192	other edges and dimensions from which this value can be deduced.
	193	*/
	194	void Unconstrained();
	195	};
	196
	197
	198	/**
	199	@class wxLayoutConstraints
	200	@wxheader{layout.h}
7c913512	201
23324ae1	202	@b Note: constraints are now deprecated and you should use sizers instead.
7c913512	203
23324ae1 FM	204	Objects of this class can be associated with a window to define its
23324ae1 FM	205	layout constraints, with respect to siblings or its parent.
7c913512	206
23324ae1 FM	207	The class consists of the following eight constraints of class
	208	wxIndividualLayoutConstraint,
	209	some or all of which should be accessed directly to set the appropriate
	210	constraints.
7c913512	211
23324ae1 FM	212	@b left: represents the left hand edge of the window
	213	@b right: represents the right hand edge of the window
	214	@b top: represents the top edge of the window
	215	@b bottom: represents the bottom edge of the window
	216	@b width: represents the width of the window
	217	@b height: represents the height of the window
	218	@b centreX: represents the horizontal centre point of the window
	219	@b centreY: represents the vertical centre point of the window
7c913512	220
23324ae1 FM	221	Most constraints are initially set to have the relationship wxUnconstrained,
	222	which means that their values should be calculated by looking at known
	223	constraints.
	224	The exceptions are @e width and @e height, which are set to wxAsIs to
	225	ensure that if the user does not specify a constraint, the existing
	226	width and height will be used, to be compatible with panel items which often
	227	have take a default size. If the constraint is wxAsIs, the dimension will
	228	not be changed.
7c913512	229
23324ae1	230	@b wxPerl note: In wxPerl the constraints are accessed as
7c913512	231
23324ae1 FM	232	@code
	233	constraint = Wx::LayoutConstraints-new();
	234	constraint-centreX-AsIs();
	235	constraint-centreY-Unconstrained();
	236	@endcode
7c913512 FM	237
7c913512 FM	238
23324ae1 FM	239	@library{wxcore}
23324ae1 FM	240	@category{winlayout}
7c913512	241
23324ae1 FM	242	@seealso
	243	@ref overview_constraintsoverview "Overview and examples",
	244	wxIndividualLayoutConstraint, wxWindow::SetConstraints
	245	*/
	246	class wxLayoutConstraints : public wxObject
	247	{
	248	public:
	249	/**
	250	Constructor.
	251	*/
	252	wxLayoutConstraints();
	253
	254	/**
	255	wxIndividualLayoutConstraint bottom
	256
	257	Constraint for the bottom edge.
	258	*/
	259
	260
	261	/**
	262	wxIndividualLayoutConstraint centreX
	263
	264	Constraint for the horizontal centre point.
	265	*/
	266
	267
	268	/**
	269	wxIndividualLayoutConstraint centreY
	270
	271	Constraint for the vertical centre point.
	272	*/
	273
	274
	275	/**
	276	wxIndividualLayoutConstraint height
	277
	278	Constraint for the height.
	279	*/
	280
	281
	282	/**
	283	wxIndividualLayoutConstraint left
	284
	285	Constraint for the left-hand edge.
	286	*/
	287
	288
	289	/**
	290	wxIndividualLayoutConstraint right
	291
	292	Constraint for the right-hand edge.
	293	*/
	294
	295
	296	/**
	297	wxIndividualLayoutConstraint top
	298
	299	Constraint for the top edge.
	300	*/
	301
	302
	303	/**
	304	wxIndividualLayoutConstraint width
	305
306	Constraint for the width.
307	*/
308	};