Class Documentation

Name:Action
Version:1.1
ID:ID_ACTION
Status:Stable
Category:Command
Date:March 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 1999-2003. All rights reserved.
Short:  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>

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.