docs/doxygen/overviews/constraints.h

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