-*- Mode:TEXT; Fonts:(hl12, hl12B, tr12i, cptfont, cptfontb) -*-



		       Ï1Toolbox Application Writing NotesÏ*
			   Merrill Cornish
        
This is not a tutorial on how to write Macintosh* application using the Toolbox.  Instead, it is a set of 
"extended bullets" commenting on various aspects of the problem.  Most of these points are mentioned in
one or more of the example applications in the microExplorer* public directory.



Ï1APPLICATION INITIALIZATIONÏ*

At the start of most Macintosh applications you will see a standard set of calls to various initialization
functions such as Ï1InitGrafÏ*, Ï1InitFontsÏ*, Ï1InitWindowsÏ*, Ï1InitMenusÏ*, Ï1TEInitÏ*, and Ï1InitDialogsÏ*.  You should
NOT include calls to these traps in your Macintosh applications on the microExplorer since they are done
for you when the Toolbox Server is started up on the Macintosh side.  As a reminder, there are comments
in the manual to the effect that you don't have to execute these traps since all basic initializations are done
for you.



Ï1MENUS and the MENU BARÏ*
        
Many of the things you have come to take for granted about the Macintosh environment appear only
through the cooperation of the application writers.  For example, you-- the Macintosh application
writer--must establish which menus go in the Menu Bar, in which order, and with what names.
Furthermore, you must load up the items in those menus.  For example, if you don't explicitly create an
Apple Menu and then load the desk accessories into it, then your user won't have access to any accessory
while running your application.

References to "toolbox macros" are talking about the macros in the directory "SYS:PUBLIC-MX;".


Ï1The Traditional ApproachÏ*
        
The conventional approach to menu management on the Macintosh is to place an "initialize menus"
functions at the beginning of your application and a "cleanup menus" function at the end.  The main
purpose of the cleanup function is to release the memory being use by the application's menus.  In Lisp,
the cleanup function should always reside in an Ï1unwind-protectÏ* form to assure that cleanup gets run
even if an error is signaled or the user presses the ABORT key during application execution.  For example:
        
	Ï3(unwind-protectÏ*
	Ï3      (prognÏ*
	Ï3        (initialize-menus)Ï*
	Ï3        Ï2... application body...Ï*)Ï*
	Ï3   (cleanup-menus))Ï*

An unfortunate sideeffect of porting this traditional approach directly to the microExplorer is that you end up
with a number of gobal variable and constants defined.  For example,

	Ï3(defvar Ï4FileMenuÏ* nil)Ï*
	Ï3(defconstant Ï4FileIDÏ* 128)
 Ï*       
There is nothing particularly wrong with this approch by itself, but you may be in for some surprised.  In the
C and Pascal worlds (where most Macintosh applications reside now) each program runs in its own
process which has its own virtual address space.  Therefore, it is of no consequence that one application
may define a symbol Ï1FileIDÏ* to be 128 and another application define it to be 130.  

However, in Lisp all functions and even all processes share all global variables.  First of all, if two
different files try to define a constant with the same name, then the compiler will signal an error so
you and I cannot both use Ï1FileIDÏ* as the symbolic menu ID of our file menu.
        
On the other hand, we may not be so lucky as to get a compiler error.  For example, Ï2yourÏ* application may
end up using Ï2myÏ*  application's Ï1FileMenuÏ* menu handle just because we both used the same traditional
name for it.  The problem is that Lisp uses global variables to communicate between functions and
processes while C and Pascal don't.  Porting the C and Pascal traditions directly into Lisp is not the right
thing to do.


Ï1The Toolbox Macro ApproachÏ*

The Public-MX directory contains a file of toolbox macros which allow toolbox programmers to do things in
a more Lisp-like manner.  For example, the Ï1tb:with-menusÏ* macro creates the menus for you, binds them to
handles, during the execution of  the body of the macro and then disposes of the menus upon normal or
abnormal exit.  Furthermore, once the menus are created and you have loaded the menu items into them,
the Ï1tb:with-menu-bar Ï*macro places them into the Menu Bar during exection of the body.  See
EXAMPLE-MENU and EXAMPLE-HMENU in "SYS:PUBLIC-MX;QD-EXAMPLES.LISP".

By using these macros, you avoid the conflict of global variables problem and you are automatically
covered by Ï1unwind-protectÏ*s which guarantee that your menu data structures will be released upon exit.
These macros also subsume a number of indiviual Macintosh traps and conventions.

--------------------------------------------------------
* "Macintosh" is a registered trademark of Apple Computer, Inc.
  "Explorer" and "microExplorer" are trademarks of Texas Instruments.
