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
 
AAPL
$108.00
Apple Inc.
+1.02
MSFT
$46.95
Microsoft Corpora
+0.90
GOOG
$559.08
Google Inc.
+8.77

MacTech Search:
Community Search:

Software Updates via MacUpdate

Vitamin-R 2.20b1 - Personal productivity...
Vitamin-R creates the optimal conditions for your brain to work at its best by structuring your work into short bursts of distraction-free, highly focused activity alternating with opportunities for... Read more
Dropbox 2.10.44 - Cloud synchronization...
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
Sandvox 2.9.2 - Easily build eye-catchin...
Sandvox is for Mac users who want to create a professional looking website quickly and easily. With Sandvox, you don't need to be a Web genius to build a stylish, feature-rich, standards-compliant... Read more
Cocktail 8.0.1 - General maintenance and...
Cocktail is a general purpose utility for OS X that lets you clean, repair and optimize your Mac. It is a powerful digital toolset that helps hundreds of thousands of Mac users around the world get... Read more
LibreOffice 4.3.3.2 - Free Open Source o...
LibreOffice is an office suite (word processor, spreadsheet, presentations, drawing tool) compatible with other major office suites. The Document Foundation is coordinating development and... Read more
VMware Fusion 7.0.1 - Run Windows apps a...
VMware Fusion allows you to create a Virtual Machine on your Mac and run Windows (including Windows 8.1) and Windows software on your Mac. Run your favorite Windows applications alongside Mac... Read more
OneNote 15.3.2 - Free digital notebook f...
OneNote is your very own digital notebook. With OneNote, you can capture that flash of genius, that moment of inspiration, or that list of errands that's too important to forget. Whether you're at... Read more
Audio Hijack Pro 2.11.4 - Record and enh...
Audio Hijack Pro drastically changes the way you use audio on your computer, giving you the freedom to listen to audio when you want and how you want. Record and enhance any audio with Audio Hijack... Read more
Iridient Developer 3.0.0 beta 3 - Powerf...
Iridient Developer (was RAW Developer) is a powerful image conversion application designed specifically for OS X. Iridient Developer gives advanced photographers total control over every aspect of... Read more
TextWrangler 4.5.11 - Free general purpo...
TextWrangler is the powerful general purpose text editor, and Unix and server administrator's tool. Oh, and also, like the best things in life, it's free. TextWrangler is the "little brother" to... Read more

Latest Forum Discussions

See All

Monster Flash Review
Monster Flash Review By Jordan Minor on October 31st, 2014 Our Rating: :: ALONE IN THE DARKUniversal App - Designed for iPhone and iPad Solid shooting and a surprising amount of spooky tension make Monster Flash a great portable... | Read more »
Retry Review
Retry Review By Rob Thomas on October 31st, 2014 Our Rating: :: SOARING HIGHUniversal App - Designed for iPhone and iPad Flappy who? Let Retry wash all those bad bird-related memories away on a cool retro-flavored flight… right... | Read more »
Dementia: Book of the Dead Review
Dementia: Book of the Dead Review By Lee Hamlet on October 31st, 2014 Our Rating: :: A TOUGH READUniversal App - Designed for iPhone and iPad A witch hunter is sent after a demonic book in the spooky but short-lived Dementia: Book... | Read more »
Card Dungeon, the Semi-Board Game Roguel...
Card Dungeon, the Semi-Board Game Roguelike, Has Been Renovated Posted by Jessica Fisher on October 31st, 2014 [ permalink ] | Read more »
Logitech Protection + Power iPhone5/5S C...
Made by: Logitech Price: $99.99 Hardware/iOS Integration Rating: 3 out of 5 stars Usability Rating: 0.5 out of 5 stars Reuse Value Rating: 0.75 out of 5 stars Build Quality Rating: 0.75 out of 5 stars Overall Rating: 1.25 out of 5 stars | Read more »
This Is Not a Test Goes Free, Permanentl...
This Is Not a Test Goes Free, Permanently Posted by Jessica Fisher on October 31st, 2014 [ permalink ] Universal App - Designed for iPhone and iPad | Read more »
Swap Heroes Review
Swap Heroes Review By Campbell Bird on October 31st, 2014 Our Rating: :: STRATEGIC SWAPPINGUniversal App - Designed for iPhone and iPad Rotate a cast of heroes to fend of waves of monsters in this difficult, puzzle rpg.   | Read more »
Night Sky Pro™ (Reference)
Night Sky Pro™ 3.0.1 Device: iOS Universal Category: Reference Price: $2.99, Version: 3.0.1 (iTunes) Description: Night Sky Pro™Wonder No More™ Night Sky Pro™ is the ultimate stargazing experience. From the creators of the original... | Read more »
Audio Defence : Zombie Arena (Games)
Audio Defence : Zombie Arena 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: A zombie shooter audio game. Made from gut-wrenching 3D binaural sound, for a new kind of weird immersion. You... | Read more »
RPG Asdivine Hearts (Games)
RPG Asdivine Hearts 1.1.0 Device: iOS Universal Category: Games Price: $3.99, Version: 1.1.0 (iTunes) Description: SPECIAL PRICE50% OFF (USD 7.99 -> USD 3.99)!!! Travel alongside four companions and a cat in the adventure of a... | Read more »

Price Scanner via MacPrices.net

Tablets Ascendent Again; Global Tablet Market...
The worldwide tablet grew 11.5% year over year in the third quarter of 2014 (3Q14) with shipments reaching 53.8 million units according to preliminary data from the International Data Corporation (... Read more
Apple now offering refurbished 2014 13-inch R...
The Apple Store is now offering Apple Certified Refurbished 2014 13″ Retina MacBook Pros for up to $270 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Apple Regains Momentum As Windows Stutters An...
The latest smartphone sales data from Kantar Worldpanel ComTech, for the three months to March 2014, shows Apple performing strongly in the first quarter of the year, with sales bouncing back in... Read more
Worldwide Smartphone Shipments Increase 25.2%...
New smartphone releases and an increased emphasis on emerging markets drove global smartphone shipments above 300 million units for the second consecutive quarter, according to preliminary data from... Read more
Apple now offering refurbished 2014 15-inch M...
The Apple Store is now offering Apple Certified Refurbished 2014 15″ Retina MacBook Pros for up to $400 off the cost of new models. An Apple one-year warranty is included with each model, and... Read more
Apple drops prices on refurbished 2013 Retina...
The Apple Store has dropped prices on 2013 Apple Certified Refurbished 13″ and 15″ Retina MacBook Pros, with Retina models now available starting at $999. Apple’s one-year warranty is standard, and... Read more
New 2.8GHz Mac mini on sale for $949, save $5...
Abt Electronics has the new 2.8GHz Mac mini in stock and on sale for $949.05 including free shipping. Their price is $50 off MSRP, and it’s the lowest price available for this model from any reseller... Read more
Sale! 3.7GHz Quad Core Mac Pro available for...
 B&H Photo has the 3.7GHz Quad Core Mac Pro on sale for $2649 including free shipping plus NY sales tax only. Their price is $350 off MSRP, and it’s the lowest price for this model from any... Read more
Mujjo Steps Up The Game With Refined Touchscr...
Netherlands based Mujjo have just launched their Refined Touchscreen Gloves, stepping up their game. The gloves feature a updated elegant design that takes these knitted gloves to the next level. A... Read more
Sale! Preorder the new 27-inch 5K iMac for $2...
 Abt Electronics has the new 27″ 3.5GHz 5K iMac on sale and available for preorder for $2374.05 including free shipping. Their price is $125 off MSRP, and it’s the lowest price available for this... Read more

Jobs Board

Position Opening at *Apple* - Apple (United...
…Summary** As a Specialist, you help create the energy and excitement around Apple products, providing the right solutions and getting products into customers' hands. You Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** Being a Business Manager at an Apple Store means you're the catalyst for businesses to discover and leverage the power, ease, and flexibility of Apple Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** As more and more people discover Apple , they visit our stores seeking ways to incorporate our products into their lives. It's your job, as a Store Read more
Position Opening at *Apple* - Apple (United...
**Job Summary** At the Apple Store, you connect business professionals and entrepreneurs with the tools they need in order to put Apple solutions to work in their Read more
Solutions Specialist with *Apple* Knowledge...
Company Description: We are an Apple Authorized Sales and Service Provider. We have been selling and servicing Apple computers in the Fairfield County area for over Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.