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.

If you actually set the template width to a new value, the HL engine honors that new width according to a few important rules.

1. If the table has only one column, the overall table width is changed to be based on the new width given by the template.
2. If the table has multiple columns, the new template width is used to determine how many columns can actually fit within the table, without increasing the established table width. Once the number of columns is determined, the table width is changed to be exactly the space needed for those columns. Remember that a table will always be sized to contain at least one item, so setting a template width that is wider than the table width will increase the overall width of the table.

The following are a couple of examples of the above rules being applied. Both examples assume that you start with a table that is 400 pixels in width and that has two columns.

1. If the template sets its width to 300, only one column will now fit. Consequently, the table width is set to 300 pixels to correspond with the one column the table contains.
2. If the template sets its width to 125, three columns with now fit. Consequently, the table width is set to 450 pixels to correspond with the three columns the table contains.

In all cases, the template has final authority over the final dimensions used for the table. The HL engine will suggestion a width that is usually appropriate, but the template is free to override that suggestion as it sees fit.