Difference between revisions of "The Positioning Sequence"

From HLKitWiki
Jump to: navigation, search
(Recursive Descent Through Hierarchy)
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
[[Category:Basic Concepts and Terminology]]
+
{{context|Basic Concepts and Terminology|Manipulation of Visual Elements}}
[Context: [[Home|HL Kit]] … [[Basic Concepts and Terminology]] … [[Manipulation of Visual Elements]]]
+
  
 
==The Position Script==
 
==The Position Script==
Line 8: Line 7:
 
==Recursive Descent Through Hierarchy==
 
==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 HL engine utilizes a consistent process for positioning all of the visual elements. Each top-level element (i.e. scene) is handled independently. Within the context of each scene, 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 detailed in the sections below.
  
The overall positioning sequence can be defined as follows for a given top-level visual element.
+
Prior to doing the recursive positioning, all visual elements within the scene 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.
  
#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.
+
==Positioning Scenes (Panels, Forms, and Sheets)==
#Invoke the Position script for the top-level visual element.
+
#Any child layout of the top-level element that has not yet been rendered is now rendered.
+
  
 +
All positioning starts with a top-level visual element: either a panel, a form, or a sheet. Within the scene, the Position script is invoked. After the script returns, any child layout that has not yet been rendered is now rendered.
  
-Layouts possess a single "position" script that can be used for all positioning
+
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.
    -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
+
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.
    -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 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.
 +
 
 +
==Positioning Templates and Portals==
 +
 
 +
When a template is positioned, its Position script is invoked. This orchestrates the sizing and positioning of all portals within the template. Unlike the above visual elements, when the Position script returns for a template, there is nothing more to do for that template and/or its contents.

Latest revision as of 01:36, 22 November 2008

Context: HL KitBasic 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. scene) is handled independently. Within the context of each scene, 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 detailed in the sections below.

Prior to doing the recursive positioning, all visual elements within the scene 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 Scenes (Panels, Forms, and Sheets)

All positioning starts with a top-level visual element: either a panel, a form, or a sheet. Within the scene, 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.

Positioning Templates and Portals

When a template is positioned, its Position script is invoked. This orchestrates the sizing and positioning of all portals within the template. Unlike the above visual elements, when the Position script returns for a template, there is nothing more to do for that template and/or its contents.