Information Access

Context: HL Kit … Basic Concepts and Terminology … Data Manipulation Basics 

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 performing a context transition 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. A complete list of contexts and specific transitions available is outlined in the Kit Reference documentation.

IMPORTANT! The initial script context resets for each separate identifier used within a script - it does not persist. This makes it easy to have a single statement access multiple different contexts by transitioning in different directions from the same initial starting point.

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.

Script Targets

Once you have established the final context to operate upon, you need to identify the specific facet of the context to access or manipulate. This is referred to as a target reference, or sometimes simply target. For example, if you have a pick context, you must specify whether you are interested in its name, its tags, or something else.

The syntax for accessing a given target aspect will vary, depending on what the target is and what information is needed to uniquely identify the desired target. All of the different target references are defined in Kit Reference documentation.

Target Identifiers

In order to access or manipulate a component, your script must specify both the intended context and the target. Scripts use an open-ended dot notation to convey this information and uniquely designate a target identifier. A target identifier represents the combination of context and target reference, which should yield a specific piece of information to operate upon. You can use valid target identifiers anywhere within scripts that you would use a simple variable, allowing you to retrieve the current value of a target identifier or set that value.

The target identifier consists of a sequence of zero or more context references, each separated by a period ('.'), and finally followed by a singe target reference. In sequence, each context reference must indicate a valid context transition from the previous context. The target reference must be valid for the final context established. This syntax for specifying a target identifier is referred to as the dot notation.