February 14, 1995Defined in Rule.Def
Inherits from RuleAction
Rule actions connect rules with their effects: the action defines what happens when the rule takes effect. Class LocalRuleAction is the most commonly used of the subclasses of class RuleAction.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Instantiate: often Subclass: rarely Call its methods: rarely
You will probably never create an object of class LocalRuleAction programmatically. Instead, you will put rule action objects into place in your object definition files. You might subclass and override some of class LocalRuleAction's methods, but you're more likely to subclass RuleAction instead.
Class LocalRuleAction defines the following methods:
| Method | Description |
|---|---|
| PerformRule | Carry out the action specified by the rule |
| ComputeRuleText | Create the text description of the rule |
Class LocalRuleAction defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| ActionObject | Object | The getter for the actionObject field |
| ActionData | Unsigned | The getter for the actionData field |
Class LocalRuleAction defines the following fields
| Field | Type | Description |
|---|---|---|
| actionType | Unsigned | The rule action type |
| actionObject | Object | The object to act upon |
| actionData | Unsigned | Additional information about the rule action (the meaning of which depends on the action type) |
Here's a typical local rule action object:
Instance LocalRuleAction 19;
actionType: 7; // actionDoOperation
actionObject: iOutBoxStack;
actionData: operation_AddToSendQueue;
End Instance;
This rule action uses the action type actionDoOperation. It calls the operation specified in the actionData field, AddToSendQueue, on the the action object, the out box stack.
Class LocalRuleAction uses some predefined constants in its actionType field. The method PerformRule relies on these constants to determine how to carry out the rule's action. The method ComputeRuleText also uses these contants. These constants are defined in Utilities.h. If you need a rule action that doesn't fit one of these action types, you should subclass LocalRuleAction and override the PerformRule method.
The descriptions in this section refer to the two parameters of PerformRule: the contextObject parameter (called the trigger data) and the rule parameter. The action object is obtained from the action object field of the rule action. The action data is obtained form the action data field.
#define actionPlaySound 1
Use this action type to play the action object as a sound.
#define actionPutInContainer 2
Use this action type to file the trigger data in the folder or gadget specified by the action object. The context object must be a card.
#define actionSetAttribute 3
Use this action type to set an attribute of the action object. The action data specifies the number of the attribute to set. The contextObject parameter specifies the value to set the attribute to.
If the rule's sceneAttribute flag is set, this action type will set the given attribute of the current scene to the value given by the action object. So the action object is the attribute value instead of the object whose attribute is being set. (Yes, this reeks of hack to your intrepid writer, too.)
#define actionPostAnnouncement 4
Use this action type to make announcements when your rule is triggered The action object is the text for the announcement iRuleAnnouncement. PerformRule will set up the announcement text and make the announcement.
#define actionPostAnimation 5
This action type is reserved by the system. Please don't use it.
#define actionPostTaskAnnouncement 6
Use this action type to announce task alarms. PerformRule calls PostTaskAnnouncement on the trigger data. You probably won't use this action type unless you're implementing the datebook.
#define actionDoOperation 7
Use this action type to call a specific operation on the action object. PerformRule will call OperationByNumber on the action object, using actionData as the operation number and contextObject as the data.
#define actionDeleteOld 8
Use this action type for rules that purge old objects from containers like the filing cabinet or the datebook. PerformRule calls DeleteOldItems on the action object, passing the action data as the timeRangeIndex parameter. You might use this action type if you're implementing something that will contain many date-stamped items.
#define actionDoIntrinsicOperation 9
Use this action type to call an intrinsic operation. The action data specifies the intrinsic operation number. If the rule's intrinsicUseActionObj flag is set, PerformRule will call IntrinsicByNumber using the action object as the value to pass to the intrinsic operation. Otherwise, PerformRule will use the context object as the value.
#define actionSetMax 10
Use this action type to set a new maximum value for a control object. Your action object must be a control. PerformRule calls SetMax on the action object, using actionData as new maximum value.
#define actionPlaySoundFor 11
Use this action type to play the action object as a sound. The sound will repeat until the duration specified in the action data has passed.
Call: rarely Override: sometimes
The system calls PerformRule to carry out the action of a rule that's been triggered and qualified.
PerformRule switches on the rule action type. See the table in the section on LocalRuleAction Action Types earlier in this chapter for a list of the types and the corresponding actions carried out by PerformRule. If you need a rule with an action different from the ones defined by class LocalRuleAction, create a custom subclass of class RuleAction.
Call: sometimes Override: rarely
The system calls ComputeRuleText while updating a rule's text for display in a rule view. It calls this method from Rule_UpdateText, immediately after calling ComputeRuleText on the rule's qualifier. ComputeRuleText uses the rule's action type to replace lines in the text mapping object with the appropriate text. LocalRuleAction_ComputeRuleText only determines the text for the action portion of the rule text. ComputeRuleText doesn't actually change the rule description directly. It changes the mapping, which UpdateText then uses to make the rule description.
For details on how the system maps rule text, see the chapter on class RuleTemplate.