Class Documentation
Action |
1.1 |
ID_ACTION |
Stable |
Command |
March 2003 |
Rocklyte Systems |
Rocklyte Systems (c) 1999-2003. All rights reserved. |
The action class is used to perform any action on a shared object. |
Description
The Action class allows you to execute actions and methods on other
objects in the system. It is specifically designed for use in scripts, such as
the Dynamic Markup Language. The Action class
is especially useful for executing generic actions such as Free,
Show, MoveToFront and Resize during the execution of a script. You may
also create static Action objects, which are useful for reacting to the
user's activity and other events in the system. Another useful feature
is action monitoring, which allows you to react to action calls made on
any object.
Executing an action requires that you state the name of the
action that you want to call and the object that is to receive it. Following
that, any arguments relevant to the type of action should be specified. It
is vital that you set all of the arguments related to the action, e.g. the
Resize action requires that three arguments are set. If you do not set all
of the required arguments, the default settings will be used, which may give
unexpected results. Here are some DML based examples:
<action call="Free" object="[myobject]"/>
<action call="Resize" object="[renderobject]" &width="100" &height="150" &depth="0"/>
<action static method="List" object="[container]"/>
This next example monitors an object and performs a reaction whenever it
is hidden. Note: When using action monitoring, the Action object will
automatically be made static.
<action monitor="[renderobject]" call="hide">
<...>
</action>
For a complete list of actions and their relevant arguments, you will
need to refer to the Action Reference Guide for more detailed
information.
Actions
The Action class supports the following actions:
Activate | Activates an Action object. |
ClosingTag | If the object is non-static, this action will cause the Action object to activate and then self-destruct. |
GetUnlistedField | This action is supported for retrieving unlisted field values. |
SetUnlistedField | Unlisted fields are supported for action and method argument values. |
Structure
The Action object consists of the following public fields:
Call | Set this field to specify the action that you want to call. |
Custom | The Custom field provides a customised action service. |
Error | Reflects the error code of the last executed action. |
Method | Set if you want to execute a method rather than an action. |
Monitor | If you want to monitor an object for activity, set this field. |
Object | Refers to the object that will receive the action. |
Static | Set to TRUE if the Action should be static. |
Field: | Call |
Short: | Set this field to specify the action that you want to call. |
Type: | STRING |
Status: | Read/Write |
This field (or the method field) must be set to determine the action that
will be executed or monitored by an action object. A list of valid action
names are provided in the manual describing the available system actions.
|
|
Field: | Custom |
Short: | The Custom field provides a customised action service. |
Type: | STRING |
Status: | Undefined |
The Custom field is used in circumstances where you want to execute a custom
action on an object, or to create a customised action for an
existing object. When setting the Custom field, you need to provide a unique
name that does not match any of the existing action names (it is recommended
that you steer clear of using generic terms such as 'Refresh'). If you set
the Custom field, you must not set it in conjunction with the Method or Call
fields, or you will lose your definition. Also, you may not pass your own
arguments via custom actions, although you may set the 'Number' argument
that accompanies the customised action standard.
|
|
Field: | Error [V] |
Short: | Reflects the error code of the last executed action. |
Type: | LONG |
Status: | Read |
When an Action object is activated, the Error field will be updated to
reflect the error code that was returned from that action or method.
A string describing the error code can be loaded from the
'system:config/error_messages.cfg' config file.
|
|
Field: | Method |
Short: | Set if you want to execute a method rather than an action. |
Type: | STRING |
Status: | Write |
If a method should be executed rather than an action, set this field
to the name of the method that you want to execute. If the method requires
that a certain number of arguments need to be set, you must also set those
arguments via the unlisted field mechanism, to ensure that the method call
is legal.
|
|
Field: | Monitor |
Short: | If you want to monitor an object for activity, set this field. |
Type: | OBJECTID |
Status: | Read/Write |
By setting the Monitor field to an existing ObjectID, your action object
will only react when the monitored object completes a specific action.
Because monitoring requires that the action object is static, setting the
Monitor field will automatically ensure that the action object is not
freed during script execution.
In the following example, action monitoring is used to react to an
object when it is freed:
<action monitor="[myobject]" call="free"/>
<action static call="hide" object="[{name}]"/>
</action>
The action is only reported if it succeeds on execution. If you want to
enable reporting of failed actions, you need to set the ACCEPTERRORS flag.
|
|
Field: | Object |
Short: | Refers to the object that will receive the action. |
Type: | STRING/OBJECTID |
Status: | Read/Write |
The object that is to receive the action call must be specified in this
field. You are required to set this field unless you intend to use action
monitoring, in which case you should set the Monitor field.
If you set this field with a string, the object reference will be
translated to an ID in run-time.
|
|
Field: | Static |
Short: | Set to TRUE if the Action should be static. |
Type: | BOOLEAN |
Status: | Read/Write |
By default, an Action object will execute itself and then self-destruct
when the 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 Action object to perform is to call the Activate() action.
|
|