docs/latex/wx/tconstr.tex

   1 \section{Constraints overview}\label{constraintsoverview}
   2
   3 Classes: \helpref{wxLayoutConstraints}{wxlayoutconstraints}, \helpref{wxIndividualLayoutConstraint}{wxindividuallayoutconstraint}.
   4
   5 Objects of class wxLayoutConstraint can be associated with a window to define the
   6 way its subwindows are laid out, with respect to their siblings or parent.
   7
   8 The class consists of the following eight constraints of class wxIndividualLayoutConstraint,
   9 some or all of which should be accessed directly to set the appropriate
  10 constraints.
  11
  12 \begin{itemize}\itemsep=0pt
  13 \item {\bf left:} represents the left hand edge of the window
  14 \item {\bf right:} represents the right hand edge of the window
  15 \item {\bf top:} represents the top edge of the window
  16 \item {\bf bottom:} represents the bottom edge of the window
  17 \item {\bf width:} represents the width of the window
  18 \item {\bf height:} represents the height of the window
  19 \item {\bf centreX:} represents the horizontal centre point of the window
  20 \item {\bf centreY:} represents the vertical centre point of the window
  21 \end{itemize}
  22
  23 The constraints are initially set to have the relationship wxUnconstrained,
  24 which means that their values should be calculated by looking at known constraints.
  25 To calculate the position and size of the control, the layout algorithm needs to
  26 know exactly 4 constraints (as it has 4 numbers to calculate from them), so you
  27 should always set exactly 4 of the constraints from the above table.
  28
  29 If you want the controls height or width to have the default value, you may use
  30 a special value for the constraint: wxAsIs. If the constraint is wxAsIs, the
  31 dimension will not be changed which is useful for the dialog controls which
  32 often have the default size (e.g. the buttons whose size is determined by their
  33 label).
  34
  35 The constrains calculation is done in \helpref{wxWindow::Layout}{wxwindowlayout}
  36 function which evaluates constraints. To call it you can either call
  37 wxWindow::SetAutoLayout to tell default OnSize handlers to call Layout
  38 automatically whenever the window size changes, or override OnSize and call Layout
  39 yourself.
  40
  41 \subsection{Constraint layout: more detail}
  42
  43 By default, windows do not have a wxLayoutConstraints object. In this case, much layout
  44 must be done explicitly, by performing calculations in OnSize members, except
  45 for the case of frames that have exactly one subwindow (not counting toolbar and
  46 statusbar which are also positioned by the frame automatically), where wxFrame::OnSize
  47 takes care of resizing the child to always fill the frame.
  48
  49 To avoid the need for these rather awkward calculations, the user can create
  50 a wxLayoutConstraints object and associate it with a window with wxWindow::SetConstraints.
  51 This object contains a constraint for each of the window edges, two for the centre point,
  52 and two for the window size. By setting some or all of these constraints appropriately,
  53 the user can achieve quite complex layout by defining relationships between windows.
  54
  55 In wxWindows, each window can be constrained relative to either its {\it
  56 siblings} on the same window, or the {\it parent}. The layout algorithm
  57 therefore operates in a top-down manner, finding the correct layout for
  58 the children of a window, then the layout for the grandchildren, and so
  59 on. Note that this differs markedly from native Motif layout, where
  60 constraints can ripple upwards and can eventually change the frame
  61 window or dialog box size. We assume in wxWindows that the {\it user} is
  62 always `boss' and specifies the size of the outer window, to which
  63 subwindows must conform. Obviously, this might be a limitation in some
  64 circumstances, but it suffices for most situations, and the
  65 simplification avoids some of the nightmarish problems associated with
  66 programming Motif.
  67
  68 When the user sets constraints, many of the constraints for windows
  69 edges and dimensions remain unconstrained. For a given window,
  70 the wxWindow::Layout algorithm first resets all constraints
  71 in all children to have unknown edge or dimension values, and then iterates through the constraints,
  72 evaulating them. For unconstrained edges and dimensions, it
  73 tries to find the value using known relationships that always hold. For example,
  74 an unconstrained {\it width} may be calculated from the {\it left} and {\it right edges}, if
  75 both are currently known. For edges and dimensions with user-supplied constraints, these
  76 constraints are evaulated if the inputs of the constraint are known.
  77
  78 The algorithm stops when all child edges and dimension are known (success), or there
  79 there are unknown edges or dimensions but there has been no change in this cycle (failure).
  80
  81 It then sets all the window positions and sizes according to the values it has found.
  82
  83 Because the algorithm is iterative, the order in which constraints are considered is
  84 irrelevant, however you may reduce the number of iterations (and thus speed up
  85 the layout calculations) by creating the controls in such order that as many
  86 constraints as possible can be calculated during the first iteration. For example, if
  87 you have 2 buttons which you'd like to position in the lower right corner, it is
  88 slighty more efficient to first create the second button and specify that its
  89 right border IsSameAs(parent, wxRight) and then create the first one by
  90 specifying that it should be LeftOf() the second one than to do in a more
  91 natural left-to-right order.
  92
  93 \subsection{Window layout examples}\label{layoutexamples}
  94
  95 \subsubsection{Example 1: subwindow layout}
  96
  97 This example specifies a panel and a window side by side,
  98 with a text subwindow below it.
  99
 100 \begin{verbatim}
 101   frame->panel = new wxPanel(frame, -1, wxPoint(0, 0), wxSize(1000, 500), 0);
 102   frame->scrollWindow = new MyScrolledWindow(frame, -1, wxPoint(0, 0), wxSize(400, 400), wxRETAINED);
 103   frame->text_window = new MyTextWindow(frame, -1, wxPoint(0, 250), wxSize(400, 250));
 104
 105   // Set constraints for panel subwindow
 106   wxLayoutConstraints *c1 = new wxLayoutConstraints;
 107
 108   c1->left.SameAs       (frame, wxLeft);
 109   c1->top.SameAs        (frame, wxTop);
 110   c1->right.PercentOf   (frame, wxWidth, 50);
 111   c1->height.PercentOf  (frame, wxHeight, 50);
 112
 113   frame->panel->SetConstraints(c1);
 114
 115   // Set constraints for scrollWindow subwindow
 116   wxLayoutConstraints *c2 = new wxLayoutConstraints;
 117
 118   c2->left.SameAs       (frame->panel, wxRight);
 119   c2->top.SameAs        (frame, wxTop);
 120   c2->right.SameAs      (frame, wxRight);
 121   c2->height.PercentOf  (frame, wxHeight, 50);
 122
 123   frame->scrollWindow->SetConstraints(c2);
 124
 125   // Set constraints for text subwindow
 126   wxLayoutConstraints *c3 = new wxLayoutConstraints;
 127   c3->left.SameAs       (frame, wxLeft);
 128   c3->top.Below         (frame->panel);
 129   c3->right.SameAs      (frame, wxRight);
 130   c3->bottom.SameAs     (frame, wxBottom);
 131
 132   frame->text_window->SetConstraints(c3);
 133 \end{verbatim}
 134
 135 \subsubsection{Example 2: panel item layout}
 136
 137 This example sizes a button width to 80 percent of the panel width, and centres
 138 it horizontally. A listbox and multitext item are placed below it. The listbox
 139 takes up 40 percent of the panel width, and the multitext item takes up
 140 the remainder of the width. Margins of 5 pixels are used.
 141
 142 \begin{verbatim}
 143   // Create some panel items
 144   wxButton *btn1 = new wxButton(frame->panel, -1, "A button") ;
 145
 146   wxLayoutConstraints *b1 = new wxLayoutConstraints;
 147   b1->centreX.SameAs    (frame->panel, wxCentreX);
 148   b1->top.SameAs        (frame->panel, wxTop, 5);
 149   b1->width.PercentOf   (frame->panel, wxWidth, 80);
 150   b1->height.PercentOf  (frame->panel, wxHeight, 10);
 151   btn1->SetConstraints(b1);
 152
 153   wxListBox *list = new wxListBox(frame->panel, -1, "A list",
 154                                   wxPoint(-1, -1), wxSize(200, 100));
 155
 156   wxLayoutConstraints *b2 = new wxLayoutConstraints;
 157   b2->top.Below         (btn1, 5);
 158   b2->left.SameAs       (frame->panel, wxLeft, 5);
 159   b2->width.PercentOf   (frame->panel, wxWidth, 40);
 160   b2->bottom.SameAs     (frame->panel, wxBottom, 5);
 161   list->SetConstraints(b2);
 162
 163   wxTextCtrl *mtext = new wxTextCtrl(frame->panel, -1, "Multiline text", "Some text",
 164                         wxPoint(-1, -1), wxSize(150, 100), wxTE_MULTILINE);
 165
 166   wxLayoutConstraints *b3 = new wxLayoutConstraints;
 167   b3->top.Below         (btn1, 5);
 168   b3->left.RightOf      (list, 5);
 169   b3->right.SameAs      (frame->panel, wxRight, 5);
 170   b3->bottom.SameAs     (frame->panel, wxBottom, 5);
 171   mtext->SetConstraints(b3);
 172 \end{verbatim}
 173
 174