Difference between revisions of "Information Access"

From HLKitWiki
Jump to: navigation, search
Line 8: Line 8:
 
==Script Contexts and Transitions==
 
==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.
+
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.
+
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 "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. The specific transitions available are outlined in the [[Kit Reference]] documentation.
 
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.
 
'''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.
 +
 +
==Dot Notation==
 +
 +
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 specify a valid context transition from the previous context. The target reference must be valid for the final context established. As an example, a target identifier might look something like "hero.child[strength].field[bonus].value", which starts with the current hero, transitions to the child pick with the id "strength", then transitions to the field within the pick with the id "bonus", and ultimately references the "value" of the field.
 +
 +
<span class="important">IMPORTANT!</span> 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. Any script for which this behavior occurs will specify it within the [[Kit Reference]] documentation.
 +
  
  

Revision as of 02:49, 18 November 2008

[Context: HL KitBasic Concepts and TerminologyScripting 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 performing a "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. 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.

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.

Dot Notation

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 specify a valid context transition from the previous context. The target reference must be valid for the final context established. As an example, a target identifier might look something like "hero.child[strength].field[bonus].value", which starts with the current hero, transitions to the child pick with the id "strength", then transitions to the field within the pick with the id "bonus", and ultimately references the "value" of the field.

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. Any script for which this behavior occurs will specify it within the Kit Reference documentation.