![](/file/12652/www.mactech.com.tar/www.mactech.com/sites/all/themes/custom_front/images/you_are_here_red.gif)
![](/file/12652/www.mactech.com.tar/www.mactech.com/sites/default/files/beta-site.gif)
|
Volume Number: | 4 | |||
Issue Number: | 6 | |||
Column Tag: | Assembly Language Lab |
FKEY that runs other FKEYs!
By John Holder, Contributing Editor
[John Holder is a previous contributor to MacTutor and is well known for his numerous FKEY shareware products. In this article, John shows us how to create an FKEY that runs other FKEYS without installing them in the system folder! Hence this FKEY has an event loop, menu bar and all the other goodies normally found in a regular application. The source code disk for this month also includes two of his more popular FKEYS to use as launch samples, along with a shareware application so you can contact John about other goodies he might have for you. -Ed]
What’s an FKEY?
FKEY’s (Function Keys) are resources containing executable code that are called upon by hitting the keys Command-Shift-# (any number 0-9) at the same time. In the standard System file there are two FKEY’s; with an ID#3 and #4 that are used to dump the current screen or window onto disk or printer.
There are also many other FKEY’s out in the Mac world, some Public Domain or Shareware, and others are sold commercially. They can be installed into the System file by using “ResEdit” or “Fkey Installer” (this application was created by “Dreams of the Phoenix, Inc™” and released into the public domain to encourage people to make Fkeys). The Fkey presented in this article can be used to access other Fkey’s which are not in the System file!
What’s this all about?
This article will show you how to create an FKEY with an interface similar to a standard applications (menus with command key equivalents, windows, and an event loop). It does not support DA’s nor does it have an EDIT menu, but if you need to add this function to your own Fkey it would be very simple.
This Fkey was created with the Macintosh 68000 Development System. All applications are on a disk titled ‘MDS1’ and all .D files are on a disk titled ‘MDS2’. First assemble the file ‘FkeyTemp.Asm’, then run the linker on the file ‘FkeyTemp.Link’, and finally run RMaker on the file ‘FkeyTemp.R’. You will now have an FKEY ready to put into your System file!
Fig. 1 Our FKEY launches other fkeys!
Fkey Sampler, How it Works
First, we create an offset table that is used to store the FKEY’s many “global” variables. This is done by naming the offsets that it will need such as sfReply, WindPtr, etc., and calculating how many bytes each will take (explained under “How to set up the offset Table”).
When the Fkey starts, there is a short jump over its header, then the applications current port and all registers are saved, next it brings up the standard arrow cursor with _InitCursor. We now check the global variable MenuList to see if the application which is currently running has a menu, if it doesn’t have one (like the MiniFinder) then we can’t let the Fkey run! If it does have a menu, we try to allocate enough space for the Fkey’s global variables by making a non-relocatable block with _NewPtr. If there is not enough memory for the globals (there has been an error if _NewPtr returns a zero in register A0) it beeps the speaker and returns to the Application. Otherwise, a pointer to the storage area is put into register A4.
If the storage was allocated, we go on and get a handle to a copy of the applications menu bar with _GetMenuBar, and clear the menu so that we may replace it with our own. After the Fkey’s menus are created with _NewMenu, _AppendMenu, and _InsertMenu, we create a window that will simulate the standard desktop. Creating a new window generates an update event, so when it gets to the main event loop, the window will be filled with the current desktop pattern.
The Main Event
Now its off to the main loop to look for events. This Fkey uses only keydown, mousedown & update events. Upon a useable event we jump to the appropriate routine to handle it, if it’s an update event the background window is filled with the current desktop pattern (found in the system global variable “DeskPattern”). Other events are handled just like a standard application by using a jump table to jump to the appropriate routines.
Doing the About...
When the mouse is clicked in the “About Fkey Sampler...” menu item under the Apple menu, a window is created and set as the current port. Then the windows text font and size is set to 9 point Monaco with _TextFont and _TextSize. Now the stack is set up for _TextBox (a very handy routine that displays text in a given rectangle with left, right or center justification!) Then we jump to a routine that uses _GetOSEvent to watch for a mousedown or key down event. When a key or the mouse button has been clicked we dispose of the window, unhighlight the menu and return to the main loop to get the next event!
Fig. 2 A useful FKEY running under our FKEY
Opening the Fkey
The purpose of this particular Fkey is to open and use other FKEY’s (of Type ‘FKEY’) that are not in the System file. When this routine is called, the standard get file dialog is displayed with _Pack3. If a name is chosen, the volume the file is on is set as the current volume with _SetVol. Now we try to open the resource fork of the file (_OpenResFile will return a #-1 if it can’t open a files resource fork). If the resource file opened with no problems we want to get the Fkey resource which is inside this file and execute it (run it, not kill it!).
Now we want to get the first Fkey resource in memory by using _GetIndResource (the newly opened res file is searched first). We check to make sure the returned Fkey is from the newly opened resource file by using _HomeResFile (when given a handle to a resource, this routine returns its resource files reference number). If it is from the Fkey file just opened, the Fkey resource is locked in memory (we don’t want the Fkey moving!), the handle is made into a pointer and the Fkey is executed by jumping to it (with JSR). When that Fkey is done, we close the resource file and return for the next event.
Doing the Quit!
When an Fkey quits it must dispose of any memory it created. The first thing dumped is the window used as the desktop, then the menus it made are released from memory with _DisposMenu and the menu bar is cleared. Now the applications menu bar is restored, the memory we allocated for the globals is released, all events are flushed, the applications current port and registers are restored, and a return from subroutine RTS returns command to the application!
Fig. 3 Map for how the FKEY is constructed Use ResEdit to copy the FKEY into the system file
Making your own FKEY
All Fkey’s must start with the FKEY header shown in the code listing. The only thing you will need to change in the header for your own Fkey is the ID number. You can use this Fkey to test all of your own Fkeys without installing them into the System file!
To make your own Fkey using this one as a template should be very simple. Just make your own offset table, or use this one and add your own needed offsets (explained below), then add your own menus and the appropriate routines to handle them. Also, change the contents of the text between MyTextBegin and MyTextEnd to whatever you want for your Fkeys ‘About..’ window.
A complete jump table for events and a jump table for where the mouse was clicked (returned by _FindWindow) is included to help in making your own Fkeys. Just remember to always check if there is enough memory before loading a resource or creating storage and to dispose of any storage that the Fkey created before returning control to the application!
How to set up the Offset Table
Lets say you need room for one handle (4 bytes) and two separate words (2 bytes each) of storage.
For the this storage you would need to put #8 into register D0 before calling _NewPtr (8 bytes are needed)
;Your Offset table (example) AHandle equ 0 ;4 bytes AWord equ 4 ;2 bytes NextWordequ 6 ;2 bytes
Register A4 points to your global storage area . To store a word into the global “AWord” just use:
move #99, AWord(A4)
To put the value contained in AWord(A4) into Register D2 , use:
move AWord(A4), D2
That’s all folks...
Well, that’s it, I hope you’ve learned something, and I hope to see lots of new Fkeys around!
;File: FkeyTemp.Asm ;------------------------------------------------ ;An Fkey sampler Fkey ;By John Holder 2/8/87 ;Revised 3/29/88 ;------------------------------------------------ IncludeTraps.D IncludeToolequ.D IncludeSysequ.D ;------------------------------------------------ ;Macros to save & restore the registers ;------------------------------------------------ MACRO SaveRegs = movem.lA0-A4/D0-D7,-(SP) | MACRO RestoreRegs = movem.l(SP)+,A0-A4/D0-D7 | ;------------------------------------------------ ;All equates go here ;------------------------------------------------ ;these are offsets into the global storage. ;(a non-relocatable block we created pointed to by A4) ;------------------------------------------------ sfReply equ 0 ;sfreply record GetVRef equ 6 GetVers equ 8 GFileName equ 10 IOParamBlkequ 76;IOparamblock (80 bytes) WindPtr equ 156 ;for our background ;window EventBlkequ 160 ;Event Block what equ 160 ;Event number message equ 162 ;Additional information when equ 166 ;Time event was posted where equ 170 ;Mouse coordinates modify equ 174 ;State of keys and button wWindow equ 176 ;Window pointer Menu1Hndl equ 180 ;handle to our Apple menu Menu2Hndl equ 184 ;handle to our File menu oldMenuBarequ 188 ;handle to applications ;menu TheWindow equ 192 ;for _FindWindow ;event masks for _GetOSEvent mDownMask equ 2 keyDownMask equ 8 ;Menu equates AppleMenu equ 1 ;Apple Menu AboutItem equ 1 FileMenuequ 2 ;File Menu OpenFkeyItemequ 1 QuitItemequ 3 ;------------------------------------------------ ;All FKEY’s must have this FKEY resource header! ;------------------------------------------------ bra.s StartIt ;branch over header dc0 ;flags (not used) dc.b ‘FKEY’ ;resource type dc9 ;Resource ID # dc0 ;version # (not used) ;------------------------------------------------ StartIt SaveRegs ;save regs MACRO subq #4,SP move.l SP,-(SP) _GetPort ;save Port for later _InitCursor;standard arrow cursor ;does application have a menu??? if not, then quit! move.l MenuList,D0 beq NoMenuJump ;no menu, beep & quit! move.l #200,D0 ;200 bytes of storage _NewPtr,CLEAR ;for our globals move.l A0,A4 ;pointer in A4 cmp.l #0,A4 bne.s StorageOk;if not zero, ptr is ok! NoMenuJump bsr Mem_Error;otherwise beep bra No_Mem ;and quit StorageOk bsr SetUpMenus ;set up our menus bsr SetUpWindow;set up background ;window ;------------------------------------------------ MainLoop;standard event loop _SystemTask clr -(SP) move #$0FFF,-(SP) ;event mask pea EventBlk(A4) ;Place to return results _GetNextEvent ;Look for an event move (SP)+,D2 beq MainLoop ;zero if we shouldn’t move What(A4),D0;respond add D0,D0 move EventTable(D0),D0 jmp EventTable(D0) ;jump to appropriate ;routine EventTable dcMainLoop-EventTable ;null event dcMouseDown-EventTable ;mouse down dcMainLoop-EventTable ;mouse up dcKeyDown-EventTable;key down dcMainLoop-EventTable ;key up dcKeyDown-EventTable;auto key dcUpDateJump-EventTable ;update event dcMainLoop-EventTable ;disk event dcMainLoop-EventTable ;activate event dcMainLoop-EventTable ;abort dcMainLoop-EventTable ;network event dcMainLoop-EventTable ;I/O driver event ;------------------------------------------------ SetUpWindow clr.l -(SP) ;for returned pointer clr.l -(SP) ;let Mac make storage pea WindowRect ;windows rectangle clr.l -(SP) ;no title move.b #1,-(SP) ;it is visible move #plainDBox,-(SP) ;Type of window move.l #-1,-(SP);in front move.b #0,-(SP) ;no close box clr.l -(SP) ;refcon zero _NewWindow ;make window! move.l (SP),WindPtr(a4) ;pointer into global _SetPort ;set as the port rts ;------------------------------------------------ SetUpMenus clr.l -(SP) ;get applications menu _GetMenuBar;bar handle for later move.l (SP)+,oldMenuBar(A4) ;restoration! _ClearMenuBar ;clear Apps menu bar ;make all of our menus ;the apple menu clr.l -(SP) move #1,-(SP) pea AppleSymbol _NewMenu move.l (SP)+,Menu1Hndl(A4) move.l Menu1Hndl(A4),-(sp) pea ‘About Fkey Sampler...’ _AppendMenu move.l Menu1Hndl(A4),-(sp) move #2,-(SP) _InsertMenu ;the File menu clr.l -(SP) move #2,-(SP) pea ‘File’ _NewMenu move.l (SP)+,Menu2Hndl(A4) move.l Menu2Hndl(A4),-(sp) pea ‘Open FKEY/F’ _AppendMenu move.l Menu2Hndl(A4),-(sp) pea ‘(-’ _AppendMenu move.l Menu2Hndl(A4),-(sp) pea ‘Quit/Q’ _AppendMenu move.l Menu2Hndl(A4),-(sp) clr -(SP) _InsertMenu _DrawMenuBar ;draw the new menu bar rts UpDateJump bsr UpDateWindow bra MainLoop ;------------------------------------------------ ;This routine keeps our background window (The DeskTop!) ;the same pattern as the current standard desktop! ;------------------------------------------------ UpDateWindow move.l WindPtr(A4),-(SP) ;our background ;window _BeginUpdate ;is kept in WindPtr(A4) move.l WindPtr(A4),-(SP) _SetPort pea PaintRect;the rectangle to paint pea DeskPattern;global var, contains _FillRect;pattern used for desktop move.l WindPtr(A4),-(SP) _EndUpdate rts ;------------------------------------------------ ;A key down event occured, check if the command key was ;down, if not, get the next event! ;------------------------------------------------ KeyDown move Modify(A4),D1 btst #8,D1 ;check command key bit beq MainLoop ;zero if command key ;is not down! clr.l -(sp) move message+2(A4),-(sp) ;put char onto stack _MenuKey ; for _MenuKey move.l (sp)+,D4 ;put result in D4 beq MainLoop ;if zero, no menu equivalent bra WhatMenu ;------------------------------------------------ ;A mousedown event occured, we only check if its in a menu, if ;not then get the next event! ;------------------------------------------------ MouseDown clr -(SP) ;word result move.l where(A4),-(SP) ;where field of ;event record pea TheWindow(A4);returns the window ;pntr the _FindWindow;mouse was clicked in, move (SP)+,D0 ;if it was in one. add D0,D0 move WindowTable(D0),D0 jmp WindowTable(D0) ;jump to appropriate ;routine ;We only use InMenu event! WindowTable dcMainLoop-WindowTable ;In Desk dcInMenu-WindowTable ;In Menu Bar dcMainLoop-WindowTable ;In System Window dcMainLoop-WindowTable ;in Content dcMainLoop-WindowTable ;in drag dcMainLoop-WindowTable ;in grow dcMainLoop-WindowTable ;in go away ;------------------------------------------------ ;The mouse was clicked in the menu bar. ;------------------------------------------------ InMenu clr.l -(SP) move.l where(A4),-(SP) _MenuSelect move.l (SP)+,D4 beq MainLoop ;zero if no item selected ;jump to here after command key down event WhatMenu move.l D4,D6 ;D6 will now have the swap D4; item # D4 will have menu # WhichMenuWasIt cmp #AppleMenu,D4;is it in the apple menu? beq InAppleMenu;if so, go see which item! cmp #FileMenu,D4 ;is it in the File menu? beq InFileMenu bra MainLoop ;where else could it be! InAppleMenu ;in the “Apple” menu cmp #AboutItem,D6 beq DoAbout ;its in the About... Item! bra MainLoop InFileMenu;in the “File” menu cmp #OpenFkeyItem,D6 ;in the OpenFkey Item? beq Open_Fkey;if so go open it! cmp #QuitItem,D6 ;Quit item? beq QuitRoutine;if so go quit bra MainLoop ;------------------------------------------------ ;Show the “About Fkey Sampler...” window ;------------------------------------------------ DoAbout saveregs ;save the registers clr.l -(SP) clr.l -(SP) pea AboutRect move.l #0,-(SP) move.b #1,-(SP) move #1,-(SP) move.l #-1,-(SP) move.b #0,-(SP) clr.l -(SP) _NewWindow ;make a window move.l (SP),A2 ;put pointer into A2 _SetPort ;make it the port move #Monaco,-(SP);Use the Monaco Font _TextFont move #9,-(SP) ;make it 9 point (size) _TextSize pea MyTextBegin;address of “About” Text ;calculate how many chars in text for TextBox move.l #MyTextEnd-MyTextBegin,-(SP) pea TextRect ;rectangle for text move #1,-(SP) ;center justification _TextBox bsr Wait_For_Event ;wait for button/key down move.l A2,-(SP) _DisposWindow ;get rid of the window bsr UnHiliteIt ;go unhilight the menu! move.l WindPtr(A4),-(sp) _SetPort ;reset our old port restoreregs;restore registers bra MainLoop ;go get another event ;------------------------------------------------ ;Wait for mouse or key down event ;------------------------------------------------ Wait_For_Event link A6,#-evtBlkSize ;link, event block size WaitLoop lea -evtBlkSize(A6),A0 ;ptr to event block in A0 moveq #mDownMask!KeyDownMask,D0 ;Event masks in D0 _GetOSEvent beq Clicked ;if zero, time to leave! bra WaitLoop ;loop until event Clicked ;mouse or key clicked! unlk A6;unlink A6 rts ;------------------------------------------------ ;Quitting, dispose of all our storage and menus and return to ;the application that the Fkey was called from! ;------------------------------------------------ QuitRoutine move.l WindPtr(A4),-(SP) ;dump background _DisposWindow ;window move.l Menu1Hndl(A4),-(SP) ;dump our #1 _DisposMenu ;menu move.l Menu2Hndl(A4),-(SP) ;dump our #2 _DisposMenu ;menu _ClearMenuBar ;clear the menu move.l oldMenuBar(A4),-(SP) _SetMenuBar;restore apps menu bar! move.l oldMenuBar(A4),A0 ;dump copy of _DisposHandle ;apps menu handle! _DrawMenuBar ;draw it move.l A4,A0 _DisposPtr ;dump our global ;storage No_Mem move.l #$0000FFFF,D0 ;flush all events _FlushEvents _SetPort ;set original port! restoreregs;restore the registers rts ;return to the application! ;------------------------------------------------ ;Couldn’t allocate space for our global storage area ;just beep & quit! ;------------------------------------------------ Mem_Error move #10,-(SP) _SysBeep rts ;------------------------------------------------ ;Unhilight menu bar after mouse down in a menu item ;------------------------------------------------ UnHiliteIt move #0,-(SP) _HiliteMenu rts ;------------------------------------------------ ;Get a file of type “FKEY”, open its resource fork, and ;execute the Fkey (if there is one) contained in it! ;------------------------------------------------ Open_Fkey saveregs ;save registers move #82,-(SP);coordinates for GetFile move #100,-(SP) ;dialog box clr.l -(SP) ;prompt clr.l -(SP) ;File Filter Proc Pointer move #1,-(SP) ;number of file types pea TypeList ;our type list clr.l -(SP) ;Dialog Hook Proc Pointer pea sfReply(A4);sfreply record move #2,-(SP) ;#2 for SFGetFile _Pack3 ;Call the Get File Pack cmp.b #0,sfReply(A4) beq Cancel ;if user hit cancel, quit! bsr UpDateWindow ;update window before ;opening the Fkey lea IOParamBlk(A4),A2 ;the IO param block clr.l 12(A2) ;zero “ioCompletion” lea GFileName(A4),A0 ;put a pointer to the files move.l A0,18(A2);name into “ioNamePtr” move GetVRef(A4),22(A2) ;”ioVRefNum” move.l A2,A0 ;put param block ptr in A0 _SetVol;set as current volume clr -(SP) ;space for refnum pea GFileName(A4);name of res file to open _OpenResFile ;Open that resource file move (SP)+,D7 ;put result in D7 cmp #-1,D7 ;will be -1 if any ;errors! beq Cancel;if error go to cancel ;this stops resources from being loaded with GetIndResource, ;GetResource or GetNamedResource move.w #0,-(sp) _SetResLoad clr.l -(sp) move.l #’FKEY’,-(sp) move #1,-(sp) _GetIndResource ;get first FKEY resource move.l (sp)+,A3 ;handle into A3 ;Turns Automatic resource loading back on! move.b #1,-(sp) _SetResLoad clr.l -(sp) move.l A3,-(sp) _SizeRsrc move.l (sp)+,D2 ;how big is the resource? cmp.l #-1,D2 ;-1 = no resource beq NotEnoughMem ;no resource error so quit ;do we have enough memory to load the FKEY move.l D2,D0 _NewHandle move.l A0,A1 cmp.l #0,A1 ;was zero returned? beq NotEnoughMem ;not enough room, so quit! _DisposHandle ;otherwise dispose the new ;handle, and go on.. move.l A3,-(sp) _LoadResource ;Load resource into memory! clr -(sp) move.l A3,-(SP) _HomeResFile ;what resource file move (sp)+,D2 ;is this resource from? cmp D2,D7 ;is it from new file? beq YepItsFromNewFile ;yep! bra NotEnoughMem ;if not, close the res ;file and quit! YepItsFromNewFile move.l A3,A0 _Hlock ;Lock it before jumping to it move.l (A3),A2 ;put pointer to FKEY in A2 SaveRegs ;save the regs jsr (A2);Run the Fkey!! RestoreRegs;restore the regs move.l A3,A0 _HUnlock ;UnLock FKEY handle bsr CloseIt ;go close res file Cancel restoreregs;restore the regs bsr UnHiliteIt ;unhilight the menu bra MainLoop ;get the next event NotEnoughMem bsr CloseIt bra Cancel CloseIt move D7,-(SP) _CloseResFile ;Close the res file rts ;------------------------------------------------ ;All constants go here ;------------------------------------------------ ;rect of background (desktop) window ;make it giant to cover entire background! WindowRectdc0,0,4000,4000 PaintRect dc0,0,4000,4000 TypeListdc.b‘FKEY’ .ALIGN 2 ;rect of “About...” window AboutRect dc130,100,190,412 ;rect text will be displayed in for _TextBox TextRectdc10,10,90,302 AppleSymbol dc.b 1,$14 ;apple symbol for menu #1 .ALIGN 2 MyTextBegin dc.b ‘Fkey Sampler 1.0’,$0D,$0D dc.b ‘Written by John Holder’ .ALIGN 2 MyTextEnd END ;The Linker file (file name FkeyTemp.Link) ] FKEYTemp /Output FkeyTemp.Code /Type ‘TEMP’ $ *The RMaker file (file name FkeyTemp.R) Fkey Sampler.Fkey FKEYQD15 TYPE FKEY = PROC Fkey Sampler,9 FkeyTemp.Code
![](/file/12652/www.mactech.com.tar/www.mactech.com/sites/all/themes/custom_front/img/search_text.gif)
- SPREAD THE WORD:
- Slashdot
- Digg
- Del.icio.us
- Newsvine