Template Sizing Within Tables

From HLKitWiki
Revision as of 22:43, 19 November 2008 by Rob (Talk | contribs) (Width Control)

Jump to: navigation, search

[Context: HL KitBasic Concepts and TerminologyManipulation of Visual ElementsWorking 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 fit within the table - without increasing the established table width.

if multiple columns, existing table width is unchanged and new template width is used -number of columns is now based on how many columns can be fit in the space using the column width dictated by the template -final table width is based on integral fit of the width

example 1 if table is 400 pixels and has two columns, template starts with a width of 200 if template sets width to 300, only one column will now fit table width is set to 300 pixels to correspond to the one column it contains

example 2 same starting state if template sets width to 150, three columns with now fit table width is set to 450 pixels to correspond to the three columns it contains


There are a few situations where you