Legacy Document

Important: The information in this document is obsolete and should not be used for new development.

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

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

<Make Sure>
You can use the <Make Sure> command to specify a condition that must be true in order for the next panel to be displayed and to specify a sequence to display (the sequence to display is referred to as an Oops or Continue sequence) if the condition isn't true.
<Make 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 if the condition evaluates to FALSE.

DESCRIPTION
You can use the <Make Sure> command to specify conditional display of the panel specified in the <Panel> command that follows it. Apple Guide displays the panel only if the condition evaluates to TRUE. Apple Guide displays the specified sequence if the condition evaluates to FALSE.
If the condition is false, the sequence Apple Guide displays is referred to as an Oops sequence (if the sequence instructs the user to correct the problem) or a Continue sequence (if the sequence performs the task for the user). Note that Apple Guide does not display the sequence title of an Oops or Continue sequence. Instead, Apple Guide displays the main sequence title as the Oops or Continue sequence title.
Oops sequences should follow special rules. An Oops sequence should generally consist of one panel, giving the user information on how to correct the problem. Use a tag and indented body format for panels in an Oops sequence. Use the tag "Oops" or its localized equivalent. You should also provide an OK button centered under the panel text. You should provide a function that, when the user clicks the OK button in a panel of an Oops sequence, either returns the user to a previous panel giving instructions on how to correct the problem, or closes the Oops sequence and returns the user to the next panel in the original sequence. You can use the GoBack event function to do this.
Continue sequences should also follow special rules. A Continue sequence should consist of one panel, telling the user that Apple Guide is performing the task for them. Use the full format for panel text and provide a Continue button centered under the panel text. To perform the task for the user, your panel definition typically includes an <On Panel Show> command. When Apple Guide displays a Continue panel with this command, it executes the specified event function, which should perform the task for the user. For example, an event function might send one or more Apple events to direct the target application to accomplish the task. You should also provide a function that closes the Continue sequence and returns the user to the next panel in the original sequence when the user clicks the Continue button in a panel of a Continue sequence. You can use the GoBack event function to do this.
This is the general structure of conditional display of a panel using the <Make Sure> command:
   <Make Sure> condition, oopsOrContinueSequenceName
   #(if condition is false,
   # display the oopsOrContinueSequenceName sequence)
   # if condition is true, display this panel 
      <Panel> "show panel if condition true"
   #continue with other commands
   #always show this panel
   <Panel> "example panel"
You typically use the <Make Sure> command to ensure that a particular condition is true before allowing the user to continue. You define an Oops sequence to guide the user toward correcting the problem and a Continue sequence if you can perform the task for the user. For example, if a panel requires that a particular window be open, you can use a <Make Sure> command with a condition function that tests whether the window is open. If so, 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 <Make Sure> command applies only to the next panel in the sequence (however, the GoBack function may update the condition, as explained in the following paragraphs). You can combine <Make Sure> and <Skip If> commands and apply them to a single panel. You should not compound functions in the condition parameter for the <Make Sure> command. Instead, if needed you can apply several <Make Sure> conditions, each with their own Oops or Continue sequence, to a single panel.
To apply a Make Sure condition to several panels, use the <Start Making Sure> and <End Making Sure> commands.
When the user clicks a navigation arrow to move to the next panel and the next panel is preceded by a <Make Sure> command, Apple Guide checks the condition associated with the <Make Sure> command before displaying the next panel. If the condition is false, Apple Guide displays the associated Oops or Continue sequence. If you use the GoBack event function, when the user clicks OK in the Oops sequence or Continue in the Continue sequence the GoBack function determines whether the condition has been met. If so, the GoBack function returns the user to the next panel in the original sequence. If the condition has not been met, then the GoBack function works backwards from the original panel until it finds a panel that it can show.
For example, consider a sequence that contains these statements:
   <Panel> "first panel"
   <Make Sure> condition1, oopsSequenceName
   # if condition1 is true, display this panel 
      <Panel> "show panel if condition true"
   #continue with other commands
   <Panel> "some panel"
   <Make Sure> condition2, oops2SequenceName
   # if condition2 is true, display this panel 
      <Panel> "example panel"
If the condition specified by condition1 is true, Apple Guide displays the following panel and other panels as the user navigates through them. If the user is viewing the panel named "some panel" in this example and then clicks the right arrow to navigate to the panel named "example panel", Apple Guide evaluates the condition specified by condition2. If the condition is true, Apple Guide displays the next panel ("example panel"). If the condition isn't true, Apple Guide displays the sequence named oops2SequenceName and allows the user to correct the problem. If the user fixes the problem and then clicks OK, the GoBack function proceeds to the next panel ("example panel"). If the user clicks OK but has not fixed the problem, the GoBack function returns to "some panel".
The Oops sequence should tell the user how to correct the problem associated with the condition. Apple Guide hides the current panel while the Oops sequence is displayed. Once the user satisfies the condition specified in the <Make Sure> command, you can close the Oops sequence and return to the original sequence (the panel following the <Make Sure> command).
The Continue sequence should inform the user that Apple Guide is performing the task for the user. Note that if the user clicks the Continue button before the task completes, Apple Guide may return the user to a previous panel rather than the next panel in the sequence. Thus, your Continue panel should always instruct the user to wait until the task completes before clicking the Continue button. Once the task is complete and the user clicks Continue, you can close the Continue sequence and return to the original sequence (the panel following the <Make Sure> command).
The file Standard Setup is provided with Guide Maker. This file defines the GoBack function. If you include the Standard Setup file in your build file, you can automatically use the GoBack function as needed in your source files.
The Standard Setup file also defines various context checks (such as OpenWindow, InSystemFolder, and ControlPanelWinActive) that you can use to specify a condition in the <Make Sure> command (and also in the <If>, <Skip If>, and <Start Making Sure> commands).

SPECIAL CONSIDERATIONS
You cannot apply a <Make Sure> condition to the first panel in a <Jump> sequence. For this reason, be careful when applying <Skip If> and <Make Sure> commands to introductory panels because the restriction on the <Make Sure> command applies to any panel that may appear first.
If you specify more than one <Make Sure> command for a panel, Apple Guide evaluates the conditions in the reverse order from the way they appear in your source file. That is, the <Make Sure> command closest to the <Panel> command is evaluated first.

EXAMPLES
#sequence definition for an Oops sequence
<Define Sequence> "instruct user to open dictionary"
   <Sequence Prompt Set> NONE
   <Define Panel> "Oops panel: Open dictionary"
      <Format> "OopsTag"   #a defined format
               Oops
      <Format> "OopsText" #a defined format
               You need to open the SurfWriter Dictionary.
               Click OK for instructions (or open the
               dictionary, then click OK).
      <Standard Button> "OK", Center, GoBack()
   <End Panel>
<End Sequence>
#sequence definition that uses <Make Sure> and Oops
<Define Sequence> "How do I use the dictionary?"
   <Panel> "intro to dictionary"
   #now make sure that the dictionary file is open before
   # allowing the user to go to the next panel;
   # if it isn't open, tell the user how to open it
   # by providing an Oops sequence
   #(isDictionaryOpen is application-defined context check)
   <Make Sure> isDictionaryOpen("SurfWriter Dictionary"),
            "instruct user to open dictionary" #oops seq.
      <Panel> "finding a word in the dictionary"
   <Panel> "special dictionaries"
<End Sequence>
#sequence definition for a Continue sequence
<Define Sequence> "open dictionary for the user"
   <Seq Nav Button Set> NONE
   <Define Panel> "Continue panel: Opening dictionary"
      <Format> "Full"      #a defined format
      Please wait a moment. Apple Guide is assisting you by 
      opening the SurfWriter dictionary.

      #this 3D button (Continue) is in Standard Resources
      <3D Button> 1070, 1072, Center, GoBack()
      #use prompt text: "Wait until the dictionary is open,
      # then click Continue."
      <Panel Prompt> "Wait while AG opens dictionary"
      #specify event function that Apple Guide executes
      # upon showing the panel; specify your own event
      # function or a built-in event function
      <On Panel Show> DoScript("openSWDictionary")
   <End Panel>
<End Sequence>  
#sequence definition that uses <Make Sure> and Continue
<Define Sequence> "How do I use the dictionary?"
   <Panel> "intro to dictionary"
   #now make sure that the dictionary file is open before
   # allowing the user to go to the next panel;
   # if it isn't open, open it for the user
   # by providing a Continue sequence
   #(isDictionaryOpen is application-defined context check)
   <Make Sure> isDictionaryOpen("SurfWriter Dictionary"),
            "open dictionary for the user" #continue seq.
   <Panel> "finding a word in the dictionary"
   <Panel> "special dictionaries"
<End Sequence>
SEE ALSO
For information on the <Define Context Check>, <Define Event>, and <On Panel Show> commands, see page 10-172, page 10-178, and page 10-185.

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.