AuroraMiddleware/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Removed layout constaints related docs as discussed on wx-dev.

Browse Source 
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52555 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Bryan Petty 2008-03-16 00:02:39 +00:00
parent 684fc22bcc
commit 8f5b44d805
4 changed files with 5 additions and 487 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
docs/doxygen/groups/class_winlayout.h
View File

@ -11,13 +11,12 @@
@defgroup group_class_winlayout Window Layout
@ingroup group_class
There are two different systems for laying out windows (and dialogs in
particular). One is based upon so-called sizers and it requires less typing,
thinking and calculating and will in almost all cases produce dialogs looking
equally well on all platforms, the other is based on so-called constraints and
is deprecated, though still available.
wxWidgets makes window layout and sizing easy and painless using a set of
classes known as "sizers". Sizers allow for flexible window positioning and
sizes that can help with automatically handling localization differences, as
well as making it easy to write user resizable windows.
Related Overviews: @ref overview_sizer, @ref overview_constraints
Related Overviews: @ref overview_sizer
*/

1
docs/doxygen/mainpages/topics.h
View File

@ -84,7 +84,6 @@ The following is a basic categorization of them:
@li @subpage overview_validator
@li @subpage overview_dataobject
@li @subpage overview_dnd
@li @subpage overview_constraints
@section page_topics_indivctrl Individual Controls

195
docs/doxygen/overviews/constraints.h
View File

@ -1,195 +0,0 @@
/////////////////////////////////////////////////////////////////////////////
// Name: constraints.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/////////////////////////////////////////////////////////////////////////////
/**
@page overview_constraints Window Layout Constraints
Classes: wxLayoutConstraints, wxIndividualLayoutConstraint.
@note Constraints are now deprecated and you should use sizers instead (see wxSizer).
Objects of class wxLayoutConstraint can be associated with a window to define
the way it is laid out, with respect to its siblings or the 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
The constraints are initially set to have the relationship wxUnconstrained,
which means that their values should be calculated by looking at known constraints.
To calculate the position and size of the control, the layout algorithm needs to
know exactly 4 constraints (as it has 4 numbers to calculate from them), so you
should always set exactly 4 of the constraints from the above table.
If you want the controls height or width to have the default value, you may use
a special value for the constraint: wxAsIs. If the constraint is wxAsIs, the
dimension will not be changed which is useful for the dialog controls which
often have the default size (e.g. the buttons whose size is determined by their
label).
The constrains calculation is done in wxWindow::Layout function which evaluates
constraints. To call it you can either call wxWindow::SetAutoLayout if the parent
window is a frame, panel or a dialog to tell default OnSize handlers to call Layout
automatically whenever the window size changes, or override OnSize and call
Layout yourself (note that you do have to call wxWindow::Layout yourself if the parent
window is not a frame, panel or dialog).
@li @ref overview_constraints_layout
@li @ref overview_constraints_examples
<hr>
@section overview_constraints_layout Constraint layout: more details
By default, windows do not have a wxLayoutConstraints object. In this case, much layout
must be done explicitly, by performing calculations in OnSize members, except
for the case of frames that have exactly one subwindow (not counting toolbar and
statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
takes care of resizing the child to always fill the frame.
To avoid the need for these rather awkward calculations, the user can create
a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
This object contains a constraint for each of the window edges, two for the centre point,
and two for the window size. By setting some or all of these constraints appropriately,
the user can achieve quite complex layout by defining relationships between windows.
In wxWidgets, each window can be constrained relative to either its @e siblings
on the same window, or the @e parent. The layout algorithm
therefore operates in a top-down manner, finding the correct layout for
the children of a window, then the layout for the grandchildren, and so on.
Note that this differs markedly from native Motif layout, where
constraints can ripple upwards and can eventually change the frame
window or dialog box size. We assume in wxWidgets that the @e user is
always 'boss' and specifies the size of the outer window, to which
subwindows must conform. Obviously, this might be a limitation in some
circumstances, but it suffices for most situations, and the
simplification avoids some of the nightmarish problems associated with
programming Motif.
When the user sets constraints, many of the constraints for windows
edges and dimensions remain unconstrained. For a given window,
the wxWindow::Layout algorithm first resets all constraints
in all children to have unknown edge or dimension values, and then iterates
through the constraints, evaluating them. For unconstrained edges and dimensions,
it tries to find the value using known relationships that always hold. For example,
an unconstrained @e width may be calculated from the @e left and @e right edges, if
both are currently known. For edges and dimensions with user-supplied constraints, these
constraints are evaluated if the inputs of the constraint are known.
The algorithm stops when all child edges and dimension are known (success), or
there are unknown edges or dimensions but there has been no change in this cycle (failure).
It then sets all the window positions and sizes according to the values it has found.
Because the algorithm is iterative, the order in which constraints are considered is
irrelevant, however you may reduce the number of iterations (and thus speed up
the layout calculations) by creating the controls in such order that as many
constraints as possible can be calculated during the first iteration. For example, if
you have 2 buttons which you'd like to position in the lower right corner, it is
slightly more efficient to first create the second button and specify that its
right border IsSameAs(parent, wxRight) and then create the first one by
specifying that it should be LeftOf() the second one than to do in a more
natural left-to-right order.
@section overview_constraints_examples Window layout examples
@subsection overview_constraints_example1 Example 1: subwindow layout
This example specifies a panel and a window side by side,
with a text subwindow below it.
@code
frame->panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0);
frame->scrollWindow = new MyScrolledWindow(frame, -1, wxPoint(0, 0), wxSize(400, 400), wxRETAINED);
frame->text_window = new MyTextWindow(frame, -1, wxPoint(0, 250), wxSize(400, 250));
// Set constraints for panel subwindow
wxLayoutConstraints *c1 = new wxLayoutConstraints;
c1->left.SameAs (frame, wxLeft);
c1->top.SameAs (frame, wxTop);
c1->right.PercentOf (frame, wxWidth, 50);
c1->height.PercentOf (frame, wxHeight, 50);
frame->panel->SetConstraints(c1);
// Set constraints for scrollWindow subwindow
wxLayoutConstraints *c2 = new wxLayoutConstraints;
c2->left.SameAs (frame->panel, wxRight);
c2->top.SameAs (frame, wxTop);
c2->right.SameAs (frame, wxRight);
c2->height.PercentOf (frame, wxHeight, 50);
frame->scrollWindow->SetConstraints(c2);
// Set constraints for text subwindow
wxLayoutConstraints *c3 = new wxLayoutConstraints;
c3->left.SameAs (frame, wxLeft);
c3->top.Below (frame->panel);
c3->right.SameAs (frame, wxRight);
c3->bottom.SameAs (frame, wxBottom);
frame->text_window->SetConstraints(c3);
@endcode
@subsection overview_constraints_example2 Example 2: panel item layout
This example sizes a button width to 80 percent of the panel width, and centres
it horizontally. A listbox and multitext item are placed below it. The listbox
takes up 40 percent of the panel width, and the multitext item takes up
the remainder of the width. Margins of 5 pixels are used.
@code
// Create some panel items
wxButton *btn1 = new wxButton(frame->panel, ->1, "A button") ;
wxLayoutConstraints *b1 = new wxLayoutConstraints;
b1->centreX.SameAs (frame->panel, wxCentreX);
b1->top.SameAs (frame->panel, wxTop, 5);
b1->width.PercentOf (frame->panel, wxWidth, 80);
b1->height.PercentOf (frame->panel, wxHeight, 10);
btn1->SetConstraints(b1);
wxListBox *list = new wxListBox(frame->panel, ->1, "A list",
wxPoint(->1, ->1), wxSize(200, 100));
wxLayoutConstraints *b2 = new wxLayoutConstraints;
b2->top.Below (btn1, 5);
b2->left.SameAs (frame->panel, wxLeft, 5);
b2->width.PercentOf (frame->panel, wxWidth, 40);
b2->bottom.SameAs (frame->panel, wxBottom, 5);
list->SetConstraints(b2);
wxTextCtrl *mtext = new wxTextCtrl(frame->panel, ->1, "Multiline text", "Some text",
wxPoint(->1, ->1), wxSize(150, 100), wxTE_MULTILINE);
wxLayoutConstraints *b3 = new wxLayoutConstraints;
b3->top.Below (btn1, 5);
b3->left.RightOf (list, 5);
b3->right.SameAs (frame->panel, wxRight, 5);
b3->bottom.SameAs (frame->panel, wxBottom, 5);
mtext->SetConstraints(b3);
@endcode
*/

285
interface/layout.h
View File

@ -1,285 +0,0 @@
/////////////////////////////////////////////////////////////////////////////
// Name: layout.h
// Purpose: interface of wxIndividualLayoutConstraint
// 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}
@see @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.
*/
void AsIs();
/**
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.
*/
void Set(wxRelationship rel, wxWindow* otherWin,
wxEdge otherEdge, int value = 0,
int margin = 0);
/**
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}
@see @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.
*/
};