Definition Routines
Volume Number: 2
Issue Number: 7
Column Tag: Pascal Procedures
Introduction to Definition Routines 
By Darryl Lovato, Lovato Programming, Salt Lake City, UT
This is the first of a series of articles which will cover Macintosh Definition
Routines. I will use TML Pascal for all the programming examples because it is rapidly
becoming the most popular Development System on the Mac, and because the new TML
linker will allow you to create procedure resources (MDEF's PROC's WDEF's FKEY's
ect.) quickly and efficiently.
This month I will cover the issues in common to all the different types of
definition routines. In the following months I will cover Menu definition routines
(MDEF's), Window definition routines (WDEF's), Control definition routines
(CDEF's), List definition routines (LDEF's), and function key routines (FKEY's) in
depth.
Defintion routines allow you to create a variation of a standard type of "Object
to better fit your needs. That is, they effect the general appearance and behavior of
whatever they define. The pattern selection Menu in MacDraw is a good example of this.
Definition routines are usually stored as resources but they may also be set up as
routines within your program.
The best way to develop a Definition Routine is to make it a routine in your code,
and when its finished, to compile it into a resource which can then be used with any
application. The Menu, Window, Contol, and List managers all allow you to use
definition routines.
Fig. 1 A non-standard Menu Item
Getting a Handle On Things
When you create a new object (menu, window ect.), you can specify a
non-standard definition routine (a routine other than the normal Mac ROM way of doing
something) for it to use. There are two ways of doing this.
1. By making the procedure a resource in a seperate file.
An example of this process for a non-standard menu follows. Listing #1 is the
code that creates the Menu Definition Resource and listing #2 shows how to use it.
{---------listing fragment #1 the resource def program-------}
{must be compiled with the DeskAcc option checked}
program TheMDEFProc;
{pascal directive to create a MDEf resource}
{---> $C type id [attribute] [name] <---}
{$C 'MENU' 256 4 'TheMDEFRes'}
var { no globals allowed }
procedure theMDEFProcedure(...);
begin
{ code to impliment the Menu Def }
end;
begin {no main program allowed}
end.
{------listing fragment #2 the program that uses the res-----}
program UseTheMenu;
{$L TheMDEFProc} {link the file we created above}
{it includes the menu def we created}
Two methods can be used to put a handle to your MDEF resource in the MenuProc
field of the menu.
(1) In the menu resource, change the menuID field to the resource id of your
MDEF. Then,when you call the GetMenu function, the Menu Manager will
automatically read the MDEF resource from the resource file, and place a handle
to it in the MenuProcField of the menu
(2) If you create the menu (or window) by any means other than reading a
resource (by calling NewMenu, for instance), you must get a handle to the MDEF
by executing the following code:
MyMenuHand := NewMenu(100,'menuTitle');
myProcHdl := GetResource('MDEF',256);
MyMenuHand^^.menuProc := myProcHdl;
2. By putting the proc in your code and creating a handle to it.
First get a handle to your object, by calling NewMenu or GetNewMenu. Then get a
handle to the definition routine, which may be part of your code, and shove it into the
MenuProc field of your objects record. An Example of this method follows:
var
myMenuHdl : MenuHandle;
procedure TheMenuProc(...);
begin
.
.
.
end;
.
.
.
myMenuHdl := GetNewMenu(...);
myMenuHdl^^.menuProc := NewHandle(0);
myMenuHdl^^.menuProc^ := Ptr(@TheMenuProc);
Fig. 2 A non-standard window definition
Things to Come
All of the definition routines are passed a message which tell them what kind of
action the are to do. Typical actions are Initialize, Draw, Select, Drag, Size, ect. A
brief introduction to the individual definition routines we will cover in the in the next
couple of months follow:
Menu Defintion Procedure
The menu definition procedure has the following Pascal definition:
procedure MyMenu(message : integer;
theMenu : MenuHandle;
var menuRect : Rect;
hitPt : Point;
var whichItem : Integer);
The message parameter tells you what kind of action to take, it may be one of the
following values:
mDrawMsg
If the menu definition procedure is passed this value it should draw theMenu
inside menuRect.
mChooseMsg
If the menu definition procedure is passed this value it should hilite the item
which hitPt is in, unhilite the old item, and return the new item in whichItem.
mSizeMsg
If the menu definition procedure is passed this value it should calculate the width
and height of the menu and put the results in theMenu^^.width and theMenu^^.height
respectively.
Window Defintion function
The window definition function has the following Pascal definition:
function MyWindow(varCode : integer;
theWindow : WindowPtr;
message : integer;
param : LongInt)
: LongInt;
The message parameter tells you what kind of action to take, it may be one of the
following values:
wDraw
If the window definition function is passed this value it should draw the window
frame. Before doing this, however, the routine should check to see if the window frame
should show hiliting, if the window is visible, if the window has a go-away box, ect.
wHit
If the window definition function is passed this value it should inspect param,
which is the point where the mouse was pressed. Then it should check to see if the point
is in one of the windows regions, such as the GoAway region, and return the appropriate
result.
wCalcRgns
If the window definition function is passed this value it should calculate the
windows current structure and content regions and store the results in the window
record.
wNew
If the window definition function is passed this value it should perform any extra
initialization and allocation it may require.
wDispose
If the window definition function is passed this value it should perform any
additional disposal actions which it may require. This message "Undo's" whatever was
done in the wNew routine.
wGrow
If the window definition function is passed this value it should draw a grow image
of the window to fit the given rectangle. This operation is called repeatedly when the
user drags inside the grow region.
wDrawGIcon
If the window definition function is passed this value it should draw the size box
icon in the window.
Control Defintion Function
The control definition function has the following Pascal definition:
function MyControl(varCode : integer;
theControl : ControlHandle;
message : integer;
param : LongInt)
: LongInt;
The message parameter tells you what kind of action to take, it may be one of the
following values:
drawCntl
If the control definition function is passed this value it should draw all or part of
theControl.
testCntl
If the control definition function is passed this value it should test where the
mouse button was pressed.
calcCRgns
If the control definition function is passed this value it should calculate the
control or its indicators regions.
initCntl
If the control definition function is passed this value it should do any extra
initialization actions it needs to perform.
dispCntl
If the control definition function is passed this value it should take any additional
disposal actions.
posCntl
If the control definition function is passed this value it should reposition the
controls indicator, and update it.
thumbCntl
If the control definition function is passed this value it should calculate
parameters for dragging indicator.
dragCntl
If the control definition function is passed this value it should drag the control or
its indicator.
autoTrack
If the control definition function is passed this value it should execute the
control's action procedure.
List Defintion Procedure
The list definition procedure has the following Pascal definition:
procedure MyList(lmessage : integer;
lSelect : Boolean;
lRect : Rect;
lCell : Cell;
lDataOffset : integer;
lDataLen : integer;
lHandle : ListHandle);
The message parameter tells you what kind of action to take, it may be one of the
following values:
lInitMsg
If the list definition procedure is passed this value it should do any additional list
initialization.
lDrawMsg
If the list definition procedure is passed this value it should draw the cell.
lHiliteMsg
If the list definition procedure is passed this value it should invert the cell's
highlite state.
lCloseMsg
If the list definition procedure is passed this value it should take any additional
disposal actions.
A Warning From Apple
Apple has stated, "For the convienience of the application's user, remember to
conform to the Macintosh User Interface Guidlines as much as possable". I agree
totally. So don't make a round menu or a window in the shape of a Apple. (I've already
done them both anyway!) [Wow! How about publishing the Apple window? -Ed.]