From: Bryan Petty Date: Sun, 16 Mar 2008 00:02:39 +0000 (+0000) Subject: Removed layout constaints related docs as discussed on wx-dev. X-Git-Url: https://git.saurik.com/wxWidgets.git/commitdiff_plain/8f5b44d805a9eda79c1981f92eda8e7b12253e23?ds=sidebyside Removed layout constaints related docs as discussed on wx-dev. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@52555 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- diff --git a/docs/doxygen/groups/class_winlayout.h b/docs/doxygen/groups/class_winlayout.h index 676e88f5a4..3a5c2b8481 100644 --- a/docs/doxygen/groups/class_winlayout.h +++ b/docs/doxygen/groups/class_winlayout.h @@ -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 */ diff --git a/docs/doxygen/mainpages/topics.h b/docs/doxygen/mainpages/topics.h index 76892be8a2..1353da828c 100644 --- a/docs/doxygen/mainpages/topics.h +++ b/docs/doxygen/mainpages/topics.h @@ -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 diff --git a/docs/doxygen/overviews/constraints.h b/docs/doxygen/overviews/constraints.h deleted file mode 100644 index 2fb51946ea..0000000000 --- a/docs/doxygen/overviews/constraints.h +++ /dev/null @@ -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 - - -
- - - @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 - -*/ - diff --git a/interface/layout.h b/interface/layout.h deleted file mode 100644 index cdfc160005..0000000000 --- a/interface/layout.h +++ /dev/null @@ -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. - */ -}; -