Label Script

Context: HL Kit … Kit Reference … Script Types 

Technical Details

Initial Context:	Pick or Thing
Alternate Context:	None
Fields Finalized?	Yes
Where Used:	Portals
Procedure Use:	"label" type, "info" context, "pick" context

The Label script utilizes the following special symbols:

text	(String) Entry: Contains the pre-defined text for the label portal. Exit: Contains the text to be displayed to the user as the label portal contents. The final text may contain encoding.
ispick	(Number) Entry: Indicates whether the text is being rendered for a thing (zero) or a pick (non-zero), allowing different handling to be performed for the two separate cases. Exit: Ignored.

Description

The Label script is used exclusively within label portals, and it is the script defined for just-in-time rendering of the portal contents. Instead of pulling the information for display out of a field or using literal text, a script is defined. This script is invoked every time the display updates, allowing the script to re-calculate the information to be displayed based on the most recent state of the portfolio.

NOTE!  The Label script is read-only. Within this script, virtually all aspects of the structural hierarchy can be accessed, but nothing can be changed.

IMPORTANT! Avoid using Label scripts indiscriminately. Since the script must be re-evaluated and re-displayed with every update of the interface, they can be computationally expensive and slow down performance on slower computers. In many cases, a separate field can be used in which the appropriate value can be calculated and placed. When a field is used, HL will only update the display if the value actually changes.

Example

Within the d20 System data files, the hero's HP and AC are both shown at the top. Separate label portals could be used for each, but the width of the HP will vary from one to three digits, requiring scripts to re-calculate the positions of the portals all the time in case the number of digits has changed. It can be more efficient to simply use a single Label script that synthesizes the text to be displayed and eliminates all the re-positioning, resulting in a script like the one below.

@text = "HP: " & herofield[acHP].text & " AC: " & herofield[acArmorCls].text