Legacy Document

Inside Macintosh: Apple Guide Complete / Part 4 - Scripting Guide Files

Chapter 10 - Guide Script Command Reference / Guide Script Command Descriptions

/ Specifying Conditional Execution

<Start Making Sure>

You can use the <Start Making Sure> command to specify a condition that must be true for all panels preceding the next <End Making Sure> command in order for each panel to be displayed. Like the <Make Sure> command, you also specify an Oops or Continue sequence to display if the condition isn't true.

<Start Making Sure> condition, oopsOrContinueSequenceName

condition

A condition function, either single or compound, that returns a Boolean value. Guide Script provides several built-in condition functions, such as radioButtonState and checkBoxState. You can also define your own condition functions using the <Define Context Check> command.

oopsOrContinueSequenceName

A text string specifying the sequence name of the sequence to display.

DESCRIPTION

You can use the <Start Making Sure> command to specify conditional display of all panels that precede the next <End Making Sure> command. Apple Guide displays a panel only if the condition evaluates to TRUE. Apple Guide displays the specified sequence if the condition evaluates to FALSE.

This is the general structure of conditional display of a panel using the <Make Sure> command:

   #specify a condition that must be true for all panels
   # between <Start Making Sure> and <End Making Sure>
   <Start Making Sure> condition, oopsOrContinueSequenceName
   #for each panel, display the panel if the condition is true 
   (if condition is false, display oopsOrContinueSequenceName seq.)
      <Panel> "show panel 1 if condition true"
      <Panel> "show panel 2 if condition still true"
      <Panel> "show panel 3 if condition still true"
   <End Making Sure>
   #always show this panel 
   <Panel> "example panel"

You typically use the <Start Making Sure> command to ensure that a particular condition is true for a series of panels. You define an Oops sequence to guide the user toward correcting the problem before allowing the user to continue. You define a Continue sequence to perform the task for the user. For example, if all panels in a series require that a particular window remain open, you can use a <Start Making Sure> command with a condition function that tests whether the window is open. If it is, the user can continue with the next panel. Otherwise, you can either provide an Oops sequence that instructs the user to open the window before continuing or provide a Continue sequence that opens the window for the user.

The <Start Making Sure> command applies to all panels preceding an <End Making Sure> command. You can also apply <Make Sure>, <If>, and <Skip If> commands to any panel in the sequence. You should not compound functions in the condition parameter for the <Start Making Sure> command. Instead, if needed you can apply several <Start Making Sure> conditions, each with their own Oops or Continue sequence, to a single panel.

Apple Guide continues to update conditions specified in <Start Making Sure> commands as the user moves through a sequence.

Apple Guide hides the current panel while the Oops or Continue sequence is displayed. Once the condition specified in the <Start Making Sure> command is performed and the user clicks OK or Continue, you can close the Oops or Continue sequence and return the user to the original sequence (the panel following the <Make Sure> command).

SPECIAL CONSIDERATIONS

You cannot apply a <Start Making Sure> condition to the first panel in a <Jump> sequence. Be careful when applying <Skip If> commands and <Start Making Sure> commands to introductory panels; the restriction on the <Start Making Sure> command applies to any panel that may appear first.

A <Start Making Sure> command must always be matched by a following <End Making Sure> command.

If you specify a series of commands that includes a <Start Making Sure> command, a <Jump Sequence> command, and an <End Making Sure> command, the <Start Making Sure> condition will not apply to any panels referenced through the <Jump Sequence> command.

EXAMPLES

<Define Sequence> "How do I use the dictionary?"
   <Panel> "intro to dictionary"
   #specify a condition that must be true for all panels
   # between <Start Making Sure> and <End Making Sure>
   #(isDictionaryOpen is an application-defined context check)
   <Start Making Sure> isDictionaryOpen("SurfWriter Dictionary"),
                     "instruct user to open dictionary" #oops
      <Panel> "finding a word in the dictionary"
      <Panel> "finding synonyms in the dictionary"
      <Panel> "getting a list of adverbs from the dictionary"
   <End Making Sure>
<End Sequence>

SEE ALSO

For information on the <Define Context Check> command, see page 10-172.