Futurebasic/Language/Reference/on appleevent

ON APPLEEVENT

Statement

(+) Appearance (+) Standard Console

Syntax

ON APPLEEVENT (eventtype&,eventClass&)Â{FN userFunction|GOSUB{lineNumber|"stmtLabel"}} 

Revised

May, 2001 (Release 5)

Description

AppleEvents are used for communication between applications. (In dealing with Apple Events, you will often see applications referred to as processes.) Use this FB statement to set up and track specific types of Apple Events. Event types and classes that are to tracked are part of the ON APPLEEVENT parameters. Types and Classes Apple events are divided into general groups called Types. Those groups are subdivided into specific classes. As an example, you may have heard of Apple core events. There are events which every application should understand and handle. The class for this group is called _coreEventType. the long integer constant for this type is _"core". Either of these two forms of address is acceptable in FB, but only one (_"core") is case sensitive. If you wanted to deal with core events, you would have to tell the Apple Event Manager which of four classes might be of interest. As an example, you might want to know if the Finder (or some other process) sent a message to you to open a document. In such a case the class would be _kAEOpenDocuments or _"odoc". An event handler set up for this type and class would be entered as follows:

ON APPLEEVENT(_coreEventType,_kAEOpenDocuments) ÂFN myODocHandler 

FB recognizes a special event class of _"TEXT". When this class in encountered, the contents of the event parameter may be more easily accessed using the APPLEEVENTMESSAGE$ function. The following simple example shows how your ON APPLEEVENT handler might look for incoming text.

LOCAL FN doAppleEvent PRINT "Message received:" PRINT APPLEEVENTMESSAGE$ END FN ON appleevent(_"buba",_"TEXT") FN doAppleEvent 

It is often convenient to pass large blocks of data via Apple Events as handles. FB processes this automatically by pulling the data from the Apple Event and transferring it to your application as a handle. FB always copies the data, so when you are finished, you must manage disposal on your own. The following fragment shows how a handle is received and disposed. To show that the data was accepted, this routine prints the first fifty characters of the handle as ASCII text.

LOCAL
DIM AERec as AERecord
DIM @OSErr
DIM dataHandle as handle
DIM n
LOCAL FN doAppleEvent
OSErr = FN AEGETPARAMDESC(gFBAEEvent&,Â
_keyDirectObject, _"CLAS", AERec)
dataHandle = AERec.dataHandle
CLS
PRINT "Rec'd at ";TIME$
FOR n = 1 TO 50
PRINT CHR$(PEEK([dataHandle]+n));
NEXT
CALL DISPOSEHANDLE(dataHandle)
END FN 

When this handler was set up, the class parameter for ON APPLEEVENT was _"CLAS". You can see that it was required for use in FN AEGETPARAMDESC. Note: Some handlers (like the example above) are already built in to most of the FB runtimes. In order to override a behavior, you will first have to use KILL APPLEEVENT. Only one Apple Event vector is allowed. If you create multiple ON APPLEEVENT vectors, each one overwrites the previous, so the last vector will be used. To handle multiple eventClasses and/or types in the one application, set up a vector for each, pointing all to the one handler. The handler can determine which class it has received by examining the global variable gFBAEType&. (See KILL APPLEVENT for the proper method of replacing an event vector.)

Example:

CD Example: AppleEvents Folder 

See Also

SENDAPPLEEVENT, HANDLEEVENTS, APPLEEVENTMESSAGE$, GETPROCESSINFO, KILL APPLEEVENT