Class Documentation

Name:Script
Version:1.0
ID:ID_SCRIPT
Status:Stable
Category:Data
Date:December 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2003. All rights reserved.
Short:  The Script class manages the processing of object script files.



Description

The Script class is provided for the purpose of processing object scripts. This class specifically supports the Dynamic Markup Language (DML), but other script types can be supported through sub-classes. DML is the most common language used throughout the Athene system and the files can be identified by a ".dml" file extension. For a complete introduction on the DML scripting standard, you will need to refer to the DML Whitepaper for all necessary details.

To run an object script, you need to set the Location field and then Activate the Script object. If a particular object script supports arguments, you can set values for them via the SetUnlistedField action. Activating an object script will often cause a large amount of objects to be generated. If you need to find any of these objects, read the ObjectList field to retrieve a list of all objects that were created by the activation process.

Actions

The Script class supports the following actions:

Activate  Processes a Script.
ClosingTag  If a Script object is non-static, calling this action will cause it to self-destruct.
GetUnlistedField  Script arguments can be retrieved through this action.
OpeningTag  Activates a Script.
SetUnlistedField  Script arguments can be set through this action.

Structure

The Script object consists of the following public fields:

Cache  Enables caching for static scripts.
Flags  Optional flags.
Location  The location of the file that is to be processed as a script.
ObjectList  Lists all objects that have been created during the activation of a Script.
PrimaryObject  Identifies the primary object of a Script.
Procedure  Allows you to specify a procedure to be executed from within a script.
Repeat  This field can be used to activate a Script multiple times.
RepeatStart  Determines the index at which to start a Script's repetition process.
Static  Set to TRUE to make a Script object static.
String  May be set to a string to translate if the script data is not in a file.
Target  Defines the container that the Script objects will be initialised to.
TotalArgs  Reflects the total number of arguments used on a Script object.
TotalObjects  Reflects the total number of objects created during a Script's activation process.
Field:Cache
Short:Enables caching for static scripts.
Type:BOOLEAN
Status:Get/Set

By default, static scripts will reload their original script file each time that they are activated (assuming that the source file has changed). You can turn off this behaviour by setting the Cache option to TRUE. In cache mode, the script will load the source file once and will never check for changes to the original data source.

Caching does not apply in circumstances where the script source has originated from a string-based statement.


Field:Flags
Short:Optional flags.
Type:LONG
Prefix:SCF
Status:Read/Write

Optional flags supported by the Script class can be specified here. Currently available flags are listed in the following table:

FlagDescription
OBJECTLIST  If you would like an object list to be generated when a Script object is executed, you need to set this flag. By default object lists are not created during the activation process as they can slow the routine slightly.

Field:Location
Synonyms:Src
Short:The location of the file that is to be processed as a script.
Type:STRING
Status:Read/Write

The location of an object script file must be specified in this field prior to initialisation. If the field is not set then the initialisation process will fail.

Special parameters can also be passed to the script when setting the location. The name of an executable procedure may be passed by following the location with a semicolon, then the name of the procedure to execute. Arguments can also be passed to the script by following this with a second semicolon, then a sequence of arguments, each separated with a comma. The following string illustrates the format used:

  dir:location;procedure;arg1=val1,arg2,arg3=val2

A target for the script may be specified by using the 'target' argument in the parameter list (value must refer to a valid existing object).

Furthermore, the STRING: assignment is useful if you wish to pass a raw DML statement directly through this field. The following example illustrates valid formatting: "STRING:...script...".


Field:ObjectList
Short:Lists all objects that have been created during the activation of a Script.
Type:OBJECTID *
Status:Read

If you have set the OBJECTLIST Flag then you can read this field to retrieve a complete list of objects that were created during the activation of a Script. The list is a straight array of OBJECTID values and is terminated with a NULL value to indicate an end to the list. The OBJECTID's are listed in the original order of object creation.


Field:PrimaryObject
Short:Identifies the primary object of a Script.
Type:OBJECTID
Status:Read

Some object scripts will define a 'primary object' - an object which is considered to be the most important out of all the objects created by a script file. Many graphical scripts, such as "templates:window.dml", "templates:button.dml" and "templates:input.dml" will do this as a development aid. In DML, primary objects are defined with an asterisk just before a new object definition. For example:

   <*render width="140" height="60/>

The exact purpose of a primary object is for the developer of the script file to decide. In most cases the presence of a primary object will save you from having to trawl through an ObjectList to find a specific object created by a Script.


Field:Procedure
Short:Allows you to specify a procedure to be executed from within a script.
Type:STRING
Status:Get/Set

Sometimes scripts are split into several procedures or functions that can be executed independently from the 'main' area of the script. If a script that you have loaded contains procedures, you can set the Procedure field to execute a specific routine whenever the script is activated with the Activate action.

If this field is not set, the first procedure in the script, or the 'main' procedure (as defined by the script type) is executed by default.


Field:Repeat
Short:This field can be used to activate a Script multiple times.
Type:LONG
Status:Read/Write

If you want to execute an object script more than once, the quickest way to do it is to set the Repeat field. Simply set the field to the number of times that you would like to have the script file processed before calling the Activate action.


Field:RepeatStart
Short:Determines the index at which to start a Script's repetition process.
Type:LONG
Status:Read/Write

If you have set the Repeat field to execute an object script multiple times, the repetition count will start at zero and increment until it reaches the value specified in the Repeat field. If you want to start the count from a value other than zero, you can set this field to that index value. For instance, if you set the Repeat field to a value of 8 and the RepeatStart field to a value of 2, the Script will be processed 6 times.

Setting this field has a direct impact on the Index reference that can be used in object scripts (refer to the DML Whitepaper for information on repetition and indexes).


Field:Static
Short:Set to TRUE to make a Script object static.
Type:LONG
Status:Read/Init

By default, a Script object will execute itself and then self-destruct when a closing tag is received. If you would rather that the object stays in the system, set this field to TRUE. If you do this, the only way to get the Script object to process is to call the Activate action.


Field:String
Short:May be set to a string to translate if the script data is not in a file.
Type:STRING
Status:Get/Set

Field:Target
Short:Defines the container that the Script objects will be initialised to.
Type:OBJECTID
Status:Read/Init

This field should be set to refer to the container that you want the Script objects to be initialised to. If you do not set this field then the root-level objects in the Script will be initialised to the Script's personal container.


Field:TotalArgs
Short:Reflects the total number of arguments used on a Script object.
Type:LONG
Status:Read

The total number of arguments that have been set on a Script object through the unlisted field mechanism are reflected in the value of this field. If you have not set any arguments then the field value will be zero.


Field:TotalObjects
Short:Reflects the total number of objects created during a Script's activation process.
Type:LONG
Status:Read

If you set the OBJECTLIST Flag prior to a Script object's activation, this field will reflect the total number of objects created during the activation process. If you did not set the OBJECTLIST flag then this field will be set to zero.