Difference between revisions of "The Positioning Sequence"

From HLKitWiki
Jump to: navigation, search
Line 20: Line 20:
 
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.
 
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==
+
'''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.
  
-Layouts possess a single "position" script that can be used for all positioning
+
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.
    -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
+
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.
    -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
+
  
==Rendering Layouts and Templates==
+
'''NOTE!''' Rendering a template multiple times is computationally expensive. Consequently, you should limit re-rendering to only be used when it is truly needed.

Revision as of 04:26, 20 November 2008

[Context: HL KitBasic Concepts and TerminologyManipulation 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.