Inherits from Rule
Rule templates describe the pieces of rules that can be edited. They map editable pieces to the editing controls. They also customize an editable rule's text.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
The chapter on class Rule is the best place to start learning about rules. You will also find the chapters on classes LocalRuleAction and LocalRuleQualifier helpful. Documentation for class TextMapping doesn't exist yet, but the comments in the class definition file will be helpful.
Instantiate: sometimes Subclass: rarely Call its methods: rarely
You will probably never create an object of class RuleTemplate programmatically or call any of its methods. Instead you'll put rule template objects in your object definition files. See the discussion following the list of class RuleTemplate's fields for details on creating your own templates.
Class RuleTemplate defines the following methods:
| Method | Description |
|---|---|
| ControlList | Overridden to return the template's control list |
| TextMatchesTemplate | Check if this template's text matches the provided rule text; called by the system to compare cloud rules to Magic Cap rules |
Class RuleTemplate defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from Rule | ||
| ruleFlags | Unsigned | Not used by rule templates |
| ruleTemplate | Object | Not used by rule templates |
| ruleTrigger | Object | Not used by rule templates |
| description | Object | The text description of the rule, with editable pieces delineated by / |
| ruleAction | RuleAction | Not used by rule templates |
| ruleQualifier | RuleQualifier | Not used by rule templates |
| Defined by RuleTemplate | ||
| controlList | Object | A list of the controls used to edit this rule |
| mapping | Object | The text mapping object to use with this template |
| numQualifierControls | Unsigned | The number of controls in the control list that are qualifier controls instead of action controls |
The mapping field should point to a text mapping object. The system provides a standard rule text mapping object, which you can refer to using the indexical iRuleTextMapping. Text mapping methods like LocalRuleAction_ComputeRuleText assume you're using this mapping. See the section on Rule Template Text Mappings later in this chapter for details on how rule text is mapped.
The controlList field should point to an object list containing all the controls needed to edit your rule.
Set the numQualifierControls field to be the number of editable qualifiers in your rule. If the numQualifierControls field is n, the first n controls correspond to qualifier mappings. The settings of those controls are mapped to rule text by class LocalRuleQualifier's ComputeRuleText method. The remaining controls correspond to action mappings. Their settings are mapped to rule text by class LocalRuleAction's ComputeRuleText method.
If the control is a qualifier control, set its target this way:
If the control is an action control, set its target this way:
Editable rules can have only two editable pieces, a qualifier piece and an action piece.
Here's an example of a rule template object and its supporting objects:
Instance RuleTemplate 31;
ruleFlags: 0x80000000;
ruleTemplate: nilObject;
ruleTrigger: nilObject;
description: (Text 33);
ruleAction: nilObject;
ruleQualifier: nilObject;
controlList: (ObjectList 34);
mapping: iRuleTextMapping;
numQualifierControls: 1;
End Instance;
Instance Text 33; // template text
text: 'Send everything in the out box as' \
'soon as it contains at least ' \
'/number/ item(s).';
End Instance;
Instance ObjectList 34; // template controls
length: 1;
entry: (Meter 'number of items' 36);
End Instance;
Instance Meter 'number of items' 36;
// meter definition goes here (elided for brevity)
End Instance;
This rule template describes how to edit a rule with one editable piece: the qualifier that specifies how many messages should be in the out box. The control list has just one control in it, the meter that edits the qualifier. The system will map the string `/number/' in the template text to the number the user chooses, using the standard rule text mapping.
When the user tap this rule to edit it, he sees the rule displayed this way:
The editable portions of the rule are underlined in the rule text. Notice that the only connection made between the control and the editable portion of the rule is the name of the control. Be sure to give your controls names that clearly connect them with the rule bits they edit.
Here's an example of a rule template with two controls:
Instance RuleTemplate 100;
ruleFlags: 0x80000000;
ruleTemplate: nilObject;
ruleTrigger: nilObject;
description: (Text 101);
ruleAction: nilObject;
ruleQualifier: nilObject;
controlList: (ObjectList 102);
mapping: iRuleTextMapping;
numQualifierControls: 1;
End Instance;
Instance Text 101;
text: 'When a message from /person/ arrives,'\
'play the /sound/ sound.';
End Instance;
Instance ObjectList 102;
length: 2;
entry: (Button 'choose person' 103);
entry: (ChoiceBox 'Select sound' 104);
End Instance;
The numQualifierControl field contains 1. So the first control in the control list is a qualifier control. It should correspond with the rule's qualifier type. The second control corresponds with the rule's action.
Here are the other pieces of this rule:
Instance ConditionalRule 3167;
ruleFlags: 0x00000000;
ruleTemplate: (RuleTemplate 3163);
ruleTrigger: iMessageArrivedTrigger;
description: (Text 3168);
ruleAction: (LocalRuleAction 7473);
ruleQualifier: (LocalRuleQualifier 7474);
condition: iCanCollectCondition;
End Instance;
Instance LocalRuleAction 7473;
actionType: 1;
actionObject: iSwallowSound;
actionData: 0;
End Instance;
Instance LocalRuleQualifier 7474;
qualifierType: 1;
qualifierObject: (ProviderAddressCard 874);
qualifierData: 0;
End Instance;
Instance Text 3168;
text: 'When a message from General Magic '\
'arrives, play the Shlurp sound.';
End Instance;
The action object and the qualifier object are pre-set to the rule's defaults.
The `choose person' button is a scripted button that pops up an edit window that helps the user pick a person. The choice box is a standard control. Here's the choice box's object definition:
Instance ChoiceBox 'Select sound' 3191;
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <0.0,-12.0>;
contentSize: <160.0,27.0>;
viewFlags: 0x10181000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: 0xFF333333;
shadow: nilObject;
sound: iTouchSound;
border: iBorderBlack1;
image: nilObject;
textStyle: iBook14;
controlFlags: 0x35008000;
level: 0.0;
min: 1.0;
max: 12.0;
target: iCurrentRuleAction;
targetAttribute: operation_ActionObject;
upDownImages: iChoiceBoxRightArrow;
choices: iSoundChoiceList;
choiceFlags: 0x08800000;
End Instance;
Note that the target of the choice box is iCurrentRuleAction and the target attribute is operation_ActionObject.
When the user edits this rule, he sees it displayed this way:
If your rule uses the standard qualifier and action types, you can use Magic Cap's predefined rule text mapping object, iRuleTextMapping, to map your template text. Mark the editable portion of your template text with mapping names that correspond to the matching qualifier or action types. Here are the mappings handled by the predefined rules classes:
| Mapping | Action or Qualifier type |
|---|---|
| /sound/ | Action types actionPlaySound and actionPlaySoundFor |
| /person/ | Qualifier types qualifySender and qualifyCaller |
| /attribute/ | Action type actionSetAttribute and qualifier type qualifierMailAttribute |
| /folder name/ | Action type actionPutInContainer |
| /folder type/ | Action type actionPutInContainer |
| /stamp name/ | Qualifier type qualifyMatchViewable |
| /announcement/ | Action type actionPostAnnouncement |
| /animation/ | Obsolete |
| /find text/ | Qualifier type qualifyMatchText |
| /operation/ | Action types actionDoOperation and actionDoIntrinsicOperation |
| /time range/ | Action type actionDeleteOld |
| /device/ | Qualifier type qualifyConnected |
| /number/ | Action type actionSetMax and qualifier type qualifyStackCount |
| /service/ | Action types actionDoOperation and actionDoIntrinsicOperation |
| /hour/ | Action type actionDoOperation (for ScheduledRules) |
Here is iRuleTextMapping's object definition:
Instance TextMapping 105; // iRuleTextMapping
keyText: (Text 106);
valueText: (Text 107);
End Instance;
Instance Text 106;
text: 'sound\nperson\nattribute\nfolder name\n' \
'folder type\nstamp name\n' \
'announcement\nanimation\nfind text\n' \
'operation\ntime range\ndevice\n' \
'number\nservice\nhour\nDL scope\n';
End Instance;
Instance Text 107;
End Instance;
Each of the slots in the text mapping corresponds to one of the qualifier and action types. (Unfortunately, the mapping numbers aren't the same as the rule action type numbers. You won't need to use the mapping numbers yourself unless you're subclassing LocalRuleAction or LocalRuleQualifier to override ComputeRuleText, though. The mapping numbers are just the line numbers for each slot.)
Rule_UpdateText creates a text description for a rule using the rule's template. It calls ComputeRuleText on the rule's qualifier and on its action. The two ComputeRuleText methods replace the appropriate piece of the mapping object with text they compute using the qualifier and action types. For example, LocalRuleAction_ComputeRuleText calls SetLine to replace the correct line in the mapping with the name of the rule action object, or with some other appropriate text determined using the action object. The system then calls TextMapping_MapAndMarkText to retrieve the new text from the mapping object and replace the matching sections of the template text.
Here's the template text object for the example earlier in this chapter:
Instance Text 3164;
text: 'When a message from /person/ arrives,'\
'play the /sound/ sound.';
End Instance;
The "/sound/" portion of this text is the piece that depends on the rule's action object. The action object is:
Instance LocalRuleAction 7473;
actionType: 1;
actionObject: iSwallowSound;
actionData: 0;
End Instance;
When this rule's text is mapped, LocalRuleAction_ComputeRuleText would replace the "sound" slot of the text mapping. ComputeRuleText replaces the first line of the text mapping with the name of the action object, which in this case would be "Shlurp."
After the qualifier and action objects have both had a chance to modify the text mapping, Rule_UpdateText calls MapAndMarkText to turn the template text and the mapping object into the finished rule description. The editable portions of the rule will be underlined when the rule is displayed.
For more information on text mappings, see class TextMapping. (Unfortunately, this class has not yet been documented.)