Class Documentation
Script |
1.0 |
ID_SCRIPT |
Unspecified |
FileSystem |
May 2001 |
Rocklyte Systems |
Rocklyte Systems (c) 2000-2001. All rights reserved. |
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:
Structure
The Script object consists of the following public fields:
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. |
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. |
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: | 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:
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.
|
|
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: | 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: | 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.
|
|