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 strict 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.

The overall positioning sequence can be defined as follows for a given top-level visual element.

1. Recursively process all visual elements within the top-level element to reset their position to (0,0), perform default sizing, and initialize the default state. In general, only portals possess default sizing and state.
2. Invoke the Position script for the top-level visual element.
3. Any child layout of the top-level element that has not yet been rendered is now rendered.

-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