alignContainer

Type: Integer

Availability: Read or write at any time

The alignContainer property of the Frame class and JadeDockBase class enables the control to align itself to its parent container so that the control automatically resizes with the container. For example, if the container of a frame is the form, any form resize causes the frame to also resize automatically to fit the new form size.

If the frame has children, those children could also be resized automatically (another frame with the alignContainer property set or this frame with the alignChildren property set).

This property is handled the same way for Frame and JadeDockBar controls except that the handling is defined by the parent of the JadeDockBar control rather than by the control itself.

When aligning controls, you should be aware of the following functionality.

Sibling controls that have the alignContainer property set do not occupy the same area on their parent. If so, use the visible property to control the window that is currently displayed.
Controls that are aligned to their parent by using the alignContainer or alignChildren 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. Dock controls and StatusLine controls, for example, therefore remain visible and unchanged when the scroll bar of the parent is adjusted.
The relativeTop, relativeLeft, relativeWidth, and relativeHeight properties are ignored when a control is aligned.
The integralHeight property of TextBox and ListBox controls is ignored if the parent of those controls has the alignChildren property set.

If it is difficult positioning docking controls to meet your requirements in the JADE Painter when the alignContainer and alignChildren properties are set, use theSuspend Parent Alignments command from the JADE Painter Layout menu. The alignContainer and alignChildren properties of controls are then treated as though the property values are zero (0) so that no automatic alignment occurs.

When this command is unchecked (the default), the alignContainer and alignChildren properties of controls behave as normal.

For the Frame class, any non-zero alignment setting causes the frame to align to the width of its parent container. The setting then determines the vertical size and position of the frame.

The alignContainer property values for Frame controls are listed in the following table.

Frame Class Constant	Value	Description
AlignContainer_All	5	Aligns container. The frame aligns itself to its entire container size.
AlignContainer_AllHorizontally	5	Children share the entire remaining client area of the parent horizontally. (For details, see the following table of values for the JadeDockBase class alignContainer property.)
AlignContainer_AllVertically	6	Children share the entire remaining client area of the parent vertically. (For details, see the following table of values for the JadeDockBase class alignContainer property.)
AlignContainer_Bottom	2	The frame retains its current height and aligns the bottom of the frame to the bottom of its container.
AlignContainer_None	0	No alignment is performed (the default). Resizes of the frame container have no effect.
AlignContainer_Stretch	4	Stretches to next control below. The frame retains its current top position and stretches downwards until it encounters another control or the bottom of its container.
AlignContainer_Top	1	The frame retains its current height and aligns the top of the frame to the top of its container.
AlignContainer_Width	3	Aligns width. The frame retains its current height and top position.

For the Frame control, the AlignContainer_All (5) constant value for the alignContainer property is treated as the AlignContainer_AllHorizontal (5) value. Use this property to place a frame in a form with the alignContainer property set to AlignContainer_All (5) or AlignContainer_AllHorizontal (5).

When a ListBox control is placed inside the frame and the alignChildren property is also set to AlignChildren_All (2), the frame and the list box are resized to fit when the form is resized. By turning off the three-dimensional (3D) effects and the frames border, the entire frame can be hidden and yet still make use of the alignment features.

For the AlignContainer_Stretch (4) value, vertically adjacent frames and status line controls merge their borders if they both have the Window class borderStyle property set.

Additionally, if adjacent frames both have the borderStyle and bevelOuter properties set to BorderStyle_None (0) and Bevel_None (0) and the same boundaryBrush and boundaryColor property settings, the frames or status line controls merge their boundary areas.

For the JadeDockBase class, the alignContainer property values are listed in the following table.

Class Constant	Value	Description
AlignContainer_AllHorizontally	5	For this value of the alignContainer property, the children share the entire remaining client area of the parent horizontally. If there is one child only, 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 have been aligned so that they totally share 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.
AlignContainer_AllVertically	6	For this value of the alignContainer property, the children share the entire remaining client area of the parent vertically. If there is one child only, 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 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 width available, 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.
AlignContainer_Bottom	2	Positioned at the left and bottom of the remaining client area of the parent of the control, with a width equal to the width of the remaining area. The control retains its height unless its children can be automatically positioned and resized.
AlignContainer_Left	3	Positioned at the left and top of the remaining client area of the parent of the control, with a height equal to the height of the remaining area. The control retains its width unless its children can be automatically positioned and resized.
AlignContainer_None	0	There is no alignment to the parent of the control.
AlignContainer_Right	4	Positioned at the right and top of the remaining client area of the parent of the control, with a height equal to the height of the remaining area. The control retains its width unless its children can be automatically positioned and resized.
AlignContainer_Top	1	Positioned at the left and top of the remaining client area of the parent of the control, with a width equal to the width of the remaining area. The control retains its height unless its children can be automatically positioned and resized.

You can dock a JadeDockBar or JadeDockContainer control into any docking position (with one exception), regardless of the value of its alignContainer property. The docking control then adopts the new alignContainer property value implied by the docking mode. The exception is that a JadeDockBar control that has its alignContainer property set to AlignContainer_None cannot be docked AlignContainer_AllHorizontal or AlignContainer_AllVertical.

A JadeDockBar control whose alignContainer property is set to AlignContainer_None is mostly useful as a toolbar sitting on a JadeDockContainer control as its parent and when docked somewhere else, it remains at its current size or the size derived from its children if the value of the alignChildren property is AlignChildren_Auto. Even when dragged and docked left, right, top, or bottom, it requires a JadeDockContainer control as its parent. If it is not docked into a JadeDockContainer control, it clones its original JadeDockContainer parent or creates a new JadeDockContainer control if it did not have one.

Setting the alignContainer property to AlignContainer_AllHorizontal causes all other siblings with the property set to AlignContainer_AllHorizontal to also be set to AlignContainer_AllVertical.

Similarly, setting the alignContainer property to AlignContainer_AllVertical causes all other siblings with the alignContainer property set to AlignContainer_AllHorizontal to also be set to AlignContainer_AllVertical. In addition, a Frame control could be aligned to the top, bottom, width, or stretched to the next control or to its entire parent container area. If multiple controls were added to the same parent with the same alignment type, they occupy the same positions within the parent.

You can have a number of different controls all aligned in the same or in different ways within the parent, to allow the dock bar containers to co-exist with each other, with StatusLine controls, and with aligned Frame controls.

In addition, controls with the same alignment type (and therefore the same alignment priority) are ordered by their position. For example, the order of two controls aligned to the top of the parent is based on the current top positions of the controls. If the top positions are the same, the control that is placed above the other is undefined. Similarly, controls aligned to the bottom are ordered in reverse order of their top positions, left-aligned controls by their left positions, and right-aligned controls are ordered in reverse order of their left position.

To enable multiple controls to be aligned in different ways within the same parent, the values of the alignContainer property have a priority.

Each control is aligned in the following priority order so that the control is positioned using the remaining space after each previous alignment within that parent.

Dock control top-aligned
Dock control bottom-aligned
Dock control left-aligned
Dock control right-aligned
Frame control top-aligned
Frame or status line bottom-aligned
Frame width-aligned
Frame stretched to the next control
Frame or dock control aligned-all horizontally
Frame or dock control aligned-all vertically

Controls with such alignments are automatically re-evaluated and resized, when required, under the following conditions.

A control is moved
A control is resized
A control is added to the form
A control is deleted from the form
The visible property of the control is changed
The alignContainer property of the control is changed
The alignChildren property of the control is changed
A docking control is floated
A docking control is docked
The parent of a control is changed

The following image is an example of a form that includes docking container controls.

In this image:

A docking container is aligned to the top (with a dock bar inside, holding pictures and a combo box)
A docking container is aligned on the right (with a dock bar inside, holding pictures)
Frame1 is aligned to the top
Two status lines are aligned to the bottom
Frame2 is aligned all, containing a list box and a table, and the Frame control has the alignChildren property set to AlignChildren_All (2)
Frame3 is aligned all

If the user resizes the form in this example, all of the aligned containers are readjusted without JADE logic being required. In addition, the ListBox and Table controls are also resized, because Frame2 uses the value AlignChildren_All (2) of the alignChildren property.

Frame2 and Frame3 demonstrate the align ‘all’ concept so that they are stretched vertically and they share the remaining space horizontally in the form. The left position of Frame3 determines how much space the Frame2 control is given. Similarly, Frame2 has the alignChildren property set to AlignChildren_All (2), which aligns the list box and table within the Frame2 area with the left position of the table, determining how much width the list box is assigned.

Frames aligned to the width and stretched to the next control (that is, those with priority 7, in which the frame width is aligned, and priority 8, in which the frame is stretched to the next control) do not adjust the remaining space used for alignment and therefore should not be mixed with align ‘all’ types (that is, those with priority 9, in which the frame or dock control are aligned-all horizontally, and priority 10, in which the frame or dock control are aligned-all vertically).

The value of the alignContainer property of a control can be defined by using its own alignContainer property value and the alignChildren property of its parent. If the alignContainer property of a control is set, that setting takes precedence over the value of the alignChildren property of its parent.

If a container contains controls that are docked both ‘all’ vertically and horizontally, they are aligned horizontally.

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. For details about adding resize bars to docking controls that are all aligned horizontally or vertically, see the showResizeBar property.