interface/layout.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        layout.h
   3 // Purpose:     documentation for wxIndividualLayoutConstraint class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxIndividualLayoutConstraint
  11     @wxheader{layout.h}
  12
  13     Objects of this class are stored in the wxLayoutConstraint class
  14     as one of eight possible constraints that a window can be involved in.
  15
  16     Constraints are initially set to have the relationship wxUnconstrained,
  17     which means that their values should be calculated by looking at known
  18     constraints.
  19
  20     @library{wxcore}
  21     @category{winlayout}
  22
  23     @seealso
  24     @ref overview_constraintsoverview "Overview and examples", wxLayoutConstraints,
  25     wxWindow::SetConstraints.
  26 */
  27 class wxIndividualLayoutConstraint : public wxObject
  28 {
  29 public:
  30     /**
  31         Constructor. Not used by the end-user.
  32     */
  33     wxIndividualLayoutConstraint();
  34
  35     /**
  36         Constrains this edge to be above the given window, with an
  37         optional margin. Implicitly, this is relative to the top edge of the other
  38         window.
  39     */
  40     void Above(wxWindow* otherWin, int margin = 0);
  41
  42     /**
  43         Constrains this edge or dimension to be the given absolute value.
  44     */
  45     void Absolute(int value);
  46
  47     /**
  48         Sets this edge or constraint to be whatever the window's value is
  49         at the moment. If either of the width and height constraints
  50         are @e as is, the window will not be resized, but moved instead.
  51         This is important when considering panel items which are intended
  52         to have a default size, such as a button, which may take its size
  53         from the size of the button label.
  54     */
  55     void AsIs();
  56
  57     /**
  58         Constrains this edge to be below the given window, with an
  59         optional margin. Implicitly, this is relative to the bottom edge of the other
  60         window.
  61     */
  62     void Below(wxWindow* otherWin, int margin = 0);
  63
  64     /**
  65         The @e wxEdge enumerated type specifies the type of edge or dimension of a
  66         window.
  67
  68         wxLeft
  69
  70         The left edge.
  71
  72         wxTop
  73
  74         The top edge.
  75
  76         wxRight
  77
  78         The right edge.
  79
  80         wxBottom
  81
  82         The bottom edge.
  83
  84         wxCentreX
  85
  86         The x-coordinate of the centre of the window.
  87
  88         wxCentreY
  89
  90         The y-coordinate of the centre of the window.
  91
  92         The @e wxRelationship enumerated type specifies the relationship that
  93         this edge or dimension has with another specified edge or dimension. Normally,
  94         the user
  95         doesn't use these directly because functions such as @e Below and @e RightOf
  96         are a convenience
  97         for using the more general @e Set function.
  98
  99         wxUnconstrained
 100
 101         The edge or dimension is unconstrained (the default for edges.
 102
 103         wxAsIs
 104
 105         The edge or dimension is to be taken from the current window position or size
 106         (the
 107         default for dimensions.
 108
 109         wxAbove
 110
 111         The edge should be above another edge.
 112
 113         wxBelow
 114
 115         The edge should be below another edge.
 116
 117         wxLeftOf
 118
 119         The edge should be to the left of another edge.
 120
 121         wxRightOf
 122
 123         The edge should be to the right of another edge.
 124
 125         wxSameAs
 126
 127         The edge or dimension should be the same as another edge or dimension.
 128
 129         wxPercentOf
 130
 131         The edge or dimension should be a percentage of another edge or dimension.
 132
 133         wxAbsolute
 134
 135         The edge or dimension should be a given absolute value.
 136     */
 137
 138
 139     /**
 140         Constrains this edge to be to the left of the given window, with an
 141         optional margin. Implicitly, this is relative to the left edge of the other
 142         window.
 143     */
 144     void LeftOf(wxWindow* otherWin, int margin = 0);
 145
 146     /**
 147         Constrains this edge or dimension to be to a percentage of the given window,
 148         with an
 149         optional margin.
 150     */
 151     void PercentOf(wxWindow* otherWin, wxEdge edge, int per);
 152
 153     /**
 154         Constrains this edge to be to the right of the given window, with an
 155         optional margin. Implicitly, this is relative to the right edge of the other
 156         window.
 157     */
 158     void RightOf(wxWindow* otherWin, int margin = 0);
 159
 160     /**
 161         Constrains this edge or dimension to be to the same as the edge of the given
 162         window, with an
 163         optional margin.
 164     */
 165     void SameAs(wxWindow* otherWin, wxEdge edge, int margin = 0);
 166
 167     /**
 168         Sets the properties of the constraint. Normally called by one of the convenience
 169         functions such as Above, RightOf, SameAs.
 170     */
 171     void Set(wxRelationship rel, wxWindow* otherWin,
 172              wxEdge otherEdge, int value = 0,
 173              int margin = 0);
 174
 175     /**
 176         Sets this edge or dimension to be unconstrained, that is, dependent on
 177         other edges and dimensions from which this value can be deduced.
 178     */
 179     void Unconstrained();
 180 };
 181
 182
 183 /**
 184     @class wxLayoutConstraints
 185     @wxheader{layout.h}
 186
 187     @b Note: constraints are now deprecated and you should use sizers instead.
 188
 189     Objects of this class can be associated with a window to define its
 190     layout constraints, with respect to siblings or its parent.
 191
 192     The class consists of the following eight constraints of class
 193     wxIndividualLayoutConstraint,
 194     some or all of which should be accessed directly to set the appropriate
 195     constraints.
 196
 197      @b left: represents the left hand edge of the window
 198      @b right: represents the right hand edge of the window
 199      @b top: represents the top edge of the window
 200      @b bottom: represents the bottom edge of the window
 201      @b width: represents the width of the window
 202      @b height: represents the height of the window
 203      @b centreX: represents the horizontal centre point of the window
 204      @b centreY: represents the vertical centre point of the window
 205
 206     Most constraints are initially set to have the relationship wxUnconstrained,
 207     which means that their values should be calculated by looking at known
 208     constraints.
 209     The exceptions are @e width and @e height, which are set to wxAsIs to
 210     ensure that if the user does not specify a constraint, the existing
 211     width and height will be used, to be compatible with panel items which often
 212     have take a default size. If the constraint is wxAsIs, the dimension will
 213     not be changed.
 214
 215     @b wxPerl note: In wxPerl the constraints are accessed as
 216
 217     @code
 218     constraint = Wx::LayoutConstraints-new();
 219       constraint-centreX-AsIs();
 220       constraint-centreY-Unconstrained();
 221     @endcode
 222
 223
 224     @library{wxcore}
 225     @category{winlayout}
 226
 227     @seealso
 228     @ref overview_constraintsoverview "Overview and examples",
 229     wxIndividualLayoutConstraint, wxWindow::SetConstraints
 230 */
 231 class wxLayoutConstraints : public wxObject
 232 {
 233 public:
 234     /**
 235         Constructor.
 236     */
 237     wxLayoutConstraints();
 238
 239     /**
 240         wxIndividualLayoutConstraint bottom
 241         Constraint for the bottom edge.
 242     */
 243
 244
 245     /**
 246         wxIndividualLayoutConstraint centreX
 247         Constraint for the horizontal centre point.
 248     */
 249
 250
 251     /**
 252         wxIndividualLayoutConstraint centreY
 253         Constraint for the vertical centre point.
 254     */
 255
 256
 257     /**
 258         wxIndividualLayoutConstraint height
 259         Constraint for the height.
 260     */
 261
 262
 263     /**
 264         wxIndividualLayoutConstraint left
 265         Constraint for the left-hand edge.
 266     */
 267
 268
 269     /**
 270         wxIndividualLayoutConstraint right
 271         Constraint for the right-hand edge.
 272     */
 273
 274
 275     /**
 276         wxIndividualLayoutConstraint top
 277         Constraint for the top edge.
 278     */
 279
 280
 281     /**
 282         wxIndividualLayoutConstraint width
 283         Constraint for the width.
 284     */
 285 };