Template Sizing Within Tables

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

Overview

Templates are normally sized either by the layout that contains them or by the template itself. When templates are used within tables, the logic remains the same, but there are additional implications involved.

Triggering of Position Script

The Position script of the template is invoked separately for each individual item being displayed. It is also invoked once when the table sizing process is first initiated. During this initial invocation is when the dimensions of the template are actually used by the containing table. No other positioning logic within the script is applied.

During the initial sizing, you can use the "issizing" target reference to detect that state. When initial sizing is being performed, the template need only calculate its height and can bail out without doing anything else. Since any other script logic is going to be thrown away during the sizing operation, there is no need to perform it.

You will see a check of the "issizing" target reference in most table-based templates within the starting data files provided by the Kit. If sizing is occurring, the script bails out as soon as the dimensions are calculated. While not truly necessary, it is recommended that you use the same technique within your own data files.

Height Control

The height of a template is always expected to be controlled by the template when within a table. Most tables contain fixed-height items, where the height of each item is always the same. For these tables, the template dimensions are expected to be established during the special "sizing" invocation of the Position script.

During sizing, there is no specific item available to the template. The HL engine passes in a special, dummy item. This dummy item has values of zero for all numeric fields and values of the empty string ("") for all text-based fields. As a result, the template cannot base its height on the contents of an actual item. It must instead determine its size based on general characteristics, such as font heights and other such information.

Once established during the sizing invocation, the height remains fixed. Any subsequent attempt to set the height to a different value are ignored. The exception to this is with variable-height tables, which are only supported for printed output. Within such tables, each template has its height re-calculated for every item that is output.

Width Control

The handling of the width within table-based templates is significantly more interesting than the height. The width passes through many layers and is treated more as a suggestion than anything else when it is passed into the template. When the sizing invocation of the Position is triggered for a template, the width is initialized to a value that is based on sizing requests made upon the table portal itself within the layout. However, the final decision regarding the width is always at the discretion of the template.

Upon entry to the sizing invocation of the Position script, the width is based on two factors. The total width of the table portal drives the overall width available, while the number of columns specified for the table dictates how the overall width is carved up. Using these two values, the template width is initialized to a value that evenly splits up the overall table width into columns.

In most cases, you will simply accept the width value specified by the table. This is achieved by using the default width that is setup for you and not specifying the width yourself. All of the table-based templates within the starting data files provided with the Kit, and even those within the Savage Worlds data files, simply use the default width given by the table.