Information Access - Revision history

Rob at 23:14, 4 December 2008

2008-12-04T23:14:59Z

← Older revision		Revision as of 23:14, 4 December 2008
Line 1:		Line 1:
	{{context\|Basic Concepts and Terminology\|~~Scripting Language~~}}		{{context\|Basic Concepts and Terminology\|Data Manipulation Basics}}

	==Overview==		==Overview==
Line 27:		Line 27:
	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.		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.		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''.

Rob at 23:08, 4 December 2008

2008-12-04T23:08:41Z

← Older revision		Revision as of 23:08, 4 December 2008
Line 7:		Line 7:
	==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 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.		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.		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.
Line 19:		Line 19:
	==Script Targets==		==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.		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.		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~~==		==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.		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.		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.

	~~==Examples==~~

	Let's look at a few examples of combining context transitions with target references into a useful target identifier. For the first example, we assume we're writing an Eval Script in which we need to access the calculated bonus conferred by the "strength" ability score for the hero. Since an Eval Script starts out in the context of a pick, we'll just go directly to the hero and drill down to get the value we need. From the hero, we transition to the pick that contains the "strength" ability score. Once we have the pick, we then transition to the "bonus" field. And finally we access the value of that field. In the end, the complete reference might look like the following:

	~~<pre>~~
	~~hero.child[strength].field[bonus].value~~
	~~</pre>~~

	What if our hero has a magic sword from which we need to extract information? In this situation, we need to drill down into the child gizmo and then into a pick belonging to that gizmo. Starting from the root hero again, we first access the pick that attaches the gizmo. From there, we transition to the gizmo, after which we can transition to the pick inside the gizmo. Once we have the pick context, we can get the field and access its value. The final result would look something like the following:

	~~<pre>~~
	~~hero.child[magicsword].gizmo.child[attack].field[bonus].value~~
	~~</pre>~~

	Now let's assume we have a script on a pick within the above gizmo that needs to access a field on a different pick within the same gizmo. Theoretically, we could bounce all the way out to the hero and drill down, but that approach won't work reliably if we have multiple magic swords on the hero. So the best approach is to move upwards to the container and then back down again into the desired pick. The process would look something like the following:

	~~<pre>~~
	~~container.child[attack].field[bonus].value~~
	~~</pre>~~

	The key thing to remember when writing scripts is to always know your initial context. From there, simply identify where you want to reference and then systematically transition, one step at a time. If you take things one step at a time, you'll be able to access the information you need and your scripts will work smoothly.

	{{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.

Rob: /* Script Contexts and Transitions */

2008-12-04T22:57:34Z

Script Contexts and Transitions

← Older revision		Revision as of 22:57, 4 December 2008
Line 11:		Line 11:
	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.		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. 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.		{{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.

Rob at 08:33, 22 November 2008

2008-11-22T08:33:59Z

← Older revision		Revision as of 08:33, 22 November 2008
Line 1:		Line 1:
	~~[[Category:~~Basic Concepts and Terminology]]		{{context\|Basic Concepts and Terminology\|Scripting Language}}
	~~[Context: [[Home~~\|~~HL Kit]] [[Basic Concepts and Terminology]] [[~~Scripting Language~~]]]~~

	==Overview==		==Overview==

Rob: /* Script Contexts and Transitions */

2008-11-21T14:04:04Z

Script Contexts and Transitions

← Older revision		Revision as of 14:04, 21 November 2008
Line 16:		Line 16:
	{{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.		{{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.		{{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==		==Script Targets==

Rob at 13:54, 21 November 2008

2008-11-21T13:54:59Z

← Older revision		Revision as of 13:54, 21 November 2008
Line 14:		Line 14:
	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.

	~~<span class="~~important~~">IMPORTANT!</span>~~ 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.		{{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.		'''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.
Line 52:		Line 52:
	The key thing to remember when writing scripts is to always know your initial context. From there, simply identify where you want to reference and then systematically transition, one step at a time. If you take things one step at a time, you'll be able to access the information you need and your scripts will work smoothly.		The key thing to remember when writing scripts is to always know your initial context. From there, simply identify where you want to reference and then systematically transition, one step at a time. If you take things one step at a time, you'll be able to access the information you need and your scripts will work smoothly.

	~~<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.		{{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.

Rob: /* Script Contexts and Transitions */

2008-11-18T13:20:34Z

Script Contexts and Transitions

← Older revision		Revision as of 13:20, 18 November 2008
Line 13:		Line 13:

	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.

			<span class="important">IMPORTANT!</span> 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.		'''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.

Rob at 09:56, 18 November 2008

2008-11-18T09:56:38Z

@@ Line 26: / Line 26: @@
 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.
+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.
-<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.
+==Examples==
-*{{fl|Context Access - Transitions}}
+<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.

Rob at 09:49, 18 November 2008

2008-11-18T09:49:05Z

← Older revision		Revision as of 09:49, 18 November 2008
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.

Rob at 09:34, 18 November 2008

2008-11-18T09:34:49Z

← Older revision		Revision as of 09:34, 18 November 2008
Line 1:		Line 1:
	[[Category:Basic Concepts and Terminology]]		[[Category:Basic Concepts and Terminology]]
	[Context: [[Home\|HL Kit]] [[Basic Concepts and Terminology]] [[Scripting Language]]]		[Context: [[Home\|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.		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.

	==~~Topics~~==		==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.

	~~Each of the basic facets of information access is detailed in the topics below.~~

	*{{fl\|Script Contexts and Targets}}
	*{{fl\|Context Access - Transitions}}		*{{fl\|Context Access - Transitions}}
	*{{fl\|Target Access}}		*{{fl\|Target Access}}
	*{{fl\|Combining Contexts and Targets}}		*{{fl\|Combining Contexts and Targets}}
	*{{fl\|Special Symbols}}		*{{fl\|Special Symbols}}