whilst -> while

[wxWidgets.git] / docs / latex / wx / tconstr.tex

diff --git a/docs/latex/wx/tconstr.tex b/docs/latex/wx/tconstr.tex
index 3c659234dbc039fcd5f133d32a27d4b91f16d567..32ea2bf62e9a149401a7ec075ff884c4cbcf0cc3 100644 (file)
--- a/docs/latex/wx/tconstr.tex
+++ b/docs/latex/wx/tconstr.tex
@@ -2,8 +2,10 @@
 
 Classes: \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}.
 
 
 Classes: \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}.
 

-Objects of class wxLayoutConstraint can be associated with a window to define the
-way its subwindows are laid out, with respect to their siblings or parent.
+{\bf Note:} constraints are now deprecated and you should use \helpref{sizers}{sizeroverview} instead.
+
+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
 
 The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
 some or all of which should be accessed directly to set the appropriate


@@ -20,24 +22,34 @@ constraints.
 \item {\bf centreY:} represents the vertical centre point of the window
 \end{itemize}
 
 \item {\bf centreY:} represents the vertical centre point of the window
 \end{itemize}
 

-Most constraints are initially set to have the relationship wxUnconstrained,
+The constraints are initially set to have the relationship wxUnconstrained,

 which means that their values should be calculated by looking at known constraints.
 which means that their values should be calculated by looking at known constraints.

-The exceptions are {\it width} and {\it 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.
-
-To call the \helpref{wxWindow::Layout}{wxwindowlayout} function which evaluates
-constraints, you can either call wxWindow::SetAutoLayout to tell
-default OnSize handlers to call Layout, or override OnSize and call Layout yourself.
-
-\subsection{Constraint layout: more detail}
+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 \helpref{wxWindow::Layout}{wxwindowlayout} 
+function which evaluates constraints. To call it you can either call
+\helpref{wxWindow::SetAutoLayout}{wxwindowsetautolayout} 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 
+\helpref{Layout}{wxwindowlayout} yourself if the parent window is not a
+frame, panel or dialog).
+
+\subsection{Constraint layout: more details}\label{constraintlayoutdetails}

 
 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
 
 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 one subwindow, where wxFrame::OnSize takes care
-of resizing the child.
+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.
 
 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.


@@ -45,13 +57,13 @@ This object contains a constraint for each of the window edges, two for the cent
 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.
 
 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 wxWindows, each window can be constrained relative to either its {\it
+In wxWidgets, each window can be constrained relative to either its {\it

 siblings} on the same window, or the {\it 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
 siblings} on the same window, or the {\it 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 wxWindows that the {\it user} is
+window or dialog box size. We assume in wxWidgets that the {\it 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
 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


@@ -62,31 +74,38 @@ 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,
 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,

-evaulating them. For unconstrained edges and dimensions, it
+evaluating them. For unconstrained edges and dimensions, it

 tries to find the value using known relationships that always hold. For example,
 an unconstrained {\it width} may be calculated from the {\it left} and {\it right edges}, if
 both are currently known. For edges and dimensions with user-supplied constraints, these
 tries to find the value using known relationships that always hold. For example,
 an unconstrained {\it width} may be calculated from the {\it left} and {\it right edges}, if
 both are currently known. For edges and dimensions with user-supplied constraints, these

-constraints are evaulated if the inputs of the constraint are known.
+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
+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
 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.
+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.

 
 \subsection{Window layout examples}\label{layoutexamples}
 
 
 \subsection{Window layout examples}\label{layoutexamples}
 

-\subsubsection{Example 1: subwindow layout}
+\subsubsection{Example 1: subwindow layout}\label{subwindowlayoutexample}

 
 

-This example specifies a panel and a canvas side by side,
-with a text subwindow below it. 
+This example specifies a panel and a window side by side,
+with a text subwindow below it.

 
 \begin{verbatim}
 
 \begin{verbatim}

-  frame->panel = new wxPanel(frame, 0, 0, 1000, 500, 0);
-  frame->canvas = new MyCanvas(frame, 0, 0, 400, 400, wxRETAINED);
-  frame->text_window = new MyTextWindow(frame, 0, 250, 400, 250, wxNATIVE_IMPL);
+  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;
 
   // Set constraints for panel subwindow
   wxLayoutConstraints *c1 = new wxLayoutConstraints;


@@ -98,7 +117,7 @@ with a text subwindow below it.
 
   frame->panel->SetConstraints(c1);
 
 
   frame->panel->SetConstraints(c1);
 

-  // Set constraints for canvas subwindow
+  // Set constraints for scrollWindow subwindow

   wxLayoutConstraints *c2 = new wxLayoutConstraints;
 
   c2->left.SameAs       (frame->panel, wxRight);
   wxLayoutConstraints *c2 = new wxLayoutConstraints;
 
   c2->left.SameAs       (frame->panel, wxRight);


@@ -106,7 +125,7 @@ with a text subwindow below it.
   c2->right.SameAs      (frame, wxRight);
   c2->height.PercentOf  (frame, wxHeight, 50);
 
   c2->right.SameAs      (frame, wxRight);
   c2->height.PercentOf  (frame, wxHeight, 50);
 

-  frame->canvas->SetConstraints(c2);
+  frame->scrollWindow->SetConstraints(c2);

 
   // Set constraints for text subwindow
   wxLayoutConstraints *c3 = new wxLayoutConstraints;
 
   // Set constraints for text subwindow
   wxLayoutConstraints *c3 = new wxLayoutConstraints;


@@ -118,7 +137,7 @@ with a text subwindow below it.
   frame->text_window->SetConstraints(c3);
 \end{verbatim}
 
   frame->text_window->SetConstraints(c3);
 \end{verbatim}
 

-\subsubsection{Example 2: panel item layout}
+\subsubsection{Example 2: panel item layout}\label{panelitemlayoutexample}

 
 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
 
 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


@@ -127,7 +146,7 @@ the remainder of the width. Margins of 5 pixels are used.
 
 \begin{verbatim}
   // Create some panel items
 
 \begin{verbatim}
   // Create some panel items

-  wxButton *btn1 = new wxButton(frame->panel, (wxFunction)NULL, "A button") ;
+  wxButton *btn1 = new wxButton(frame->panel, -1, "A button") ;

 
   wxLayoutConstraints *b1 = new wxLayoutConstraints;
   b1->centreX.SameAs    (frame->panel, wxCentreX);
 
   wxLayoutConstraints *b1 = new wxLayoutConstraints;
   b1->centreX.SameAs    (frame->panel, wxCentreX);


@@ -136,8 +155,8 @@ the remainder of the width. Margins of 5 pixels are used.
   b1->height.PercentOf  (frame->panel, wxHeight, 10);
   btn1->SetConstraints(b1);
 
   b1->height.PercentOf  (frame->panel, wxHeight, 10);
   btn1->SetConstraints(b1);
 

-  wxListBox *list = new wxListBox(frame->panel, (wxFunction)NULL, "A list",
-                                  wxSINGLE, -1, -1, 200, 100);
+  wxListBox *list = new wxListBox(frame->panel, -1, "A list",
+                                  wxPoint(-1, -1), wxSize(200, 100));

 
   wxLayoutConstraints *b2 = new wxLayoutConstraints;
   b2->top.Below         (btn1, 5);
 
   wxLayoutConstraints *b2 = new wxLayoutConstraints;
   b2->top.Below         (btn1, 5);


@@ -146,9 +165,9 @@ the remainder of the width. Margins of 5 pixels are used.
   b2->bottom.SameAs     (frame->panel, wxBottom, 5);
   list->SetConstraints(b2);
 
   b2->bottom.SameAs     (frame->panel, wxBottom, 5);
   list->SetConstraints(b2);
 

-  wxMultiText *mtext = new wxMultiText(frame->panel, (wxFunction)NULL, "Multiline text", "Some text",
-                        -1, -1, 150, 100);
-  
+  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);
   wxLayoutConstraints *b3 = new wxLayoutConstraints;
   b3->top.Below         (btn1, 5);
   b3->left.RightOf      (list, 5);