The Positioning Sequence

[Context: HL Kit … Basic Concepts and Terminology … Manipulation of Visual Elements]

The Position Script

Every visual container possesses a "position" script, which means the script is possessed by every template, layout, panel, and sheet. The Position script serves one specific purpose - to properly size, position, and configure all of the child elements within the visual container. Not every visual container needs to define a position script, since the HL engine performs some actions automatically, but most visual containers will perform at least some operations within their Position, and some will perform extensive operations to properly setup the visual elements within them.

Recursive Descent Through Hierarchy

The HL engine utilizes a consistent process for positioning all of the visual elements. Each top-level element (i.e. panel or sheet) is handled independently. Within the context of each top-level element, a recursive descent is performed upon all of the visual elements it contains, invoking the Position script within each visual element during the descent. How this works is details in the sections below.

Prior to doing the recursive positioning, all visual elements within the top-level element are properly reset. This entails setting their position to (0,0), performing default sizing, and initializing their default state. In general, only portals possess default sizing and state.

Positioning Panels and Sheets

All positioning starts with a top-level visual element: either a panel or a sheet. Within the top-level element, the Position script is invoked. After the script returns, any child layout that has not yet been rendered is now rendered.

Within the Position script, the panel or sheet may need to force a layout to properly calculate its size before another layout can be positioned relative to the first one. When this occurs, the panel or sheet can explicitly tell the layout to render itself by using the "render" target reference on that layout. Rendering a layout invokes the Position script for that layout immediately. Since each layout is automatically rendered at the end, triggering the render from the Position script is only necessary if the rendered results are needed within the script.

Rendering a layout does not place anything on the screen or page. All it does is trigger appropriate sizing, positioning, and state configuration. It is perfectly valid to render a layout multiple times. In fact, there will be situations where you will want to do this to optimally position information. You can render a layout, find out about size of the layout, force a change to the layout, then render the layout again.

NOTE! Rendering a layout multiple times is computationally expensive. Consequently, you should limit re-rendering to only be used when it is truly needed.

Positioning Layouts

When a layout is positioned, its Position script is invoked. Once the script returns, any child templates that have not yet been rendered are now rendered.

Just like with panels and sheets, the layout may need to force a child template to calculate its size before a separate visual element can be positioned relative to it. You can explicitly trigger a template to be rendered by invoking the "render" target reference on the template. As above, rendering a template immediately invokes the Position script of that template. This is not always necessary, since the layout will automatically render all templates after the Position script completes.

In the same way that layout rendering does not actually output anything, template rendering simply determines the position, size, and state of the template and its contents. Nothing is actually output, so it is valid to render a template multiple times, and there may be situations where you need to do that.

NOTE! Rendering a template multiple times is computationally expensive. Consequently, you should limit re-rendering to only be used when it is truly needed.