alignChildren

Type: Integer

Availability: Read or write at any time

The alignChildren property of the Frame class and JadeDockBar class enables the frame or dock bar control to align child controls placed inside the frame or dock bar. The controls are automatically resized when the frame or dock bar resizes. If the three-dimensional (3D) effects are turned on for a Frame control, the children are placed inside the 3D border area.

For details about floating and docking container controls, see "Floating a Docking Control" and "Docking a Control", under the "JadeDockBase Class", earlier in this document. See also the docking examples under the allowDocking property, later in this document.

The settings of the Frame class alignChildren property are listed in the following table.

Frame Class Constant	Value	Description
AlignChildren_None	0	No alignment is performed (the default). Resizes of the frame have no effect.
AlignChildren_Width	1	Aligns width. When the frame is resized, each child control is sized to exactly fit the width of the client area of the frame (the area inside the 3D border).
AlignChildren_All	2	Aligns all. When the frame is resized, any child controls are also resized to exactly fit the height and width of the client area of the frame. If there is more than one child, they are all aligned.

Use this property to place a Frame in a form with the alignContainer property set to AlignChildren_All (2).

When a ListBox control is placed inside the frame and the alignChildren property set to AlignChildren_All, the frame and the list box are resized to fit when the form is resized.

By turning off the 3D effects and the frames border, the entire frame can be hidden and yet still make use of the alignment features.

The integralHeight property of TextBox and ListBox controls is ignored if the parent of those controls has the alignChildren property set.

Some controls, such as a check box, do not permit their size (usually the height) to change. The recalculation of the positions of the children occurs only if the size or position of the frame is altered. Changing the size and position of a child does not reposition the set of child controls within the frame, unless that child is also a frame control. To force the realignment, change to the size and position of the frame, or set the alignChildren property within logic (even if unchanged).

Dock controls that are aligned to their parent by using the JadeDockBar class alignChildren or alignContainer property and that have scroll bars are not scrolled and remain in place in their parent when the scroll bar of the parent is shifted. They therefore remain visible and unchanged when the scroll bar of the parent is adjusted.

The settings of this property for the JadeDockBar class are listed in the following table.

JadeDockBar Class Constant	Integer Value
AlignChildren_None	0
AlignChildren_AllHorizontal	1
AlignChildren_AllVertical	2
AlignChildren_Auto	3

For the JadeDockBar class, the AlignChildren_None (0) constant value has the following rules.

• The children within the dock bar remain in the positions allocated by the developer.

• The dock bar size is also unaffected by its children.

• Because the control has fixed positions for its children, docking the control cannot alter the position of the children or the size of the control itself. The current width is therefore retained and the docking could cause the waste of space in its parent.

If the alignChildren property is not set to AlignChildren_Auto and the width of the control is greater that its height and the control is dragged to a left or right docking position (and it is not currently docked left or right), the values of width and height properties are exchanged when considering the docking position.

Similarly, if the height of the control is greater than its width and the control is dragged to a top or bottom docking position (and it is not currently docked top or bottom), the values of width and height properties are exchanged when considering the docking position. This is necessary because the control does not know how to resize itself. For example, if the control were docked at the top and then dragged to the left position and these exchanges were not done, the control would retain its current width, stretch its height, and therefore probably use all of the space in its parent.

For the JadeDockBar class, the AlignChildren_AllHorizontal (1) constant value has the following rules.

• If there is only one child, the child is positioned at the left and top of that area with a width and height equal to the remaining width and height of that area.

• If there is more than one child, the children are positioned at the left of the remaining area with a width equal to the width of the remaining area. The child with the lowest top value is positioned at the top of the area, immediately followed by the next top-most child, and so on.

  The height of each child is the minimum of the gap between the initial top position and the top position of the next child, and the initial height of the child itself.

• If the combined height of the children exceeds the total available height, each child is equally reduced in height so that exactly the entire available area of the parent is used. If the combined height of the children is less than the total available height, each child is equally increased in height so that exactly the entire available area of the parent is used.

• When the children are aligned so that they share all of the remaining area of the parent, they retain their relative heights if the parent is subsequently resized. If the user resizes the form, no resize logic is therefore required when the parent height is affected by the height of the form.

For the JadeDockBar class, the AlignChildren_AllVertical (2) constant value has the following rules.

• If there is one child only, that child is positioned at the left and top of that area with a width and height equal to the remaining width and height of that area.

• If there is more than one child, the children are positioned at the top of the remaining area with a height equal to the height of the remaining area. The child with the lowest left value is positioned at the left of the area, immediately followed by the next left-most child, and so on.

  The width of each child is the minimum of the gap between the initial left position and the left position of the next child, and the initial width of the child itself.

• If the combined width of the children exceeds the total available width, each child is equally reduced in width so that exactly the entire available area of the parent is used. If the combined width of the children is less than the total available width, each child is equally increased in width so that exactly the entire available area of the parent is used.

• When the children have been aligned so that they share all of the remaining area of the parent, they retain their relative widths if the parent is subsequently resized. If the user resizes the form, no resize logic is therefore required when the parent width is affected by the width of the form.

For the JadeDockBar class, the AlignChildren_Auto (3) constant value has the following rules.

• The dock bar automatically positions the child controls in the order of the tabIndex property.

• The dock bar automatically resizes itself to the size required for its children.

• If the dock bar is aligned vertically, the controls are positioned in columns.

• If the dock bar is aligned horizontally, the controls are positioned horizontally in rows.

• Additional columns or rows result if the position of the controls would cause the dock bar to exceed the size of the area available within its parent.

• The spacing between the controls is determined by the value of the JadeDockBar class autoSpacingX and autoSpacingY properties.

• The spacing of a control from the edges of the dock bar area is half the value of the autoSpacingX property horizontally and half the value of the autoSpacingY property vertically.