Defining Constraints

The most basic way to define a constraining relationship (that is, set up a relationship between an edge or size of one window and an edge or size of another window) is to use the Set function.

The Set function is defined in the TEdgeConstraint class and subsequently inherited by TEdgeOrWidthConstraint and TEdgeOrHeightConstraint. Here is the Set function declaration:

void Set(TEdge edge, TRelationship rel, TWindow* otherWin, TEdge otherEdge, int value = 0);

In this declaration,

• edge specifies which part of the window you are constraining and uses the enum TEdge, which has five possible values:
  • lmLeft specifies the left edge of the window.
  • lmTop specifies the top edge of the window.
  • lmRight specifies the right edge of the window.
  • lmBottom specifies the bottom edge of the window.
  • lmCenter specifies the center of the window. The object that owns the constraint, such as TLayoutMetrics, determines whether the center of the window is the vertical center or the horizontal center.
• You can also specify the window's width or height as a constraint, but only with TEdgeOrWidthConstraint and TEdgeOrHeightConstraint. Use the enum TWidthHeight, which has two possible values:
  • lmWidth specifies that the width of the window should be constrained.
  • lmHeight specifies that the height of the window should be constrained.
  • rel specifies the relationship between the two edges, as follows:

    rel	Relationship
    lmAsIs	This dimension is constrained to its current value.
    lmPercentOf	This dimension is constrained to a percentage of the constraining edge's size. This is usually used with a constraining width or height.
    lmAbove	This dimension is constrained to a certain distance above its constraining edge.
    lmLeftOf	This dimension is constrained to a certain distance to the left of its constraining edge.
    lmBelow	This dimension is constrained to a certain distance below its constraining edge.
    lmRightOf	This dimension is constrained to a certain distance to the right of its constraining edge.
    lmSameAs	This dimension is constrained to the same value as its constraining edge.
    lmAbsolute	This dimension is constrained to an absolute coordinate or size.

  • otherWin specifies the window with which you are constraining your child window. You must use the value lmParent when specifying the parent window. Otherwise, pass a pointer to the TDialog or TWindow-derived object containing the other window.
  • otherEdge specifies the particular edge of otherWin with which you are constraining your child window. otherEdge can have any of the values allowed for edge.
  • value means different things, depending on the value of rel:

    rel	Meaning of value
    lmAsIs	No meaning. Should be set to 0.
    lmPercentOf	What percent of the constraining measure the constrained measure should be.
    lmAbove	How many units above the constraining edge the constrained edge should be.
    lmLeftOf	How many units to the left of the constraining edge the constrained edge should be.
    lmBelow	How many units below the constraining edge the constrained edge should be.
    lmRightOf	How many units to the left of the constraining edge the constrained edge should be.
    lmSameAs	No meaning. Should be set to 0.
    lmAbsolute	The absolute measure for the constrained edge, as follows: When edge is lmLeft, lmRight, or sometimes lmCenter, value is the X coordinate for the edge. When edge is lmTop, lmBottom, or sometimes lmCenter, value is the Y coordinate for the edge. When edge is lmWidth or lmHeight, edge represents the size of the constraint. The owning object determines whether lmCenter represents an X or Y coordinate.

    The meaning of value is also dependent on the value of Units, a TMeasurementUnits member of TLayoutConstraint. TMeasurementUnits is an enum that describes the type of unit represented by value. Units can be either lmPixels or lmLayoutUnits. lmPixels indicates that value is meant to represent an absolute number of physical pixels. lmLayoutUnits indicates that value is meant to represent a number of logical units. These layout units are based on the size of the current font of the layout window. TEdgeConstraint also contains a number of functions that you can use to set up predefined relationships. These correspond closely to the relationships you can specify in the Set function. In fact, these functions call Set to define the constraining relationship. You can use these functions to set up a majority of the constraint relationships you define.

The following four functions work in a similar way:

void LeftOf (TWindow* sibling, int margin = 0);
void RightOf (TWindow* sibling, int margin = 0);
void Above (TWindow* sibling, int margin = 0);
void Below (TWindow* sibling, int margin = 0);

Each of these functions places the child window in a certain relationship with the constraining window sibling. The edges are predefined, with the constrained edge being the opposite of the function name and the constraining edge being the same as the function name.

For example, the LeftOf function places the child window to the left of sibling. This means the constrained edge of the child window is lmRight and the constraining edge of sibling is lmLeft.

You can set an edge of your child window to an absolute value with the Absolute function,

void Absolute(TEdge edge, int value);

edge indicates which edge you want to constrain, and value has the same value as when used in Set with the lmAbsolute relationship.

There are two other shortcut functions you can use,

void SameAs(TWindow* otherWin, TEdge edge);
void PercentOf(TWindow* otherWin, TEdge edge, int percent);

These two use the same edge for the constrained window and the constraining window. For example, if you specify lmLeft for edge, the left edge of your child window is constrained to the left edge of otherWin.