Book Contents          Previous Chapter          Next Chapter

Rules

This chapter describes how to make and use rules, user interface objects that let users set policies and change preferences for the behavior of Magic Cap features. Before reading this chapter, you should be familiar with scenes.

About Rules

Rules allow users to customize the behavior of objects in various parts of Magic Cap. For example, the user can set rules in the in box that determine when mail should be collected automatically and what to do when mail is received that matches particular criteria. Magic Cap defines class Rule to represent rules.

Each scene can implement its own rules. To add your own rules to a scene, you'll specify information in the scene's scene additions object in the instance definition file. For more information on how to specify a scene additions object, see the Scene Additions section of this book's Scenes chapter.

When you create rules, you'll specify the rules and their related objects in your instance definition file. Each rule refers to several other objects that provide information about it:

You won't often call operations of these classes when you use rules. Instead, you'll just specify the appropriate objects in your instance definition file.

Creating Rules

When you create rules for your packages, you'll specify the rule object and related objects in your instance definition file. The rule has several fields that you must set up, which are described in this section.

Several fields of the rule refer to related objects. These fields are ruleTemplate, ruleTrigger, ruleAction, and ruleQualifier. See the sections below for more information about these objects.

The rule's description field refers to a text object containing the text of the rule. This is the text that appears to the user in the rules window.

The ruleFlags field contains various flags that affect the operation of the rule. For example, the isEnabledMask flag controls whether the rule is turned on or off by default, and the ruleNoCopyMask flag prevents the user from making a copy of the rule. For a complete description of rule flags, see the Rule chapter in Magic Cap Class and Method Reference. It rules.

Triggering Rules

Every rule has a trigger, an event that indicates when the rule should be invoked. Your rules will probably use triggers from a list of system triggers defined by Magic Cap. Each system trigger is associated with a list of rules. When the action associated with a particular system trigger takes place, the rules using that trigger are invoked. For example, iMessageArrivedTrigger is invoked when a new telecard arrives in the in box, and iEmptyTrashTrigger is invoked when an object in the trash is deleted. See the Rule chapter in Magic Cap Class and Method Reference for a complete list of system triggers.

You can add a rule to a trigger's list by calling AddTo on the trigger when the rule is set up, as in this example:

AddTo(iMessageArrivedTrigger, newMsgRule);

Rule Actions

Every rule refers to a rule action, described by an object of class RuleAction. The rule action determines what happens when the rule is triggered. You won't create or use any objects of class RuleAction, because several of its operations are empty. Instead, you'll use objects of subclasses of RuleAction, such as LocalRuleAction.

Class LocalRuleAction defines several common actions you can specify for your rule. For example, you can use this class if your rule plays a sound, moves an object into a folder or gadget, or displays a public address announcement. For a complete description of actions supported by this class, see the LocalRuleAction chapter in Magic Cap Class and Method Reference.

If you want your rule to perform some action that isn't defined by class LocalRuleAction or another subclass, you can create your own subclass of RuleAction. When you create your own class of rule action, you must override operations PerformRule and ComputeRuleText. Your overridden version of PerformRule should define the action you want the rule to take when triggered. Your overridden version of ComputeRuleText should determine the text that the rule should contain when it appears in the rules window.

Rule Qualifiers

Every rule refers to a rule qualifier, described by an object of class RuleQualifier. The rule qualifier specifies a condition that must be met before the action will be taken. You won't create or use any objects of class RuleQualifier, because several of its operations are empty. Instead, you'll use objects of subclasses of RuleQualifier, such as LocalRuleQualifier.

Class LocalRuleQualifier defines several common qualifiers you can specify for your rule. For example, you can use this class if your rule tests whether a telecard has been received from a particular correspondent, whether a connection has been made using a particular communication stream, or whether a particular list object contains more than a given number of items. For a complete description of qualifiers supported by this class, see the LocalRuleQualifier chapter in Magic Cap Class and Method Reference.

If you want your rule to use some qualifier that isn't defined by class LocalRuleQualifier or another subclass, you can create your own subclass of RuleQualifier. When you create your own class of rule qualifier, you must override operations QualifyRule and ComputeRuleText. Your overridden version of QualifyRule should define the test your rule performs to determine if it should take action. Your overridden version of ComputeRuleText should determine the text that the rule should contain when it appears in the rules window.

Rule Templates

If your rule can be edited by the user, rather than simply turned on and off, it must refer to a rule template, described by an object of class RuleTemplate. The rule template describes the rule in its basic, unedited form. You won't create rule templates programatically. Instead you'll include them in your instance definition file.

The rule template includes a number of fields that specify how the rule should appear and act. The template's description field refers to the default text description of the rule. The controlList field refers to a list of controls used for editing the rule. Magic Cap uses the text mapping defined by the mapping field to place text into the editable parts of the rule. The numQualifierControls indicates how many of the rule's controls are used to test whether the rule should be triggered, rather than to edit the rule.

If your rule can't be edited by the user, its ruleTemplate field should be set to nilObject.

Reference

For more information, see the following topics in Magic Cap Class and Method Reference:

class Rule

fields:

description
ruleAction
ruleFlags
ruleQualifier
ruleTemplate
ruleTrigger

class RuleAction

operations and attributes:

ComputeRuleText
PerformRule

class LocalRuleAction

class RuleQualifier

operations and attributes:

ComputeRuleText
QualifyRule

class LocalRuleQualifier

operations and attributes:

PerformRule

class RuleTemplate

fields:

controlList
description
mapping
numQualifierControls


Book Contents          Previous Chapter          Next Chapter