Script Contexts

Context: HL Kit … Kit Reference 

Overview

This first step in accessing data via scripts is in identifying where that data resides within the overall data hierarchy. A separate hierarchy is maintained for both structural information (e.g. actors, picks, gizmos, minions, etc.) and visual information (e.g. panels, layouts, templates, etc.). Each different layer within the hierarchy is considered a distinct "context".

IMPORTANT! Within certain script contexts, all target references are treated as read-only, regardless of whether they are normally writable. Any attempts to modify the contents of a target reference that has been forced to be read-only will fail to either compile or work at run-time. For example, if a Position script for a visual element attempts to modify the contents of a pick, it will be forbidden. Scripts and/or contexts within which this behavior occurs should specify it within their documentation.

Contexts Within Structural Hierarchy

Within the structural hierarchy, there are a variety of contexts managed by the Kit. The following table identifies these contexts and provides a brief description of what each represents.

portfolio	The "portfolio" context represents the topmost level within the structural hierarchy, encapsulating all of the different leads that have been created. This context is generally not accessible via scripts, as each lead is considered to be an atomic object.
hero	The "hero" context represents an individual actor within the portfolio. This actor could be a lead or a minion.
container	The "container" context represents any container within the portfolio. The container could be an actor or a gizmo.
pick	The "pick" context represents any pick throughout the portfolio, located within any container.
thing	The "thing" context represents a thing that has not been added to the portfolio. The thing context is very similar to the pick context in behavior, with the only real difference being that the dynamic facets of picks don't exist for things, resulting in many valid actions for picks being inaccessible from things.
field	The "field" context represents any field within any pick or thing. If within a thing, all aspects of the field are read-only.
pool	The "pool" context represents any usage pool associated with either the actor or a specific pick.

There are also quite a few logical contexts within the structural hierarchy. Each of these contexts actually maps to one of the basic contexts above, but it is identified below due to important considerations, such as added restrictions or limitations on what can be done within the context.

parent	The "parent" context is wholly dependent on the current context. If the current context is a pick, then the parent is the container that the pick resides within. If the current context is a container, then the parent is the pick that attaches the gizmo, unless the container is an actor, in which case there is no parent.
linkage	The "linkage" context proceeds from one pick to another pick that has been associated with the first pick via a named linkage. If no linkage has been established, then there is no linkage context.
root	The "root" context identifies the pick that bootstrapped the current pick. If the pick was not bootstrapped by another pick, then there is no root context.
dynalink	The "dynalink" context provides access from one pick to another pick that is dynamically setup via the Creation script for the original pick. If no dynamic link is setup for a pick, there is no dynalink context.
gearholder	The "gearholder" context accesses the pick that is designated as the "holder" of the current pick. If the pick is not gear or is not presently assigned to another piece of gear as a holder, there is no gearholder context.
shadow	The "shadow" context represents the shadowed version of a pick, which resides within a different location in the structural hierarchy due the shadowing. If the pick is not shadowed, there is no shadow context.
origin	The "origin" context represents the original version of a displaced pick, which resides within a different location in the structural hierarchy due to the displacement. If the pick is not displaced, there is no origin context.
master	The "master" context identifies the actor that is the master of the current actor. If the current actor is not a minion, there is no master context.
minion	The "minion" context identifies an actor that is a minion of the current actor. If the current actor is not a master, there is no minion context.
anchor	The "anchor" context identifies the specific pick that attaches the current actor as a minion. If the current actor is not a minion, there is no anchor context.
child	The "child" context accesses a specific child pick that exists within the current container.
gizmo	The "gizmo" context references the gizmo that is attached as a child of the current pick. If the pick does not attach a gizmo, there is no gizmo context.

Contexts Within Visual Hierarchy

The visual hierarchy has a separate set of contexts that are managed by the Kit and that are accessed exclusively via Position scripts on visual elements. The following table describes each of these contexts.

scene	The "scene" context identifies the top-level visual element within the current hierarchy, which will be either a panel, a form, or a sheet.
layout	The "layout" context identifies a layout within the top-level scene of the current hierarchy.
template	The "template" context identifies a template within the current hierarchy. Templates can either be used within layouts or within tables, so the parent context of the template within the hierarchy can vary.
portal	The "portal" context identifies a portal within the current hierarchy. Portals can either be used within templates or within layouts, so the parent context of the portal within the hierarchy can vary.
table	The "table" context identifies the containing table of a template or portal within the current hierarchy.
value	The "value" context represents any field within the pick or thing associated with a template. The value context is used for display only, so all aspects of the field are always read-only.

There are also a few logical contexts within the visual hierarchy. Each of these contexts actually maps to a basic context, but it is identified below due to important considerations, such as added restrictions or limitations on what can be done within the context.

parent	The "parent" context is wholly dependent on the current context, as detailed below. portal – The parent is the visual container that the portal resides within (i.e. a template or a layout). template – The parent is the visual container that the template resides within (i.e. a layout or a table). layout – The parent is the containing scene. scene – There is no parent for a scene.
chosen	The "chosen" context represents the current selection within a thing-based menu, so it can either be a pick or thing.
hero	The "hero" context within a visual script identifies the actor that the visual element is operating upon. This context is always treated as read-only from within a visual script.
container	The "container" context within a visual script identifies the container that the visual element is operating upon. This context is always treated as read-only from within a visual script.
value	The "value" context within a visual script represents the contents of a field. The field is accessed via a pick, which is identified by the template from which the value context is being utilized.

General Contexts

In addition to the structural and visual contexts, the Kit supports contexts that are outside of the the normal hierarchy. These general contexts are described in the table below.

state	The "state" context provides access to overall state information that pertains to the portfolio as a whole or general information about the evaluation cycle.
transaction	The "transaction" context represents the special pick that is utilized for buy and sell transactions. Since such transactions can be canceled by the user, all the details must be managed in a temporary fashion until the user completes the transaction.
focus	The "focus" context reflects the pick that has been established as the current "pick focus" via explicit actions within scripts. If no pick focus has been setup, then there is no focus context.
actor	The "actor" context reflects the hero that has been established as the current "actor focus" via explicit actions within scripts. If no actor focus has been setup, then there is no actor context.
eachpick	The "eachpick" context reflects the current pick that is being processed within a "foreach" loop performed by a script.
altpick	The "altpick" context identifies a secondary pick that is involved in an operation, such as when merging two stackable picks into one.
altthing	The "altthing" context identifies a secondary thing that is involved in an operation, such as is necessary when performing pre-requisite tests.