TweetFollow Us on Twitter

Chain Events
Volume Number:9
Issue Number:12
Column Tag:Jörg's Folder

Related Info: Event Manager Apple Event Mgr

Apple Event Handlers in MacForth

Changing the main event loop with executable chains

By Jörg Langowski, MacTech Magazine Regular Contributing Author

Note: Source code files accompanying article are located on MacTech CD-ROM or source code disks.

Which Macintosh programming environment - other than Forth - do you know where you can change the main event loop on the fly, plug in new routines or change them while you’re trying them out, or even while your application is running? Maybe Lisp, but certainly none of the development systems (C and C++ of various flavors, Pascal, maybe Fortran and Basic) that account for the majority of all applications on the market. You can solve some of these problems through runtime binding in C++, but for developing a program you still face that edit/compile/link/crash cycle. When I did the example for this column, implementing high-level event support in MacForth, I had plenty of opportunity to appreciate the incremental compiling that Forth offers, together with a good low-level debugger like TMON.

So after having seen how to use Apple events in Fortran and C++, you knew that a Forth example on that subject was just unavoidable. MacForth 4.0, the version that I am still using, does not offer built-in support for high level events. I’m not sure whether the latest 4.2 update does, but I’ll keep you informed as soon as I receive it. Anyway, for the sake of example it is better to use a version that does not support Apple events, because then you can see how to do it.

You remember that an application that supports Apple events has to tell this to the system. There is a bit in the SIZE resource reserved for this purpose. So the first step to make our MacForth kernel high-level event aware is to use ResEdit and set this bit to 1. Now the application’s name will, e.g., be visible in the PPC browser dialog when you select an application to interact with. Now comes the actual work, implementing an Apple event handler in MacForth.

Hooking into the main event loop

Apple events have an event code of 23. Older applications that did not handle Apple events did not check for this code. So how do you persuade the MacForth runtime system to react to high-level events, that is, how does one change the main event loop? (Let’s assume we don’t have access to the source). Easy. MacForth solves this and related problems - like how do you change its behavior on startup and during quit - through the concept of executable chains. These are lists of Forth words that are executed in sequence on various occasions; for instance, the Eventer chain is executed on each pass through the main event loop. There is a standard mechanism to add new Forth words to this chain. If you would add a word to the Eventer chain, all you do is to write Eventer linked followed by your word’s definition (see near the end of the example listing). This word is then automatically linked into the main event loop.

Words linked into the Eventer chain take an event code as a parameter and leave an event code (which may be different from the original one) plus a flag on the stack. The flag tells the system whether the event has been processed (true) or not (false). Thus, we’ll define a word that looks for event code 23 and if it finds it, calls ProcessAppleEvent, the routine that finds the handler corresponding to the Apple event received.

Event handlers

The handlers themselves are installed in a dispatch table through the Forth word Install.Event.Handler (see listing). The parameters to the trap are, from bottom to top of stack:

• the event class specifier (32 bit);

• the event ID (32 bit);

• a pointer to the handler routine (32 bit);

• a reference constant (32 bit);

• a boolean (16 bit) which is true if the handler is installed in the system event dispatch table, false otherwise.

The event class for the required Apple events is ‘aevt’, and the event IDs are ‘oapp’, ‘odoc’, ‘pdoc’, and ‘quit’. We will define handlers for all these events except ‘oapp’.

The address of the handler that is passed to the AEInstallEventHander trap must be a pointer to a routine that follows Pascal calling conventions. Of course, a standard MacForth word doesn’t do that, and you have to define the handler routines in a particular way. MacForth offers two ‘filter routine’ definition words, filter: and ;filter that can be used for that purpose. If you use them instead of : and ; at the start and end of a Forth definition, the resulting word will be callable as a subroutine from machine language. All the word does on execution is to put the entry address of the routine on the stack, which can then be passed as a parameter to a toolbox trap.

The first handler that we’ll write is for the ‘quit’ event. It seems pretty simple; just call ExitToShell and you’re done. But wait we can’t pull the rug from underneath other things that may be going on in the run time system; e.g. open files that have been edited and are not saved, etc. There is a Forth word, bye, that quits the MacForth system gracefully and will for instance present you with the ‘Save Changes ’ dialog box when there are unsaved files. So why not call bye from within the handler? I’ve tried that, with spectacular crashes as a result. This approach does not work because the handler routine would never return correctly, and I guess this leaves things hanging in the air that should be safely fixed on the ground. A safe way to quit is to install a token for a word that quits in the event.filter variable. If this variable is nonzero, MacForth assumes that it contains the pointer to a routine that is called on every pass through the main event loop. We now define a word ciao which resets event.filter to zero and then calls bye, and the quit handler will install the token for this word in event.filter. This way we make sure that ciao is called only once when the ‘quit’ event is received.

You can try out the ‘quit’ handler by using any of the tools to send an Apple event to other applications (there is a Hypercard stack and an Apple event test application available on the Apple ETO CD-ROM, and I’m sure there are public domain programs floating around in cyberspace). You’ll see that MacForth quits, and if there is any open file with unsaved changes, opens the dialog that asks you whether you want to save the changes. I had some problems with the quit handler when I used it in connection with the extended editor (see my last Forth column), and don’t know the reason for sure, but with the standard Sibley editor it works alright.

The other two handlers are for opening and printing documents from the finder. They are very similar, and one could easily modify this so that only one handler is called for both purposes, the switch between open and print behavior being done through the reference constant that is passed when the handler is installed.

These handlers are direct translations from the proposed ‘odoc’ and ‘pdoc’ handlers in Inside Mac vol. 6. First, we get the parameter descriptor out of the Apple event that corresponds to a list of files to be opened or printed. The keyword for this descriptor is ‘list’. The descriptor returned consists of two 32-bit words, the first one containing the parameter type (‘list’), the second one a handle to this parameter. The address of the descriptor is then passed to a routine that counts the number of items in the list (CountItems), and then a loop is executed that steps an index starting at 1 to the number of items, and opens - or prints - each item. The information about the file to be opened is obtained through the routine Get.Nth.Ptr which gets the data corresponding to the n-th item out of a descriptor list. The parameters taken by the trap, AEGetNthPtr, used in this routine are the following:

• a pointer to the descriptor list (32 bits);

• the number of the desired item (32 bits);

• the type of the desired item (32 bits);

• a keyword if one is associated with the descriptor record (32 bits);

• the descriptor type of the item returned (32 bits);

• a pointer to the data buffer (32 bits);

• the maximum size of the data to be returned (32 bits);

• the address of a variable that contains the actual size of the data returned (32 bits).

We call this trap with our descriptor list as a parameter, and specifying that we want the data to be returned in the format of a file system specifier (‘fss ’). Actually, the information about the files to be processed in the ‘odoc’ and ‘pdoc’ Apple events is in the format of alias records, which allows file aliases to be processed transparently. If we specify as the desired type ‘fss ’, the Apple Event manager will automatically ‘coerce’ the alias data to the FSS format, thus resolve the alias. You don’t have to worry about this, all that’s important is that the buffer myFSS contains the volume reference number (16 bits), the directory ID (32 bits), and the file name (63 byte string), in that order. After the successful call to GetNthPtr, this information is extracted from the buffer and used to call either of two routines: se.open$ for opening a file in a new editor window, or (paper) for printing it.

After all these preliminaries, try and load the Forth code, and then drag a few files from the finder to the MacForth item, or select the print command. You’ll see how it works. If it doesn’t, make sure that you have modified your SIZE resource with ResEdit so that the high-level events bit is set.

Things to be resolved

There remain quite a few things that could still be done, for instance, I haven’t told you how to install Apple event handlers in a stand-alone MacForth application, or how to handle other types of Apple events. In fact, I have a very nice project: to install a ‘dosc’ handler in MacForth that interprets Forth code that is sent from other applications, and send back the result in text form. Sort of a Forth tool server. But this is something that you may find in a later column. Until then, happy threading.

Example: Implementing the required Apple events in MacForth 4.0
anew testAE


\ generic interface word to the AE manager

<code AEPack
 popd0, \ pop selector into d0
 MAC Pack8 w,
 next,


\ some AE routines that we need in this example
\ the Pack8 routines all return a 16-bit result,
\ so we have to leave space below the parameters
\ on the stack. Here, we push a 32-bit 0 and later shift the 
\ result code by 16 bit ( hex 10000 / )

hex
: Process.Apple.Event
 0 event.record 021b AEPack 10000 /
;

: Install.Event.Handler  ( AEclass AEID AEproc -- OSErr )      
 0 3 bury ( space for result)
 0 ( refcon ) 0 0 wbury ( false ) 091f ( selector )
 AEPack 10000 /
;

: Get.Param.Desc 
 ( theEvent AEKey DescType AEDesc -- OSErr )
 0 4 bury ( space for result)
 0812 AEPack 10000 /
;

: Count.Items ( DescList theCount -- OSErr )
 0 2 bury ( space for result)
 0407 AEPack 10000 /
;

: Get.Nth.Ptr ( DescList index desiredType theAEKey
 typeCode dataPtr maximumSize actualSize -- OSErr )
 0 8 bury ( space for result )
 100A AEPack 10000 /
;
 
: Dispose.Desc ( AEDesc -- OSErr )
 0 swap 0204 AEPack 10000 /
;
decimal


\ global variables

create myFSS 70 allot
create docList 8 allot


\ the ‘quit’ handler does not call bye directly (this leads to
\ crashes), but just puts a token to a ‘bye’ routine into 
\ EVENT.FILTER. The ‘bye’ routine then sets the filter
\ back to ‘off’ again, so that it won’t be called all over 
\ again in case the user cancels the bye process.

\ our ‘bye’ routine. 

: ciao 
 event.filter off
 bye
;


\ the quit handler itself

filter: AEquit
 locals| refcon reply theEvent |
 token.for ciao event.filter !
;filter


\ ‘odoc’ handler, uses routines from the Sibley editor

filter: AEodoc
 0 0 0 0 
 locals| actualSize descType myKey #items 
 refcon reply theEvent |
 
 theEvent  ascii ---- ( DirectObject )
 ascii list ( AEList ) docList
 Get.Param.Desc 
 if ." GetParamDesc error" cr then
 
 docList addr.of #items  
 Count.Items
 if ." CountItems error" cr then
 
 #items 1+ 1 do
 docList i ascii fss_ addr.of myKey 
 addr.of descType myFSS 70 addr.of actualSize  
 Get.Nth.Ptr
 if ." Get.Nth.Ptr error" cr then
 myFSS 6+ myFSS w@ myFSS 2+ @ se.open$ 
 loop
 
 docList Dispose.Desc
 if ." Dispose.Desc error" cr then
;filter


\ ‘pdoc’ handler, very similar to the ‘odoc’ handler (some
\ code could be factored out here). Uses the printing 
\ routine from ‘Paper’

filter: AEpdoc
 0 0 0 0 
 locals| actualSize descType myKey #items 
 refcon reply theEvent |
 
 theEvent  ascii ---- ( DirectObject )
 ascii list ( AEList ) docList
 Get.Param.Desc 
 if ." GetParamDesc error" cr then
 
 docList addr.of #items  
 Count.Items
 if ." CountItems error" cr then
 
 #items 1+ 1 do
 docList i ascii fss_ addr.of myKey addr.of descType
 myFSS 70 addr.of actualSize  
 Get.Nth.Ptr
 if ." Get.Nth.Ptr error" cr then
 myFSS w@ volref# !
 myFSS 2+ @ ioDir !
 myFSS 6+ (paper) 
 loop
 
 docList Dispose.Desc
 if ." Dispose.Desc error" cr then
;filter

\ space for filter routine return stack
256 allot here 64 - FilterRP !


\ word to install the handlers. We have not provided the 
\ ‘oapp’ handler, but put in there anything you like

: install.req.handlers
   ascii aevt ascii quit AEquit Install.Event.Handler drop
\ ascii aevt ascii oapp AEoapp Install.Event.Handler drop
   ascii aevt ascii odoc AEodoc Install.Event.Handler drop
   ascii aevt ascii pdoc AEpdoc Install.Event.Handler drop
;

\ we need to catch the high level event. MacForth allows to 
\ easily hook new event handlers into the main event loop, 
\ through the Eventer executable chain.
 
Eventer Linked
: AEDispatch
 dup
 23 = if
 Process.Apple.Event drop
 drop 0 true
 else
 false
 then
;

\ finally, install the handlers
install.req.handlers

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

WhatRoute 2.0.18 - Geographically trace...
WhatRoute is designed to find the names of all the routers an IP packet passes through on its way from your Mac to a destination host. It also measures the round-trip time from your Mac to the router... Read more
Posterino 3.3.5 - Create posters, collag...
Posterino offers enhanced customization and flexibility including a variety of new, stylish templates featuring grids of identical or odd-sized image boxes. You can customize the size and shape of... Read more
Skim 1.4.28 - PDF reader and note-taker...
Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. Skim includes many features and has a... Read more
Apple macOS Sierra 10.12.4 - The latest...
With Apple macOS Sierra, Siri makes its debut on Mac, with new features designed just for the desktop. Your Mac works with iCloud and your Apple devices in smart new ways, and intelligent... Read more
Apple Numbers 4.1 - Apple's spreads...
With Apple Numbers, sophisticated spreadsheets are just the start. The whole sheet is your canvas. Just add dramatic interactive charts, tables, and images that paint a revealing picture of your data... Read more
Xcode 8.3 - Integrated development envir...
Xcode includes everything developers need to create great applications for Mac, iPhone, iPad, and Apple Watch. Xcode provides developers a unified workflow for user interface design, coding, testing... Read more
Dropbox 22.4.24 - Cloud backup and synch...
Dropbox is an application that creates a special Finder folder that automatically syncs online and between your computers. It allows you to both backup files and keep them up-to-date between systems... Read more
Merlin Project 4.2.0 - Project managemen...
Merlin Project is the leading professional project management software for OS X. If you plan complex projects on your Mac, you won’t get far with a simple list of tasks. Good planning raises... Read more
Postbox 5.0.12 - Powerful and flexible e...
Postbox is a new email application that helps you organize your work life and get stuff done. It has all the elegance and simplicity of Apple Mail, but with more power and flexibility to manage even... Read more
Apple Pages 6.1 - Apple's word proc...
Apple Pages is a powerful word processor that gives you everything you need to create documents that look beautiful. And read beautifully. It lets you work seamlessly between Mac and iOS devices, and... Read more

Hearthstone celebrates the upcoming Jour...
Hearthstone gets a new expansion, Journey to Un'Goro, in a little over a week, and they'll be welcoming the Year of the Mammoth, the next season, at the same time. There's a lot to be excited about, so Blizzard is celebrating in kind. Players will... | Read more »
4 smart and stylish puzzle games like Ty...
TypeShift launched a little over a week ago, offering some puzzling new challenges for word nerds equipped with an iOS device. Created by Zach Gage, the mind behind Spelltower, TypeShift boasts, like its predecessor, a sleak design and some very... | Read more »
The best deals on the App Store this wee...
Deals, deals, deals. We're all about a good bargain here on 148Apps, and luckily this was another fine week in App Store discounts. There's a big board game sale happening right now, and a few fine indies are still discounted through the weekend.... | Read more »
The best new games we played this week
It's been quite the week, but now that all of that business is out of the way, it's time to hunker down with some of the excellent games that were released over the past few days. There's a fair few to help you relax in your down time or if you're... | Read more »
Orphan Black: The Game (Games)
Orphan Black: The Game 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Dive into a dark and twisted puzzle-adventure that retells the pivotal events of Orphan Black. | Read more »
The Elder Scrolls: Legends is now availa...
| Read more »
Ticket to Earth beginner's guide: H...
Robot Circus launched Ticket to Earth as part of the App Store's indie games event last week. If you're not quite digging the space operatics Mass Effect: Andromeda is serving up, you'll be pleased to know that there's a surprising alternative on... | Read more »
Leap to victory in Nexx Studios new plat...
You’re always a hop, skip, and a jump away from a fiery death in Temple Jump, a new platformer-cum-endless runner from Nexx Studio. It’s out now on both iOS and Android if you’re an adventurer seeking treasure in a crumbling, pixel-laden temple. | Read more »
Failbetter Games details changes coming...
Sunless Sea, Failbetter Games' dark and gloomy sea explorer, sets sail for the iPad tomorrow. Ahead of the game's launch, Failbetter took to Twitter to discuss what will be different in the mobile version of the game. Many of the changes make... | Read more »
Splish, splash! The Pokémon GO Water Fes...
Niantic is back with a new festival for dedicated Pokémon GO collectors. The Water Festival officially kicks off today at 1 P.M. PDT and runs through March 29. Magikarp, Squirtle, Totodile, and their assorted evolved forms will be appearing at... | Read more »

Price Scanner via MacPrices.net

13-inch MacBook Airs, Apple refurbished, in s...
Apple has Certified Refurbished 2016 13″ MacBook Airs available starting at $849. An Apple one-year warranty is included with each MacBook, and shipping is free: - 13″ 1.6GHz/8GB/128GB MacBook Air: $... Read more
12-inch Retina MacBooks on sale for $1199, sa...
B&H has 12″ 1.1GHz Retina MacBooks on sale for $100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 12″ 1.1GHz Space Gray Retina MacBook: $1199 $100 off MSRP - 12″ 1.1GHz... Read more
Save up to $260 with Apple refurbished 12-inc...
Apple has Certified Refurbished 2016 12″ Retina MacBooks available for $200-$260 off MSRP. Apple will include a standard one-year warranty with each MacBook, and shipping is free. The following... Read more
13-inch 2.7GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 13″ 2.7GHz/128GB Retina Apple MacBook Pro on sale for $170 off MSRP. Shipping is free, and B&H charges NY tax only: - 13″ 2.7GHz/128GB Retina MacBook Pro (MF839LL/A): $... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
B&H Photo has the 2015 15″ 2.2GHz Retina MacBook Pro (MJLQ2LL/A) on sale for $1799.99 including free shipping plus NY sales tax only. Their price is $200 off MSRP. Read more
Save up to $160 with Apple refurbished 9-inch...
Apple has Certified Refurbished 9″ and 12″ Apple iPad Pros available for up to $160 off the cost of new iPads. An Apple one-year warranty is included with each model, and shipping is free: - 32GB 9″... Read more
Apple Chip Foundry TSMC To Begin A11 System-o...
Digitimes’ Steve Shen is reporting today that according to the Chinese-language Economic Daily News (EDN), chipmaker and major Apple supplier foundery Taiwan Semiconductor Manufacturing Company (TSMC... Read more
MacX MediaTrans 3.5 iOS Data Transfer Spring...
MacXDVD Software has announced general availability of the latest MacX MedTrans 3.5, featuring a new user interface (UI). MacX MediaTrans is ann iPhone manager that enables free data transfer between... Read more
Regular Price $19.95 DupeZap 4 Finder For OS...
Hyperbolic Software has announced the release of DupeZap 4.0.2, their modern duplicate finder developed exclusively for macOS. DupeZap 4 is an utility for Mac owners seeking to reclaim disk space... Read more
B-Eng Releases SSD Health Check for MVNe for...
Fehraltorf, Switzerland based B-Eng has announced the release and immediate availability of SSD Health Check for MVNe for MacBook Pro, their app that delivers important data and insights for MVNe... Read more

Jobs Board

Fulltime aan de slag als shopmanager in een h...
Ben jij helemaal gek van Apple -producten en vind je het helemaal super om fulltime shopmanager te zijn in een jonge en hippe elektronicazaak? Wil jij werken in Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492889BR** **Job Title:** Apple Mobile Master **Location Number:** 000886-Norwalk-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492472BR** **Job Title:** Apple Mobile Master **Location Number:** 000470-Seattle-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Mobile Master - Best Buy (United Sta...
**492562BR** **Job Title:** Apple Mobile Master **Location Number:** 000853-Jackson-Store **Job Description:** **What does a Best Buy Apple Mobile Master do?** Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.