mckay@EE.PURDUE.EDU (05/25/86)
These directions are from the OSS bulletin board and include source for a
sample DA. Uuencoded binary for the DA will follow in my next message...
--Dwight Mckay, ECN Text & Workstation Software Support
[arpanet: mckay@ee.ecn.purdue.edu, usenet: ...ihnp4!pur-ee!mckay]
[Compu-serve: 75776,1521, office: EE 348B, phone: (317) 494-3561]
-------------------------------- cut here --------------------------------
WRITING DESK ACCESSORIES USING PERSONAL PASCAL
----------------------------------------------
In order to make a Personal Pascal program into a desk accessory, you must
perform a few operations which are not described in the manual. First of all,
you must make sure your program can be made into an accessory as follows:
1. The start of your program should contain an S0 compiler directive. This
command tells the compiler not to adjust the size of the stack.
2. You should NOT use debug mode. Either change the option setting called
"Full debug mode", or use a D- command along with the S0 command.
3. The value actually returned by the Init_Gem routine is the application
identification number for your program. You must save this number in a
variable, instead of just testing it. Again, look at the sample accessory
for details.
4. Two additional GEM messages are sent to accessories. These messages,
AC_Open and AC_Close, are not declared in the GEMCONST.PAS file. You
should either declare them in your program (as the sample accessory does)
or add them to the GEMCONST.PAS include file. You also must respond to
these messages as shown in the sample accessory.
5. You need to declare one more EXTERNAL function in your desk accessory
program:
FUNCTION Menu_Register( ap_id : integer ; VAR name : Str255 ) : integer ;
EXTERNAL ;
This function already appears in the PASGEM library, but it does not appear
in GEMSUBS.PAS (you can add it there, if you wish). Use the Menu_Register
function to insert the name of your accessory in the "Desk" menu. See the
sample accessory for details.
Next, you need to create a file called PASACC.O by running the MAKEACC.PAS
program listed below. You must enter a valid stack size; although you could
use most any size, we recommend 5 Kbytes. After creating the PASACC.O file,
link your program as follows:
1. You must link PASACC.O as the first link file, not the object file produced
by your Pascal source program. Put the name of your Pascal object program
in the "Additional Link Files" field of the link options dialog box.
2. Select the "Link..." item in the files menu. When the ITEM SELECTOR dialog
appears, select the file PASACC.O-- remember, your program's .O file must
already be in the "Additional Link Files" list!
3. The linker should load and link your program normally. The final output
file will be named PASACC.PRG. Change this to any name, but give it the
extension ".ACC" (this tells GEM to load the accessory upon booting). If
you have an early version of GEM/TOS, you may need to name your file
DESK3.ACC (the earliest version needed the "DESK#" primary name).
4. Copy your accessory file to a backup of your boot disk, and reboot your ST.
The name of your accessory should appear under the "Desk" menu. If you
select your accessory, it should run.
LISTING OF MAKEACC.PAS
----------------------
PROGRAM Make_Accessory ;
VAR
stack_size : Integer ;
answer : STRING ;
PROCEDURE Write_Accstart( size : Integer ) ;
VAR
f : FILE OF integer ;
PROCEDURE Word( w : Integer ) ;
BEGIN
f^ := w ;
put( f ) ;
END ;
PROCEDURE Long( l : Long_Integer ) ;
BEGIN
Word( Int(Shr( l, 16 )) ) ;
word( Int( l ) ) ;
END ;
BEGIN
writeln( 'Opening PASACC.O...' ) ;
rewrite( f, 'pasacc.o' ) ;
writeln( 'Writing data...' ) ;
(* Put out the object file header: *)
Word( $601A ) ;
Long( $14 ) ;
Long( 0 ) ;
Long( size+4 ) ;
Long( 0 ) ;
Long( 0 ) ;
Long( 0 ) ;
Word( 0 ) ;
(* Now the code: *)
Word( $4FF9 ) ; (* lea user_stack,sp *)
Long( size ) ;
Word( $41F9 ) ; (* lea stack_start,a0 *)
Long( 0 ) ;
Word( $2248 ) ; (* movea.l a0,a1 *)
Word( $4EF9 ) ; (* jmp prg_start+12 *)
Long( $20 ) ;
(* Now the relocation information: *)
Word( 7 ) ;
Long( $50003 ) ;
Word( 7 ) ;
Long( $50003 ) ;
Word( 7 ) ;
Word( 7 ) ;
Long( $50002 ) ;
writeln( 'Finished!' ) ;
END ;
BEGIN
REPEAT
write( 'How many Kbytes for desk accessory stack? ' ) ;
readln( stack_size ) ;
write( stack_size:1, ' Kbytes-- is this correct? ' ) ;
readln( answer ) ;
UNTIL (length(answer) > 0) AND ((answer[1] = 'y') OR (answer[1] = 'Y')) ;
IF ((answer[1] = 'y') OR (answer[1] = 'Y')) THEN
Write_Accstart( stack_size*1024 ) ;
END.
LISTING OF ACCDEMO.PAS (SAMPLE ACCESSORY)
-----------------------------------------
(* We don't want any stack (PASACC.O takes care of the stack) and we certainly
shouldn't be in full debug mode! *)
(*$S0,D-*)
PROGRAM Sample_Accessory ;
CONST
(*$I gemconst.pas*)
AC_Open = 40 ; (* Two new messages which only accessories will get. *)
AC_Close = 41 ;
TYPE
(*$I gemtype.pas*)
VAR
window, (* The handle of our window. *)
ap_id, (* Our application identification handle. *)
menu_id : integer ; (* Index of our menu item in "Desk" menu. *)
our_name, (* The name of our accessory. *)
wind_name : Str255 ; (* The title of our window. *)
(*$I gemsubs.pas*)
(* You must declare this function either in your accessory program (as here)
or in the GEMSUBS.PAS file: *)
FUNCTION Menu_Register( id : integer ; VAR name : Str255 ) : integer ;
EXTERNAL ;
(* Open our window, if not already open. If our window IS open already, just
make it the front window. *)
PROCEDURE Do_Open ;
BEGIN
(* Does our window already exist? *)
IF window <> No_Window THEN
Bring_To_Front( window ) (* Yes, just make it front window. *)
ELSE
BEGIN (* No, open a new window. *)
wind_name := ' Accessory Test ' ;
window := New_Window( G_Name|G_Close|G_Size|G_Move, wind_name,
0, 0, 0, 0 ) ;
Open_Window( window, 0, 0, 0, 0 )
END
END ;
(* Close our window and delete it from the system. *)
PROCEDURE Do_Close ;
BEGIN
Close_Window( window ) ;
Delete_Window( window ) ;
window := No_Window
END ;
(* Redraw an area of our window. The area to redraw is passed in the
parameters x0, y0, w0, and h0. For simplicity, we just draw a rectangle
of the same size as the area to redraw and draw an X in it. This is also
interesting to watch since it shows exactly what redraw messages GEM is
sending. *)
PROCEDURE Do_Redraw( handle, x0, y0, w0, h0 : integer ) ;
VAR
x, (* These four variables are used to hold the size of *)
y, (* the current rectangle in the list for our window. *)
w,
h : integer ;
BEGIN
Begin_Update ; (* Tell GEM we are updating, *)
Hide_Mouse ; (* and hide mouse so we don't mess up screen. *)
Paint_Color( White ) ; (* We'll be clearing each rectangle w/ white. *)
(* This loop should look familiar, since it is copied out of the
Pascal manual, p. 5-115, except for correcting a couple of errors! *)
First_Rect( handle, x, y, w, h ) ;
WHILE (w <> 0) AND (h <> 0) DO
BEGIN
IF Rect_Intersect( x0, y0, w0, h0, x, y, w, h ) THEN
BEGIN
(* The only thing that's new is what we're drawing: *)
Set_Clip( x, y, w, h ) ;
Paint_Rect( x, y, w, h ) ; (* First clear to white... *)
Frame_Rect( x, y, w, h ) ; (* Then draw rectangle outline *)
Line( x, y, x+w-1, y+h-1 ) ; (* and two lines to form an X. *)
Line( x+w-1, y, x, y+h-1 )
END ;
Next_Rect( handle, x, y, w, h ) ;
END ;
Show_Mouse ; (* OK, we can redraw the mouse, too, *)
End_Update (* and tell GEM we're finished! *)
END ;
(* This next routine performs all events we receive from GEM. Since we are
an accessory, we will never reach a state where we will stop running, so
the loop below (for each event we get) is infinite! *)
PROCEDURE Event_Loop ;
VAR
event, dummy : integer ;
msg : Message_Buffer ;
BEGIN
WHILE true DO
BEGIN
(* Get one event-- we're only interested in messages. *)
event := Get_Event( E_Message, 0, 0, 0, 0,
false, 0, 0, 0, 0, false, 0, 0, 0, 0,
msg, dummy, dummy, dummy, dummy, dummy, dummy ) ;
CASE msg[0] OF
AC_Open:
IF msg[4] = menu_id THEN (* If our menu item was selected, *)
Do_Open ; (* open the window! *)
AC_Close:
(* If we haven't already closed our window, pretend it's closed
(because GEM is going to close it for us!) Presumably, the
program that was running when we were opened has finished. *)
IF (msg[4] = menu_id) AND (window <> No_Window) THEN
window := No_Window ;
WM_Sized, (* Allow any size or position on the screen. *)
WM_Moved: (* (we really should have a minimum size!) *)
Set_WSize( msg[3], msg[4], msg[5], msg[6], msg[7] ) ;
WM_Closed: (* User wants to close our window-- close it. *)
Do_Close ;
WM_Redraw: (* Need to redraw a portion of our window. *)
Do_Redraw( msg[3], msg[4], msg[5], msg[6], msg[7] ) ;
WM_Topped: (* Aha, user wants us to be front window! *)
Bring_To_Front( msg[3] ) ;
END
END
END ;
(* Main routine-- initialize GEM, then insert our name into the "Desk" menu
and go to our event loop. That routine will NEVER return! That's why we
don't need an Exit_Gem call at the end of the program. *)
BEGIN
ap_id := Init_Gem ; (* We do need to save our application ID... *)
IF ap_id >= 0 THEN (* that's a change from most programs. *)
BEGIN
(* Starting off with no window on the screen: *)
window := No_Window ;
(* Always put two spaces before the name of the accessory: *)
our_name := ' Sample Accessory' ;
(* Here is where we use the application ID number: *)
menu_id := Menu_Register( ap_id, our_name ) ;
Event_Loop ;
END
END.