Volume FKEY--Dialog Lists in Memory

By John Holder, Eureka, CA

What’s the deal here anyway?

My first article for MacTutor™ showed you how to create an Fkey that used its own menus and acted just like an application (refer to MacTutor™ Vol.4 No.6). This article will show you how to create a very simple FKEY using a dialog to allow you to change the volume level of the Macintosh speaker. It also shows how to create a Dialog ITem List (the data normally stored in a DITL resource) in memory so your FKEY doesn’t need any other resources.

How do I use this thing?

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 ‘Volume-Fkey.Asm’, then run the linker on the file ‘ Volume-Fkey.Link’, and finally run RMaker on the file ‘ Volume-Fkey.R’. You will now have an FKEY ready to put into your System file!

Volume-Fkey, How it Works

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. When we’ve successfully allocated storage for the FKEYs globals and room for the dialog item list handle, we get the current value of the speakers volume by getting the low 3 bits of the global variable ‘sdVolume’ (a byte) and putting the value in our own global CurrentVol(A4).

Now we jump to a routine that puts the data (defined as contants at the end of the code) into our item list handle. Now the dialog is created and the handle to our item list is passed to the _NewDialog routine which draws the dialog and all of the items in the list. Then we want to set the appropriate radio button depending on the current volume level. We do this by adding 3 (the item number of the first radio button) to the current volume level to determine which radio button to hilight and call _SetCtlValue to set it. Now, it’s onward to the main loop!

The Main Loop

Since we’re using a dialog we can let _ModalDialog handle all the events for us. All we have to do is wait for _ModalDialog to return an item number and jump to an appropriate routine to handle it. If the Enter or Return key is pushed _ModalDialog returns item number 1, which is the default button in a dialog and in this case is the Quit button.

A click in a radio button

We’ve spotted a click on one of the radio buttons! So we put the item hit in register D7 for safekeeping and jump to a routine to handle changing the volume. We clear all the radio buttons (makes it a bit easier than remembering what the last hilighted button was, guess I’m kind of lazy) and then hilight the one clicked on. Now we take it’s item number and subtract 3 from it to figure the new volume level.

The next step is to change the low order 3 bits of three different variables which the Mac stores the sound level in (each one is a byte) without disturbing any other data in the other bits of the byte. These are; ‘sdVolume’, ‘SPVolCtl’ and the VIA data register A (you get at this by getting the base address of the VIA and adding the offset vBufA to it to access the byte containing the sound volume level, see Inside Mac, Vol. III-21 & III-39).

When those are set we call _WriteParam to write the new volume level to the clock chip, beep the speaker and return to the main loop!

A click in the Info button

When the mouse is clicked in the “Info” button, we change the dialogs font to 9 point Monaco with _TextFont and _TextSize. Now we set up the stack to call _TextBox to display the Info text (which is defined at the end of the code between ‘AboutTextBegin’ & ‘AboutTextEnd’ which makes it very easy to add or change any message you’d like to have displayed when the Info button is clicked). _TextBox calls _EraseRect which temporarily clears the dialogs window before displaying the text. We simply wait for a button or key down event and erase the window, reset the dialogs font and call _DrawDialog to redraw all the controls in the dialog and return to the main loop.

Doing the Quit

When an Fkey quits it must dispose of any memory it created. After the dialog is disposed of with a call to _DisposDialog (which in turn releases the memory we allocated for the item list), 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!

The Dialog Item List

I’ve defined my Item List at the end of the source file as constants. Basically there’s a word at the beginning of the item list which tells how many items are in the list (-1). After that, each item in the list is defined, the first long word is a space reserved for the controls handle when it’s created, the next 4 words are the items rectangle in local coordinates, then a byte defining the control type, a byte (which must be even) which tells how many bytes are in the last field (which is the Title of the control).

When creating your own item list you must make sure the Title of each control has an even amount of bytes (each of mine is four bytes long except the last item, the Volume-Fkey string) and that you make sure to allocate enough memory for your item list by setting the BytesInItemList equate near the beginning of the code. For more information on the format of an Item List refer to Inside Mac Vol. I-427.

Final Comments...

If there’s anything I haven’t explained fully just take a look at the source code as I’ve commented it quite well. You should always take the time to comment your code AS you’re coding! You wouldn’t want to take a look at your code later and ask yourself what the heck you were doing would you? Well, that’s it, I hope you’ve learned something useful from this article. See you next time...

;File: Volume-Fkey.Asm
;------------------------------------------------
;An FKEY that lets you change the speakers volume
;© 1989 by John Holder for MacTutor
;By John Holder Thu May 4, 1989
;------------------------------------------------
;The purpose of this Fkey is to show how to set-up & use
;an item list in memory for a dialog (instead of using a 
;DITL resource) and to show how to check and set the Macs
;speaker volume
 INCLUDETraps.D
 Include ToolEqu.D; Use ToolBox equates
 IncludeSysEqu.D ; Use System equates
;some useful macros
MACRO MakePointerHowManyBytes,StorageRegister =
 MOVE.L #{HowManyBytes},D0
 _NewPtr,CLEAR
 MOVE.L A0,{StorageRegister}
 |
MACRO MakeHandle HowManyBytes,StorageRegister =
 MOVE.L #{HowManyBytes},D0
 _NewHandle,CLEAR
 MOVE.L A0,{StorageRegister}
 |
MACRO SaveRegs =
 MOVEM.LA0-A4/D0-D7,-(SP)
 |
MACRO RestoreRegs=
 MOVEM.L(SP)+,A0-A4/D0-D7
 |
MACRO beep=
 MOVE.W #10,-(SP)
 _SysBeep
 |
;------------------------------------------------
;All equates go here
;------------------------------------------------
;these are offsets into our global storage.
;(a non-relocatable block we created pointed to by A4)
;------------------------------------------------
EventBlockequ 0
what equ 0 ; Event number
message equ 2 ; Additional information
when equ 6 ; Time event was posted 
where equ 10 ; Mouse coordinates
modify equ 14 ; State of keys and button
TheWindow equ 16; var used by _DialogSelect
windowpointer equ 20; Dialog ptr
ItemListHandle equ 24; Item List handle
ItemHit equ 28 ; word
CurrentVolequ 30; current Volume (byte)
padding equ 31 ; next byte (unused)
DispRectequ 32
ItemNumberequ 40
ItemHandleequ 42
ItemTypeequ 46
MemNeeded equ 100 ;how much memory needed 
 ;for globals
mDownMask equ 2
keyDownMask equ 8
true equ 0100ドル
false equ 0
nilequ 0
;Buttons used in dialog
QuitButtonequ 1
InfoButtonequ 2
ZeroBut equ 3
OneBut equ 4
TwoBut equ 5
ThreeButequ 6
FourBut equ 7
FiveBut equ 8
SixBut equ 9
SevenButequ 10
BytesInItemList equ 300 ;how many bytes we want
 ;allocated for the dialog’s 
 ;item list
SysParamequ 1ドルF8 ;location of copy of Parameter
 ;RAM (PRAM) settings (20 bytes)
 ;used by _WriteParam
SPVolCtlequ 208ドル ;location of the speaker vol.
 ;setting in the copy of PRAM
 ;settings
VIAequ 1ドルD4;contains address of the
 ;VIA buffer
vBufA EQU 1ドルE00;Offset to Buffer A (of the
 ; VIA) (for the sound chip)
;------------------------------------------------
;The start of the Fkey
;------------------------------------------------
JumpIt
 BRA.S Start ;Jump the FKEY header info
 DC.W 0 
 DC.B ‘FKEY’ 
 DC.W 7 ;(FKEYs res id#)
 DC.W 0 
Start
 SaveRegs
 ;save current port
 SUBQ #4,SP
 MOVE.L SP,-(SP)
 _GetPort
 _InitCursor
 ;allocate storage for our globals
 MakePointerMemNeeded,A4
 cmp.l #0,A4 ;if returned ptr is not
 bne.s Pointer_Is_Fine ;zero it was allocated ok
 ;not enough mem if it gets here, so beep & quit
 bsr Theres_Been_an_Error
 bra No_Mem_Must_Quit
Pointer_Is_Fine ;will get here if pointer was allocated!
 ;set up storage for our dialogs Item List
 MakeHandle BytesInItemList,ItemListHandle(A4)
 cmp.l #0,ItemListHandle(A4) ;if returned handle
 bne.s Handle_Is_Fine ; is not zero it was
 ;allocated ok
 ;not enough mem if it gets here, so beep,
 ;release global storage we just allocated & quit
 bsr Theres_Been_an_Error
 bra No_Handle_Jump
Handle_Is_Fine ;will get here if handle was allocated!
 ;save current speaker volume level
 ;speaker volume level is store in low
 ;3 bits of global var sdVolume
 move.b sdVolume,D0
 and.b #07,ドルD0 ;clear all but low 3 bits
 move.b D0,CurrentVol(A4)
 bsr ShowDialog
;------------------------------------------------
;The Main loop
;------------------------------------------------
MainLoop
 ;let _ModalDialog handle all events
 clr.l -(sp) ;filter proc
 pea ItemHit(A4);returns dialog item hit
 _ModalDialog
 ;which item was clicked?
 cmp #QuitButton,ItemHit(A4)
 beq QuitRoutine
 cmp #InfoButton,ItemHit(A4)
 beq DoAbout
 ;if it wasn’t on of the two buttons
 ;check for click in the radio buttons
 ;if ItemHit(A4) is < the first radio 
 ;button or > the last one we don’t
 ;handle it
 cmp #ZeroBut,ItemHit(A4)
 blt MainLoop
 cmp #SevenBut,ItemHit(A4)
 bgt MainLoop
 move ItemHit(A4),D7
 bsr ChangeAndBeep
 bra MainLoop ;back to the Main loop
;------------------------------------------------
;Turn on button selected and beep
;------------------------------------------------
ChangeAndBeep
 saveregs
 ;it was a click in a radio button
 ;first, unhilite all the radio buttons!
 bsr Clear_Radio_Buttons
 ;now turn on the one that was clicked on!
 move.l windowpointer(A4),-(SP)
 move D7,-(sp)
 pea ItemType(A4)
 pea ItemHandle(A4)
 pea DispRect(A4)
 _GetDItem
 move.l ItemHandle(A4),-(sp)
 move #1,-(sp)
 _SetCtlValue
 ;calculate new volume setting by which button was
 ;clicked.
 ;button clicked (3-10) - first button (3) = new
 ;volume setting
 move D7,D2
 sub #ZeroBut,D7
 and.b #07,ドルD7 ;clears all but low 3 bits
 ;set the sdVolume global var to sound 
 ;level chosen!
 move D7,D2 ;put new setting into D2
 move.b sdVolume,D1;get current value
 and.b #$F8,D1 ;clears low 3 bits (leaves 
 ;the rest of the sdVolume
 ;bits unchanged)
 or.b D1,D2 ;combine the two
 move.b D2,sdVolume;set the global to new value
 ;save new speaker volume level
 move.b sdVolume,D0
 and.b #07,ドルD0 ;clear all but low 3 bits
 move.b D0,CurrentVol(A4)
 ;set the SPVolCtl (part of Parameter RAM vars kept
 ;in low memory globals)
 move D7,D2 ;put new setting into D2
 move.b SPVolCtl,D1;get current value
 and.b #$F8,D1 ;clears low 3 bits (leaves 
 ;the rest of the SPVolCtl
 ;bits unchanged)
 or.b D1,D2 ;combine the two
 move.b D2,SPVolCtl;set the global to new value
 ;last, set the VIA Buffer A global var
 ;to sound level chosen (this is the sound
 ;chip buffer A)
 move D7,D2 ;put new setting into D2
 move.l VIA,A0 ;pointer to Vbase
 move.b vBufA(A0),D1 ;get current value
 and.b #$F8,D1 ;clears low 3 bits (leaves 
 ;the rest of the
 ;bits unchanged)
 or.b D2,D1 ;combine the two
 move.l VIA,A0 ;pointer to Vbase
 move.b D1,vBufA(A0) ;set the global to new value
 ;now change parameter RAM
 ;Saves settings in clock chip
 lea SysParam,A0
 move.l minusOne,D0
 _WriteParam
 beep ;beep to hear new setting
 restoreregs
 rts
;------------------------------------------------
;Do about (info button was pushed)
;------------------------------------------------
DoAbout
 saveregs
 ;set to Monaco 9pt
 MOVE.W #Monaco,-(SP)
 _TextFont
 MOVE.W #9,-(SP)
 _TextSize
 ;use _TextBox to show About info
 pea AboutTextBegin
 MOVE.L #AboutTextEnd-AboutTextBegin,-(SP)
 PEA TextRect
 MOVE.W #0,-(SP) ;left justification
 _TextBox
 bsr Wait_For_Event ;wait for mouse or
 ;key click
 ;erase About text
 pea TextRect
 _EraseRect
 ;restore normal text attributes for the dialog
 MOVE.W #0,-(SP) ;0 = systemFont
 _TextFont
 MOVE.W #12,-(SP);12 point
 _TextSize
 ;redraw the dialog to show all controls
 move.l windowpointer(A4),-(sp)
 _DrawDialog
 restoreregs
 BRA MainLoop
;------------------------------------------------
;Quit, rel6.5 Volume FKEY
;--------------------------------------------
QuitRoutine
 ;This will also dispose of the handle
 ;we created for the item list so we dont
 ;have to
 MOVE.L windowpointer(A4),-(SP)
 _DisposDialog
No_Handle_Jump
 move.l A4,A0
 _DisposPtr
No_Mem_Must_Quit 
 MOVE.L #0000ドルFFFF,D0
 _FlushEvents ;flush of all events
 _SetPort ;restore port
 restoreregs
 rts
Theres_Been_an_Error ;will jump here if space
 ;couldn’t be allocated!
 beep
 Rts
;------------------------------------------------
;Set up the dialog
;------------------------------------------------
ShowDialog
 saveregs
 bsr SetUpItmList
 ;create the dialog
 CLR.L -(SP) ;For ptr
 clr.l -(SP) ;dialog storage
 pea WindowRect ;rect of dialog
 clr.l -(sp) ;title
 MOVE #true,-(SP);vis
 MOVE.W #dboxproc,-(SP)
 MOVE.L #-1,-(SP);behind wind ptr
 MOVE #false,-(SP) ;goaway
 clr.l -(sp) ;refcon
 move.l ItemListHandle(A4),-(sp) ;handle to item list
 _NewDialog
 MOVE.L (SP),windowpointer(A4) ;leave ptr on stack
 _SetPort
 bsr SetUpControl ;show current vol. level
 restoreregs
 rts
;------------------------------------------------
;Set up our item list
;------------------------------------------------
SetUpItmList
 ;blockmove our item list into space we
 ;allocated for it at the beginning
 move.l ItemListHandle(A4),A0
 _HLock ;dont want it
 ;moving!
 lea ItmList,A0 ;from ptr
 move.l ItemListHandle(A4),A1
 move.l (A1),A1
 move.l #BytesInItemList,D0 ;lgth of data
 _BlockMove
 move.l ItemListHandle(A4),A0 ;unlock it
 _HUnLock
 rts
;------------------------------------------------
;Turn on button (depending on the current volume)
;------------------------------------------------
SetUpControl
;depending on the value of sdVolume, turn on the appropriate
;radio button!
 saveregs
 clr D6
 move.b CurrentVol(A4),D6
 add #ZeroBut,D6;make volume level
 ;correspond to a button
 ;in the dialog
 move.l windowpointer(A4),-(SP)
 move D6,-(sp)
 pea ItemType(A4)
 pea ItemHandle(A4)
 pea DispRect(A4)
 _GetDItem
 ;turn on the button
 move.l ItemHandle(A4),-(sp)
 move #1,-(sp)
 _SetCtlValue
 restoreregs
 rts
;------------------------------------------------
;Wait for key or mouse press
;------------------------------------------------
Wait_For_Event
 LINK A6,#-evtBlkSize
Here 
 LEA -evtBlkSize(A6),A0
 MOVEQ #mDownMask!KeyDownMask,D0
 _GetOSEvent
 BEQ M_Down
 BRA Here;keep looping until mouse press!
M_Down
 UNLK A6
 rts
;------------------------------------------------
;Clear all radio buttons
;------------------------------------------------
Clear_Radio_Buttons
 ;Unhilite all the radio buttons!
 saveregs
 move #7,D7 ;how many times to loop
 ;(8 buttons -1 for dbra)
 move #ZeroBut,D6;button to clear
Clear_Loop
 move.l windowpointer(A4),-(SP)
 move D6,-(sp)
 pea ItemType(A4)
 pea ItemHandle(A4)
 pea DispRect(A4)
 _GetDItem
 move.l ItemHandle(A4),-(sp)
 move #0,-(sp)
 _SetCtlValue
 add #1,D6 ;inc. dialog item counter
 dbra D7,Clear_Loop
 restoreregs
 rts
;------------------------------------------------
;Constants
;------------------------------------------------
WindowRectDC.W 105,145,265,365
TextRectDC.W5,5,150,215 ;for About info
;Item list of our dialog (this data
;get copied into a handle
ItmList dc10;number of items in list - 1
 dc.l 0 ;place for handle
 dc130,40,150,95 ;item rect
 dc.b btnCtrl+4 ;Item type (Button Ctrl)
 dc.b 4 ;length of following data
 dc.b ‘Quit’;Title
 dc.l 0 
 dc130,125,150,180 
 dc.b btnCtrl+4 
 dc.b 4 
 dc.b ‘Info’
 dc.l 0 
 dc30,30,45,70 
 dc.b radCtrl+4 ;(Radio Button Ctrl)
 dc.b 4 
 dc.b ‘0 ‘; 0 + 3 spaces (same with
 ;all radio buttons below)
 dc.l 0 
 dc50,30,65,70 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘1 ‘
 dc.l 0 
 dc70,30,85,70 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘2 ‘
 dc.l 0 
 dc90,30,105,70 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘3 ‘
 dc.l 0 
 dc30,150,45,190 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘4 ‘
 dc.l 0 
 dc50,150,65,190 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘5 ‘
 dc.l 0 
 dc70,150,85,190 
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘6 ‘
 dc.l 0 
 dc90,150,105,190
 dc.b radCtrl+4 
 dc.b 4 
 dc.b ‘7 ‘
 dc.l 0 
 dc5,62,15,170 
 dc.b statText 
 dc.b 12
 dc.b ‘Volume-Fkey ‘ ; Volume-Fkey + 1 space
EndItmList
AboutTextBegin 
 dc.b ‘ Volume-Fkey (1.0)’,0ドルD
 dc.b ‘ (c) 1989 by John Holder’,0ドルD
 dc.b ‘ for MacTutor™’,0ドルD,0ドルD
 dc.b ‘ This Fkey lets you change the speaker volume. ‘
 dc.b ‘Click on a button to set the volume.’
 .ALIGN 2
AboutTextEnd
 END
* File: Volume-Fkey.R
* RMaker source file
* for Volume-Fkey FKEY
MDS1:Volume-Fkey.Fkey
FKEYSPFK
TYPE FKEY = PROC
Volume-Fkey,7
MDS2:Volume-Fkey.Code
; File: Volume-Fkey.Link
; Linker source file
; for Volume-Fkey
/Output Volume-Fkey.Code
/Type ‘TEMP’
Volume-Fkey
$