TweetFollow Us on Twitter

FKeys, Events
Volume Number:3
Issue Number:9
Column Tag:Forth Forum

FKeys & Events

By Jörg Langowski, MacTutor Editorial Board, Grenoble, France

FKEYs and Events

The example we’ll deal with this time has some history. On a national bulletin board here in France, Calvacom, which has a large section of its activity devoted to the Mac, a proposal was made to write an FKEY that would paste one of a number of character strings into the application currently under use. Thus one would have an easy way to enter ‘boilerplate’ phrases or often used commands into text processors, terminal emulators etc.

I thought this would make a nice example for the Forth column, especially since we hadn’t had an FKEY dealt with yet. In the way of writing this, I discovered several things. First, the simple strategy that comes to mind - taking a string that was saved away somewhere and posting key down events for one character after the other - works only in certain cases, so one has to go a more complicated way (as you’ll see soon). Second, somebody had of course in the meantime written the FKEY under question - in some other language. Nevertheless, still a good Forth example.

Implementing an FKEY

Everyone of you has probably already used one or the other function key, that is, command-shift-number combination. Some might even have written one, its implementation being rather simple. The FKEY resource is a simple subroutine with its entry point at the beginning of its code. It is called from the routine that handles the keyboard. If that routine detects a command-shift-number combination, it will look for the FKEY resource corresponding to the number, and if such a resource is present, load and execute it.

No parameters are passed to the FKEY routine on the stack; we’ll simply set up a local Forth stack on entry to the routine, using LINK, save all registers away, then call the main body of the FKEY, and finally restore the registers and UNLINK A6. This is the standard glue routine for writing kernel-independent Mach2 code which you might already be familiar with. See listing 1.

[One remark with regard to the listing here. This program has been written in Mach2.12 which has a different Toolbox call mechanism than earlier versions. In particular, it expects D4 to point to a common stack low in memory which can be used for all toolbox calls. This stack, and D4, are set up in the Mach2 system. Therefore, to write kernel-independent code, one has to use the old CALL mechanism again. This word is available under a new name: (CALL). If you have an older Mach2 version, simply replace all occurrences of (CALL) with CALL, or redefine the word].

The main body of the FKEY will first look whether it has been called from a bona fide application or whether the topmost window is a dialog or desk accessory. In the latter two cases, the FKEY will do nothing but beep and return. Since the FKEY itself might display a dialog (for editing the text strings), it should not be allowed to redisplay its own dialog when it is already active. Checking whether any dialog is already in place is one way of achieving this; you might think up some more sophisticated ways and change the program accordingly.

If the routine has been called from within a good environment, it will wait for the next key pressed. If the key is a number key, the appropriate message will be posted (see later how this is done). If it is the ‘e’ key, a dialog will be displayed for editing the text strings. In all other cases the routine will simply beep and return.

Posting Events

The first problem that we encounter here is how to post key down events that correspond to the text string into the event queue. Very simple, you’ll say, do the following:

: post.char ( char -- ) 3 swap call post.event drop ;
 : post.string ( string -- )
 count 0 DO dup i + c@ post.char LOOP drop ;

where 3 is the event code for a key down event, and the event message simply contains the character code in the low byte, and no key code (=0). Leaving out the actual key code has so far caused no problem in any case that I tested.

Well, the simple example works. In a way. If the string that is posted is longer than 15 characters, Mach2 will simply beep because it cannot accept more keydown events before switching tasks. This doesn’t have anything to do with the actual length of the event queue or the maximum number of allowed events. It is the application that can’t deal with so many ‘keystrokes’ coming in rapid succession. In addition, of course, if we don’t check the event queue before posting an event, we take the risk of losing it if the maximum number of allowed events (20 by default) has been reached.

This last number can be changed by editing the boot blocks. However, one can think of a more elegant solution that makes the whole process completely independent of the maximum length of the event queue. We allow the posting of a character only if the GetNextEvent routine fetches a null event. In that case we can be sure that not too much activity is going on and the key down event will be handled correctly.

But how do we handle this process? We cannot do some sort of waiting loop within the FKEY, since GetNextEvent will only be called by the application after we have returned. Therefore the FKEY must install a short background routine that monitors the activity of GetNextEvent and posts key down events from the string to be transmitted each time a null event is received. Here the JGNEFilter system global, already used for several examples in MacTutor (V1#9, Bob Denny, and V2#6, JL), comes in very handy. To post a message into the event queue, the post.string word as defined in the listing saves the string and its length away into a defined place and then changes the JGNEFilter vector to point to a custom routine that will post the keystrokes.

The custom routine, GNE.glue, calls GNEIntfc through our standard glue code, which you really know by now. GNEIntfc looks at A1 (which points to the event record), and if a null event is about to be transmitted, it will take the next character from the saved message string and post a key down event under the following conditions:

1. A certain delay has expired since the last character was posted (2 ticks in my example) and

2. The number of pending events is less than a predefined number (here 10).

When the end of the string has been reached, the filter routine resets the JGNEFilter vector to its old value.

Using the method just described, one can transmit strings of arbitrary length to applications. Which is what we wanted.

Editing the text strings

If an ‘e’ is pressed after the FKEY, we’ll display the editing dialog. The Rmaker source for this dialog (ID=2000 for DLOG and DITL, you may want to change this) is in listing 2. It simply consists of 10 editable text items, one OK button and some static text.

The associated Forth word, edit.messages, does a number of things. It first tries to open a resource file named ‘FKEY.messages’ and creates a new one if it doesn’t succeed. By standard, this will be kept in the system folder; leave it there. You can prepare any number of files containing standard messages by renaming them.

The routine then gets the dialog with ID 2000 (it is a shame that FKEYs cannot ‘own’ resources like DRVRs etc. can). If the dialog can’t be found, it beeps and returns; otherwise, it displays the strings from the FKEY.messages file in the boxes for the editable text items. They are 10 individual string-format resources type ‘bplt” with ID=3 to 12 (corresponding to the dialog items 3 to 12). If the resources cannot be found (i.e. the file has just been created and is empty), they are created and initialized with whatever was in the EditText items of the dialog box. In my case, I used the texts ‘Message x’, but you might just leave the strings empty. If the bplt resources are there, they replace the EditText items.

A ModalDialog is then called, allowing the strings to be edited. The only enabled item is the OK button, which returns to the Forth routine. Then, the changed text strings are written back to the bplt resources in the FKEY.messages file, the resource file updated and the dialog disposed of.

Finally, post.message is the routine that is called when a number key is pushed after the FKEY. It gets the bplt resource corresponding to that number and calls post.string (described above) to transmit the string via the GetNextEvent filter routine.

make.fkey creates a file ‘fkey.text’ that contains the FKEY resource and has the correct type and creator to be opened from the FKEY installer (from Quick and Dirty Utilities, Dreams of the Phoenix, Inc., P.O.Box 10273, Jacksonville FL 32247, (904) 396-6952). This file is then packed together with the dialog resources into one file. The FKEY may be installed with the installer; the DLOG 2000 and DITL 2000 must be copied with ResEdit.

Some last notes

As you’ve seen, yet another Mach2 version has been released, v2.12, making v2.11 obsolete only two weeks after I received it. No BIG modifications, only minor ones.

I received some comments from a reader, James Merkel, who mentioned that it would be a good idea for Palo Alto Shipping to release the source for the multitasking kernel as well, now that we have the source of the I/O task. The second comment was to release bug fixes in MacTutor as well as on GEnie, for those not having access to the GEnie Roundtable (including myself). Very good suggestion. PAS, do you listen?

Last, the bulletin board that I mentioned, Calvacom, is now accessible via Tymnet from the US. If you’d like to see what’s going on over here or want to leave me some mail, connect yourself to a Tymnet line and type ‘CalvaCom’ at the login prompt, then ‘nouveau’ when it prompts you for your access code. You can subscribe with your credit card, as usual. Speaking some French helps, of course, but most anybody on the board will understand English. Connect charges (overseas rates included) are of the order of $25 per hour. I’d like to see your feedback in my mailbox!

{1}
Listing 1: Mach2 FKEY for text glossary
( *** Function Key example. JL June 1987 *** )
ONLY FORTH ALSO ASSEMBLER ALSO MAC

4ascii QD15 CONSTANT “qd15
4ascii bplt CONSTANT “bplt
4ascii DITL CONSTANT “ditl
4ascii DLOG CONSTANT “dlog

2 CONSTANT post.delay
 ( 2 ticks wait between posting of characters )
10 CONSTANT max.event  
 ( max # of pending events allowed during posting )
$14a CONSTANT EvQHdr
$29A CONSTANT JGNEFilter
2 CONSTANT QHead
6 CONSTANT QTail
BINARY 0000000000001000 CONSTANT KeyEvent
DECIMAL
 ( header code filled at end of definitions )
header start
 JMP start  ( to be filled later )
header temprect 8 allot
header itemrect 8 allot
header myEventRec 16 allot

: beep 5 (call) sysbeep ;

CODE cmove ( redefine since this is part of Kernel )
 MOVE.L (A6)+,D0
 MOVE.L (A6)+,A1
 MOVE.L (A6)+,A0
 TST.L  D0
 BLE.S  @2
@1 MOVE.B (A0)+,(A1)+
 SUBQ.L #1,D0
 BNE.S  @1
@2 RTS
END-CODE

: / w/ ;

: getFkeyDlg 
 2000 0 -1 (call) GetNewDialog 
;

: #events EvQHdr QTail + @ EvQHdr QHead + @ - 22 / ;

: post.char ( char -- ) 3 swap (call) postEvent drop
 ;

header SavedJGNEFilter 4 allot
header SavedString 256 allot
header bytesToTransfer 4 allot
header lastpost 4 allot

: GNEIntfc { | btt -- }
    getA1 w@ 0= IF
 [‘] bytesToTransfer @ -> btt
 btt IF  (call) tickcount [‘] lastpost @ - post.delay > 
 #events max.events < AND 
 IF
 [‘] SavedString dup c@ btt - 1+
 + c@ post.char
 btt 1- [‘] bytesToTransfer !
 (call) tickcount [‘] lastpost !
 THEN
 ELSE
 [‘] savedJGNEFilter @ JGNEFilter !
 THEN
    THEN
;    
CODE GNE.glue
 LINK A6,#-256 ( 256 bytes of local Forth stack )
 MOVEM.L A0-A5/D0-D7,-(A7)( save registers )
 ( no need for loop return stack )
 ( no parameters are passed )
 JSR GNEintfc  ( call Forth routine )
 MOVEM.L (A7)+,A0-A5/D0-D7( restore registers )
 UNLK A6
 LEA  SavedJGNEFilter,A0
 MOVE.L (A0),A0  ( return address )
 JMP  (A0)
END-CODE

: post.string { string | length -- }
 string c@ -> length
 string [‘] SavedString length 1+ cmove
 length [‘] bytesToTransfer !
 (call) tickcount [‘] lastpost !
 JGNEFilter @ [‘] SavedJGNEFilter !
 [‘] GNE.glue JGNEFilter !
;

: post.message { msg# | dh dPtr tPtr -- }
 “ FKEY.messages” (call) OpenResFile (call) UseResFile
 “bplt msg# 3 + (call) getResource -> dh
 dh IF dh @ post.string
 ELSE beep THEN
;

: edit.messages 
 { | dPtr itemType item box box1 itemHit thandle refnum -- }
 “ FKEY.messages” dup (call) OpenResFile
 (call) ResError 
 IF drop dup (call) CreateResFile
 (call) OpenResFile dup -> refNum 
 (call) UseResFile 
 ELSE dup -> refNum 
 (call) UseResFile drop 
 THEN 
 getFkeyDlg -> dPtr
 dPtr IF
 13 3 DO 
 dPtr i ^ itemType ^ item ^ box
 (call) GetDItem
 item (call) HLock drop
 “bplt i (call) GetResource -> thandle
 thandle IF 
 thandle (call) HLock drop
 item thandle @ (call) SetIText 
 thandle (call) HUnlock drop 
 ELSE
 256 (call) NewHandle drop
 “bplt i “ Message” (call) AddResource
 THEN
 item (call) HUnlock drop
 LOOP ( all messages have been initialized )

 0 ^ itemHit (call) ModalDialog

 13 3 DO 
 dPtr i ^ itemType ^ item ^ box
 (call) GetDItem
 item (call) HLock drop
 “bplt i (call) GetResource -> thandle
 thandle IF 
 thandle (call) HLock drop
 item thandle @ (call) GetIText
 thandle (call) ChangedResource 
 thandle (call) HUnlock drop THEN
 item (call) HUnlock drop
 LOOP ( all messages have been updated )
 refNum (call) UpdateResFile
 dPtr (call) DisposDialog
 ELSE beep THEN
;

: fkey { | keycode -- }
 (call) frontwindow windowkind + w@ l_ext dup
 2 = swap 0< OR 0= IF 
 BEGIN 
 KeyEvent [‘] myEventRec (call) GetNextEvent UNTIL

 [‘] myEventRec message + @ $FF and -> keycode
 keycode ascii e = 
 IF edit.messages 
 ELSE
 keycode ascii 0 < keycode ascii 9 > OR
 IF beep ELSE keycode 48 - post.message
 THEN 
 THEN
 ELSE beep 
 THEN
;

( *** our standard glue routine *** )

CODE fkey.glue
 LINK A6,#-2048  ( 2K bytes of local Forth stack )
 MOVEM.L A0-A5/D0-D7,-(A7)( save registers )
 MOVE.L A6,A3    ( setup local loop return stack )
 SUBA.L #256,A3  ( starting 256 bytes below locals )
 ( no parameters are passed to the FKEY )
 JSR fkey ( call Forth routine )

 MOVEM.L (A7)+,A0-A5/D0-D7( restore registers )
 UNLK A6
 MOVE.L (A7)+,A0 ( return address )
 JMP  (A0)
END-CODE

header end

( install initial jump vector )
‘ fkey.glue ‘ start 2+ - ‘ start 2+ w!

( *** installation *** )

: make.fkey { | refNum namePtr -- }
 “ fkey.text” dup $create-res
 abort” You have to delete the old ‘fkey.text’ file first.”
 $open-res dup -> refNum call UseResFile 
[‘] start [‘] end over - call PtrToHand drop ( result code )
 “fkey 5 “ Mach2 FKEY” call AddResource
 refNum $close-res drop ( result code )
 0 “ fkey.text” 
 getvol ioVRefNum + w@ l_ext
 getfileinfo drop
 “qd15 “fkey “ fkey.text” setfileinfo
;
{2}
Listing 2: Rmaker file for the FKEY
* File fkr.R
Mach2 Fkey
FKEYQD15

Include Fkey.Text

Type DLOG
   ,2000
New Dialog
30 14 330 494
visible goAway
1
0
2000

Type DITL   
,2000
22

BtnItem
256 32 278 91
OK

StaticText
256 136 286 463  
Text FKEY © 1987 J. Langowski/MacTutor Written in Mach2™ Forth

EditText Disabled
8 32 24 464
Message 0

EditText Disabled
32 32 48 464
Message 1

EditText Disabled
56 32 72 464
Message 2

EditText Disabled
80 32 96 464
Message 3

EditText Disabled
104 32 120 464
Message 4

EditText Disabled
128 32 144 464
Message 5

EditText Disabled
152 32 168 464
Message 6

EditText Disabled
176 32 192 464
Message 7

EditText Disabled
200 32 216 464
Message 8

EditText Disabled
224 32 240 464
Message 9
 
StatText
8 8 24 28
0

StatText
32 8 48 28
1

StatText
56 8 72 28
2

StatText
80 8 96 28
3

StatText
104 8 120 28
4

StatText
128 8 144 28
5

StatText
152 8 168 28
6

StatText
176 8 192 28
7

StatText
200 8 216 28
8

StatText
224 8 240 28
9
 

Community Search:
MacTech Search:

Software Updates via MacUpdate

Fantastical 2.5.13 - Create calendar eve...
Fantastical is the Mac calendar you'll actually enjoy using. Creating an event with Fantastical is quick, easy, and fun: Open Fantastical with a single click or keystroke Type in your event... Read more
A Better Finder Rename 11.05 - File, pho...
A Better Finder Rename is the most complete renaming solution available on the market today. That's why, since 1996, tens of thousands of hobbyists, professionals and businesses depend on A Better... Read more
SpamSieve 2.9.38 - Robust spam filter fo...
SpamSieve is a robust spam filter for major email clients that uses powerful Bayesian spam filtering. SpamSieve understands what your spam looks like in order to block it all, but also learns what... Read more
TeamViewer 15.0.8397 - Establish remote...
TeamViewer gives you remote control of any computer or Mac over the Internet within seconds or can be used for online meetings. Find out why more than 200 million users trust TeamViewer! Free for non... Read more
SteerMouse 5.4.3 - Powerful third-party...
SteerMouse is an advanced driver for USB and Bluetooth mice. SteerMouse can assign various functions to buttons that Apple's software does not allow, including double-clicks, modifier clicks,... Read more
Toast Titanium 18.2.1 - The ultimate med...
Roxio Toast Titanium, the leading DVD burner for Mac, makes burning even better, adding Roxio Secure Burn to protect your files on disc and USB in Mac- or Windows-compatible formats. Get more style... Read more
HoudahSpot 5.0.11 - Advanced file-search...
HoudahSpot is a versatile desktop search tool. Use HoudahSpot to locate hard-to-find files and keep frequently used files within reach. HoudahSpot will immediately feel familiar. It works just the... Read more
ClipGrab 3.8.6 - Download videos from Yo...
ClipGrab is a free downloader and converter for YouTube, Vimeo, Facebook and many other online video sites. It converts downloaded videos to MPEG4, MP3 or other formats in just one easy step Version... Read more
ExpanDrive 7.4.0 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Adobe Dreamweaver CC 2020 20.0 - Build w...
Dreamweaver CC 2020 is available as part of Adobe Creative Cloud for as little as $20.99/month (or $9.99/month if you're a previous Dreamweaver customer). Adobe Dreamweaver CC 2020 allows you to... Read more

Latest Forum Discussions

See All

New heroes and balance updates set to ar...
It feels like Hearthstone: Battlegrounds only launched yesterday, and already the auto batter addition to Blizzard's megahit card game is set to receive new heroes and balance updates. [Read more] | Read more »
Pre-register for Hello Kitty AR: Kawaii...
Hello Kitty — the cute cat that launched a multi-billion-pound franchise — has been brought to life… sort of. Sanrio has teamed up with the Bublar Group to create a new mobile game that uses AR tech to turn the real world into Hello Kitty’s... | Read more »
Gorgeous and tranquil puzzler Spring Fal...
One-man indie studio SPARSE//GameDev has now launched its tranquil puzzler, Spring Falls. It's described as "a peaceful puzzle game about water, erosion, and watching things grow". [Read more] | Read more »
Black Desert Mobile gets an official rel...
Pearl Abyss has just announced that its highly-anticipated MMO, Black Desert Mobile, will launch globally for iOS and Android on December 11th. [Read more] | Read more »
Another Eden receives new a episode, cha...
Another Eden, WFS' popular RPG, has received another update that brings new story content to the game alongside a few new heroes to discover. [Read more] | Read more »
Overdox guide - Tips and tricks for begi...
Overdox is a clever battle royale that changes things up by adding MOBA mechanics and melee combat to the mix. This new hybrid game can be quite a bit to take in at first, so we’ve put together a list of tips to help you get a leg up on the... | Read more »
Roterra Extreme - Great Escape is a pers...
Roterra Extreme – Great Escape has been described by developers Dig-It Games as a mini-sequel to their acclaimed title Roterra: Flip the Fairytale. It continues that game's tradition of messing with which way is up, tasking you with solving... | Read more »
Hearthstone: Battlegrounds open beta lau...
Remember earlier this year when auto battlers were the latest hotness? We had Auto Chess, DOTA Underlords, Chess Rush, and more all gunning for our attention. They all had their own reasons to play, but, at least from where I'm standing, most... | Read more »
The House of Da Vinci 2 gets a new gamep...
The House of Da Vinci launched all the way back in 2017. Now, developer Blue Brain Games is gearing up to deliver a second dose of The Room-inspired puzzling. Some fresh details have now emerged, alongside the game's first official trailer. [Read... | Read more »
Shoot 'em up action awaits in Battl...
BattleBrew Productions has just introduced another entry into its award winning, barrelpunk inspired, BattleSky Brigade series. Whilst its previous title BattleSky Brigade TapTap provided fans with idle town building gameplay, this time the... | Read more »

Price Scanner via MacPrices.net

Apple continues to offer 2017 13″ Dual-Core n...
Apple has Certified Refurbished 2017 13″ 2.3GHz Dual-Core non-Touch Bar MacBook Pros still available starting at $1019. An standard Apple one-year warranty is included with each model, outer cases... Read more
Save up to $120 on the new 16″ MacBook Pro at...
Apple’s resellers are starting to receive stock of new 16″ MacBook Pros, and the first set of sales & deals are now available: (1) Amazon 16″ MacBook Pros start on sale for $100-$116 off Apple’s... Read more
Apple Watch Series 3 models on sale at Amazon...
Amazon has Apple Watch Series 3 GPS models on sale for $30 off MSRP, starting at only $169. There prices are the lowest we’ve ever seen for these models from any Apple reseller. Choose Amazon as the... Read more
The ‘Mac Potpourri’ Mailbag: Edition #1- Info...
COMMENTARY: 11.20.19- Welcome to the inaugural edition of the “Mac Potpourri” Mailbag where we take a look at correspondence received from readers of this column from all over the world who write in... Read more
13″ 2.4GHz MacBook Pros available for up to $...
Apple has a full line of Certified Refurbished 2019 13″ 2.4GHz 4-Core Touch Bar MacBook Pros available starting at $1529 and up to $300 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
New at T-Mobile: Switch to T-Mobile, and get...
T-Mobile is offering a free 64GB iPhone 8 for new customers who switch to T-Mobile and open a new line of service. Eligible trade-in required, and discount applied over a 24 month period. The fine... Read more
Xfinity Mobile’s Black Friday Apple savings:...
Take $250 off the purchase of any iPhone at Xfinity Mobile with a new line activation, and transfer of phone number to Xfinity Mobile, through December 8, 2019. This includes Apple’s new iPhone 11... Read more
2019 13″ 1.4GHz MacBook Pros available starti...
Apple has a full line of Certified Refurbished 2019 13″ 1.4GHz 4-Core Touch Bar MacBook Pros available starting at $1099 and up to $230 off MSRP. Apple’s one-year warranty is included, shipping is... Read more
Save up to $350 on a 21″ or 27″ iMac with the...
Apple has Certified Refurbished 2019 21″ & 27″ iMacs available starting at $929 and up to $350 off the cost of new models. Apple’s one-year warranty is standard, shipping is free, and each iMac... Read more
Early Holiday 2019 Sale: B&H again offers...
B&H Photo has 10.2″ iPads on sale again for $30 off Apple’s MSRP, starting at $299, as part of their early Holiday 2019 sale. Overnight shipping is free to many addresses in the US: – 10.2″ 32GB... Read more

Jobs Board

Best Buy *Apple* Computing Master - Best Bu...
**745516BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Store Associates **Store NUmber or Department:** 001101-Manhattan-Store **Job Read more
Best Buy *Apple* Computing Master - Best Bu...
**746655BR** **Job Title:** Best Buy Apple Computing Master **Job Category:** Sales **Store NUmber or Department:** 002518-Atlantic Center-Store **Job Description:** Read more
*Apple* Mobility Pro - Best Buy (United Stat...
**747089BR** **Job Title:** Apple Mobility Pro **Job Category:** Store Associates **Store NUmber or Department:** 000377-Prescott AZ-Store **Job Description:** At Read more
*Apple* Health Benefit Specialist - Call Cen...
Description ** Apple Health Benefit Specialist - Call Center (MAS 3/MACSC)** **Olympia, WA Multiple Positions** *The ideal candidate for this position will have Read more
Hair Stylist - *Apple* Blossom Mall - JCPen...
Hair Stylist - Apple Blossom Mall Location:Winchester, VA, United States- Apple Blossom Mall 1850 Apple Blossom Dr Job ID:1065040Salon Professionals Job Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.