{ -----------------------------------------------------------------------------

                                 NOTICE:

      THESE MATERIALS are UNSUPPORTED by OSS!  If you do not understand how to
      use them do not contact OSS for help!  We will not teach you how to 
      program in Pascal.  If you find an error in these materials, feel free
      to SEND US A LETTER explaining the error, and how to fix it.

      THE BOTTOM LINE:

         Use it, enjoy it, but you are on your own when using these materials!


                               DISCLAIMER:

      OSS makes no representations or warranties with respect to the contents
      hereof and specifically disclaim all warranties of merchantability or
      fitness for any particular purpose.   This document is subject to change
      without notice.
      
      OSS provides these materials for use with Personal Pascal.  Use them in
      any way you wish.

   -------------------------------------------------------------------------- }


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 ;         { The 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.
      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
                BEGIN
                  window := No_Window
                END ;
            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 ;
        { You should 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.