Legacy Document

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

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

/ Specifying Events

<On Panel Show>

You can use the <On Panel Show> command to define an event function that Apple Guide executes when opening a panel and when expanding a panel.

<On Panel Show> eventFunction [, firstOrAlways]

eventFunction

An event function or event list.

firstOrAlways

A constant that indicates whether Apple Guide should execute the event function only when it first shows the panel (FIRST) or both when it first shows the panel and whenever the panel is expanded (ALWAYS). This parameter is optional. If you omit this parameter, Apple Guide uses ALWAYS as the default.

DESCRIPTION

The <On Panel Show> command defines an event function or event list for a panel. Apple Guide executes the event function, based on the firstOrAlways parameter, when Apple Guide shows or expands the panel to which it is attached. Event functions are usually used to send an Apple event to a target application, requesting it to perform some action.

You can use multiple <On Panel Show> commands per panel. Apple Guide executes event functions in the order in which the <On Panel Show> command appears in your panel definition.

You typically use the <On Panel Show> command to perform a task that is required by a Continue panel. One of the parameters to the <Make Sure> command is the sequence to display if the specified condition isn't true. In this case, Apple Guide displays the sequence, showing the first panel in the sequence. If you include an <On Panel Show> command in this panel definition, Apple Guide executes the specified event function. This event function should perform the task for the user.

EXAMPLES

#simple panel that plays a sound when opened or expanded
<Define Panel> "Example Panel"
   #always play a sound when panel is opened and also
   # when it is expanded
   <On Panel Show> PlaySound(1000), ALWAYS
<End Panel>
#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 Guide Maker's built-in event functions, see "Built-in Event Functions" on page 10-188. For information on the <Define Event> and <Define Event List> commands, see page 10-178 and page 10-181, respectively. For information on the <Make Sure> command, see page 10-162.