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.

Positioning Layouts

-Layouts possess a single "position" script that can be used for all positioning

   -Replaces the previous "pre-child" and "post-child" positioning scripts
       -Old scripts cannot be used in combination with new script - either or
   -If a template needs to be positioned explicitly during the layout's position
       script, authors can use the "render" target reference on the template to
       invoke its position script
       -Eliminates the need for pre- and post-processing, since author controls
           when templates are processed and can access the resultant position
           information afterwards within the one script
   -Any template that is NOT explicitly positioned by the layout script is
       automatically positioned after the script completes

-Scenes possess a single "position" script that can be used for all positioning

   -Replaces the previous "pre-layout" and "post-layout" positioning scripts
       -Old scripts cannot be used in combination with new script - either or
   -If a layout needs to be positioned explicitly during the scene's position
       script, authors can use the "render" target reference on the layout to
       invoke its position script
       -Eliminates the need for pre- and post-processing, since author controls
           when layouts are processed and can access the resultant position
           information afterwards within the one script
   -If a scene needs to figure out how much space a layout would consume given
       certain conditions, but without actually rendering the contents of the
       layout, authors can use the "estimate" target reference on the layout to
       invoke its position script in a non-output mode
       -The estimate logic invokes the layout's position script as if the layout
           is being rendered but does not actually render it (much like a print
           preview), after which the contents of the layout reflect the position
           of everything just as if the actual render was performed
       -Critical for output, where a sheet script can estimate the size of a
           layout, make adjustments, and then render it
       -Estimation is computationally expensive, so it should only be used when
           absolutely necessary within the UI (the cost is less important when
           printing a character sheet)
   -Any layout that is NOT explicitly positioned by the scene script is
       automatically positioned after the script completes