Using the Relative Panel

From RAD Studio
Jump to: navigation, search

Go Up to VCL


The TRelativePanel is a container control that allows you to position child controls relative to the panel itself or relative to other child controls of this panel.

Because of the non-restrictive nature of this control, you may easily set conflicting alignment rules if you do not respect some guidelines.

Precedence of Alignment Rules

This section is the most important thing that you need to keep in mind when using the relative panel. The process of positioning children of a relative panel executes in the following order:

  1. AlignXxWithPanel: Any "Align" properties that have to do with "Panel", such as AlignLeftWithPanel.
    • Centering (AlignXxCenterWithPanel) has priority over side alignments.
    • Left has priority over right, top over bottom.
  2. AlignXxWith: The rest of the "Align" properties.
    • Centering (AlignXxCenterWith) has priority over side alignments.
    • Left has priority over right, top over bottom.
  3. Side alignments: LeftOf, RightOf, Above and Below.
    • Left has priority over right, above over below.

The order that the children are positioned in step 2 and 3 depends on their index in the array of children. If you want a control to "win" over another in a conflict of alignment, set the index of the winning control to be higher.

Special Considerations

Out-of-sight Alignment (Disappearing Controls)

There are no checks to prevent you from setting an alignment that pushes a control out of the relative panel. In that case the control disappears from the panel. This is intentional and may prove useful in some cases.

Circular Dependency

The relationship between elements inside a TRelativePanel forms a directed graph. A circular dependency occurs when there is a cycle in this graph; that is, two elements have a dependency on each other, including through intermediate elements.

When you set a circular dependency, the TRelativePanel component detects it and throws an exception. If this occurs at design-time, the Designer displays an error message. Code invoking the EnableAlign or Realign members can also trigger the exception.

Conflicting Relationships

If you set multiple alignments that target the same edge of a control, you may encounter a conflict. Refer to the Precedence of Alignment Rules section for more information on which alignment rules have priority over others.

Opposite Edge Alignments and Auto-sizing

If you set both opposite edge (left and right or top and bottom) alignments of a control to the same target (either "Panel" or another sibling control) the affected control automatically changes its width or height to match that of a target. For example, If you set both AlignLeftWithPanel and AlignRightWithPanel for a button, that button changes its width to match the width of the relative panel.

This behavior may lead to some unexpected situations. For example, if you set both AlignLeftWithPanel| and AlignRightWithPanel for an edit control and the set that control to be LeftOf a button control, the edit control assumes the width of the relative panel but because of the "left of" button position rule, the edit control "goes out of" the relative panel.

See Also