+++ /dev/null
-/////////////////////////////////////////////////////////////////////////////
-// 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
-
-*/
-
+++ /dev/null
-/////////////////////////////////////////////////////////////////////////////
-// 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.
- */
-};
-
projects / wxWidgets.git / commitdiff
