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 #define void AsIs()     /* implementation is private */
  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
  71         The left edge.
  72
  73         wxTop
  74
  75
  76         The top edge.
  77
  78         wxRight
  79
  80
  81         The right edge.
  82
  83         wxBottom
  84
  85
  86         The bottom edge.
  87
  88         wxCentreX
  89
  90
  91         The x-coordinate of the centre of the window.
  92
  93         wxCentreY
  94
  95
  96         The y-coordinate of the centre of the window.
  97
  98         The @e wxRelationship enumerated type specifies the relationship that
  99         this edge or dimension has with another specified edge or dimension. Normally,
 100         the user
 101         doesn't use these directly because functions such as @e Below and @e RightOf
 102         are a convenience
 103         for using the more general @e Set function.
 104
 105         wxUnconstrained
 106
 107
 108         The edge or dimension is unconstrained (the default for edges.
 109
 110         wxAsIs
 111
 112
 113         The edge or dimension is to be taken from the current window position or size
 114         (the
 115         default for dimensions.
 116
 117         wxAbove
 118
 119
 120         The edge should be above another edge.
 121
 122         wxBelow
 123
 124
 125         The edge should be below another edge.
 126
 127         wxLeftOf
 128
 129
 130         The edge should be to the left of another edge.
 131
 132         wxRightOf
 133
 134
 135         The edge should be to the right of another edge.
 136
 137         wxSameAs
 138
 139
 140         The edge or dimension should be the same as another edge or dimension.
 141
 142         wxPercentOf
 143
 144
 145         The edge or dimension should be a percentage of another edge or dimension.
 146
 147         wxAbsolute
 148
 149
 150         The edge or dimension should be a given absolute value.
 151     */
 152
 153
 154     /**
 155         Constrains this edge to be to the left of the given window, with an
 156         optional margin. Implicitly, this is relative to the left edge of the other
 157         window.
 158     */
 159     void LeftOf(wxWindow * otherWin, int margin = 0);
 160
 161     /**
 162         Constrains this edge or dimension to be to a percentage of the given window,
 163         with an
 164         optional margin.
 165     */
 166     void PercentOf(wxWindow * otherWin, wxEdge edge, int per);
 167
 168     /**
 169         Constrains this edge to be to the right of the given window, with an
 170         optional margin. Implicitly, this is relative to the right edge of the other
 171         window.
 172     */
 173     void RightOf(wxWindow * otherWin, int margin = 0);
 174
 175     /**
 176         Constrains this edge or dimension to be to the same as the edge of the given
 177         window, with an
 178         optional margin.
 179     */
 180     void SameAs(wxWindow * otherWin, wxEdge edge, int margin = 0);
 181
 182     /**
 183         Sets the properties of the constraint. Normally called by one of the convenience
 184         functions such as Above, RightOf, SameAs.
 185     */
 186 #define void Set(wxRelationship rel, wxWindow * otherWin,
 187              wxEdge otherEdge, int value = 0,
 188              int margin = 0)     /* implementation is private */
 189
 190     /**
 191         Sets this edge or dimension to be unconstrained, that is, dependent on
 192         other edges and dimensions from which this value can be deduced.
 193     */
 194     void Unconstrained();
 195 };
 196
 197
 198 /**
 199     @class wxLayoutConstraints
 200     @wxheader{layout.h}
 201
 202     @b Note: constraints are now deprecated and you should use sizers instead.
 203
 204     Objects of this class can be associated with a window to define its
 205     layout constraints, with respect to siblings or its parent.
 206
 207     The class consists of the following eight constraints of class
 208     wxIndividualLayoutConstraint,
 209     some or all of which should be accessed directly to set the appropriate
 210     constraints.
 211
 212      @b left: represents the left hand edge of the window
 213      @b right: represents the right hand edge of the window
 214      @b top: represents the top edge of the window
 215      @b bottom: represents the bottom edge of the window
 216      @b width: represents the width of the window
 217      @b height: represents the height of the window
 218      @b centreX: represents the horizontal centre point of the window
 219      @b centreY: represents the vertical centre point of the window
 220
 221     Most constraints are initially set to have the relationship wxUnconstrained,
 222     which means that their values should be calculated by looking at known
 223     constraints.
 224     The exceptions are @e width and @e height, which are set to wxAsIs to
 225     ensure that if the user does not specify a constraint, the existing
 226     width and height will be used, to be compatible with panel items which often
 227     have take a default size. If the constraint is wxAsIs, the dimension will
 228     not be changed.
 229
 230     @b wxPerl note: In wxPerl the constraints are accessed as
 231
 232     @code
 233     constraint = Wx::LayoutConstraints-new();
 234       constraint-centreX-AsIs();
 235       constraint-centreY-Unconstrained();
 236     @endcode
 237
 238
 239     @library{wxcore}
 240     @category{winlayout}
 241
 242     @seealso
 243     @ref overview_constraintsoverview "Overview and examples",
 244     wxIndividualLayoutConstraint, wxWindow::SetConstraints
 245 */
 246 class wxLayoutConstraints : public wxObject
 247 {
 248 public:
 249     /**
 250         Constructor.
 251     */
 252     wxLayoutConstraints();
 253
 254     /**
 255         wxIndividualLayoutConstraint bottom
 256
 257         Constraint for the bottom edge.
 258     */
 259
 260
 261     /**
 262         wxIndividualLayoutConstraint centreX
 263
 264         Constraint for the horizontal centre point.
 265     */
 266
 267
 268     /**
 269         wxIndividualLayoutConstraint centreY
 270
 271         Constraint for the vertical centre point.
 272     */
 273
 274
 275     /**
 276         wxIndividualLayoutConstraint height
 277
 278         Constraint for the height.
 279     */
 280
 281
 282     /**
 283         wxIndividualLayoutConstraint left
 284
 285         Constraint for the left-hand edge.
 286     */
 287
 288
 289     /**
 290         wxIndividualLayoutConstraint right
 291
 292         Constraint for the right-hand edge.
 293     */
 294
 295
 296     /**
 297         wxIndividualLayoutConstraint top
 298
 299         Constraint for the top edge.
 300     */
 301
 302
 303     /**
 304         wxIndividualLayoutConstraint width
 305
 306         Constraint for the width.
 307     */
 308 };