Legacy Document

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

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

/ Specifying Events

<Define Event>

You can use the <Define Event> command to define an event function for use with the following commands: <Standard Button>, <3D Button>, <Define Nav Button>, <Hot Text>, <Hot Rectangle>, <Hot Object>, <On Panel Create>, <On Panel Destroy>, <On Panel Show>, and <On Panel Hide>.

<Define Event> eventName, targetApp, eventClass, eventID
               [, IOPTData] [, optKey] [, optData]

eventName

A text string specifying the name of this event function.

targetApp

A four-character sequence specifying the signature of the target application or the constant FRONT. You can use the constant FRONT to specify the frontmost application. You can use the signature 's***' to send an Apple event to Apple Guide.

eventClass

A four-character sequence that identifies the event class.

eventID

A four-character sequence that identifies the event ID.

IOPTData

A short integer that provides data for the 'IOPT' keyword. This parameter is optional. If you provide it, Guide Maker adds to the Apple event a parameter whose keyword is 'IOPT' and whose data contains the value you specify in the IOPTData parameter.

optKey

A four-character sequence that identifies an additional keyword for the event. This parameter is optional.

optData

A string providing additional data for the Apple event parameter whose keyword is specified by optKey. This parameter is optional. If you provide the optKey and optData parameters, Guide Maker adds to the Apple event a parameter whose keyword is specified by optKey and whose data contains the value you specify in the optData parameter.

DESCRIPTION

The <Define Event> command defines an event function. You typically associate an event function with another button-defining command, such as <Standard Button> or <3D Button>. Event functions are used to send an Apple event to a target application, requesting it to perform some action. When the user clicks a button, Apple Guide calls the event function associated with that particular button and then sends the event to the specified target application.

In addition to specifying the event class and event ID, you can add two Apple event parameters to the event you send by using the IOPTData, optKey, and optData parameters. One parameter is identified by the 'IOPT' keyword, and you provide data for this Apple event parameter in the IOPTData parameter. In the optKey parameter, you provide the keyword for the second parameter and in the optData parameter you provide data for this Apple event parameter.

For example, if an event requires a direct object, specify the keyword for the direct object in the optKey parameter and specify its data in the optData parameter. Optionally, you can allow the caller of the event function to provide the data for the optData parameter. If you do this, the event definition must leave the optData parameter blank, and the caller must provide a string surrounded by quotes inside of the parentheses of the event function. As an example, for an event function called doOpenDocmt, the caller specifies the data for the direct object like this: doOpenDocmt("HD:Reports folder:Quarter 1 Report").

Guide Maker provides the following built-in event functions: DoScript, GoPanel, LaunchNewSequence, LaunchNewSequenceNewWindow, PlaySound, QuitTopicOops, and StartTopicOops. Each built-in event function corresponds to a specific Apple event that is directed to Apple Guide.

Apple Guide also supports a number of other events. These events are defined in the Standard Setup file. If your build file includes the Standard Setup file, then you can specify any of the events defined in that file.

EXAMPLES

#define doButton1Action as an event function that sends to 
# the app with signature 'WAVE' (SurfWriter) the Apple event
# defined by event class 'sfwr' and event ID 'act1'
<Define Event> "doButton1Action", 'WAVE', 'sfwr', 'act1'

<Define Panel> "Example Panel"
   <Standard Button> "Create Chapter Index", Point(50,100),
                      doButton1Action()
<End Panel>
#define doOpenDocmt as an event function that sends to 
# the app with signature 'WAVE' (SurfWriter) the 
# Open Documents event. Note that the Open Documents event
# expects a direct object (the name of the file to open)
# as a parameter. This event definition specifies the keyword of the
# direct object and the caller specifies its data.
<Define Event> "doOpenDocmt", 'WAVE', 'aevt', 'odoc',,'----' 

<Define Panel> "Example Panel 3"
   To accomplish this task, do this:
   Very informative instructions here.

   #place Open button left-justified on panel
   <3D Button> "OpenButtonUpPict", "OpenButtonDownPict", LEFT, \xAC
                doOpenDocmt("HD:SurfWriter folder:SampleReport")
<End Panel>
#define an event function that sends to
# the app with signature 'WAVE' (SurfWriter) the Apple event
# defined by event class 'sfwr' and event ID 'act2'
# This event expects two parameters: the number 2530 is the
# data for the 'IOPT' keyword; the other additional parameter has
# the keyword 'kysf' and "info for kysf parameter" as data.
<Define Event> "doButton2Action", 'WAVE', 'sfwr', 'act2', \xAC
                2530, \xAC
               'kysf', "info for kysf parameter"

<Define Panel> "Example Panel"
   <Standard Button> "Create Chapter Index", Point(50,100),\xAC
                     doButton2Action()
<End Panel>

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 <Standard Button> and <3D Button> commands, see page 10-57 and page 10-60, respectively. For information on specifying event functions for hot objects, see "Creating Hot Items" beginning on page 10-119. For information on specifying event functions for the <On Panel Create> and related commands, see page 10-183.