Information Access
[Context: HL Kit … Basic Concepts and Terminology … Scripting Language]
Overview
The goal of writing a script is to retrieve and/or manipulate one or more facets of either an actor or a visual element. Consequently, your primary focus, as an author, will be on how to access information. The Kit uses an hierarchical structure for managing all the different objects. This section of the documentation outlines the basics of how to navigate the hierarchy and access the information you need.
Script Contexts and Transitions
Every script begins with an initial context. The context depends entirely upon the script, but the context always refers to a specific object maintained by HL, such as a pick, an actor, or a layout. For example, an Eval Script begins with an initial context of the pick that the script will be executed upon. Similarly, a Position script for a layout begins with an initial context of the layout for which the contents need to be positioned on the screen.
When you are writing a script, you will often need to retrieve information from or apply changes to objects other than the initial context your script begins with. This is accomplished by transitioning to the context of a connected object within the hierarchy, thereby establishing the new object as the new context. For example, you can transition from a pick context to the context of the container that contains the pick. Or you can transition from a pick context to the context of one of its fields.
Using context transitions, you can "travel" through the hierarchy of objects (within limits), seeking out the specific objects you need to manipulate via your scripts. The exact list of what context transitions are possible is entirely dependent on the script and the current context. The specific transitions available are outlined in the Kit Reference documentation.
NOTE! It is possible to transition to an invalid (i.e. non-existent) context. For example, a script might try to transition from a container to a pick that doesn't exist within that container. If that occurs and the non-existent context is then accessed (e.g. getting the name of the non-existent pick), a run-time error will be reported and the access will fail.
