maker@dartvax.UUCP (Steve Maker) (03/06/85)
{%describe 'a Skeleton demo program'}
{$X-} {Turn automatic run-time stack expansion off - it's a Lisa concept.}
{$R-} {Turn off range checking; it can cause crashes.}
PROGRAM Skel;
{ By Steve Maker
Academic Computing
Kiewit Computation Center
Dartmouth College
July 14, 1984
Copyright notice:
SKEL may be copied and used by anyone, so long as that use
is not for commercial purposes. Please send significant changes
back to me so that I may incorporate them into future versions.
Why SKEL?
Skel is a skeleton demo program. Its purpose is to illustrate
in a clear fashion, isolated from any particular application,
the basic code for handling a simple Macintosh user interface.
It strives to be correct as far as it goes, without many short-cuts
that would lead to trouble in larger applications.
I think of SKEL as a program that does nothing, but does it well.
What does SKEL do?
It handles:
Events, carefully handling only those which are its
business, and passing the others on to their
respective handlers.
A Window, which is filled with Dark Gray, and can be
activated or inactivated, updated, dragged
and grown but NOT scrolled or closed.
Menus, including the Apple Menu. An "About Skel" menu entry
is provided. A File menu offers Rattle and Frighten,
which just invoke dialog boxes, and Quit. Command
key equivalents are supported.
The Desk Accessories, supported in the Apple menu,
and correctly meshed with the other features.
NOT supported are Undo, Cut, Copy, Paste and Clear
(and keyboard equivalents) for desk accessories.
A Modal Dialog Box, used to communicate with the user.
Special icons for the application and its related files.
The Finder information (in the resource file).
In accordance with Macintosh guidelines, everything possible is
kept in the resource file: window description, menus,
dialog specification, and the "About Skel" and other strings.
In addition, the resource file handles the Bundle, File References,
and Icons that determine what Skel's icon looks like, and other
information for the Finder.
How do I use SKEL?
Study it. Modify it to test your knowledge. Steal working
pieces of code for your own programs. Beat on it. Subject
it to cruel and unusual experiments. Pay heed to its warnings.
What do I study first in SKEL?
Initially you should ignore several sections of SKEL, and the calls
made to them. I recommend X-ing them out in your listing.
The sections to ignore on the first round of study are:
Report: ignore the implementation
SetUpMemory: ignore all of it
DrawWindow: ignore the scroll bar and grow icon handling
ReSize: ignore all of it
DoCommand: ignore the Desk Accessory handling in the Apple Menu
MainEventLoop:
MouseDown handling: ignore inSysWindow, inDrag, inGrow
keyDown, autoKey handling: ignore this.
In the resource definition file, SKELR:
Finder information (offset by asterisks):
ignore this whole section, icons and all.
What should I read in Inside Macintosh?
You should read the following sections of Inside Macintosh,
in the order given. At first, just lightly skim the sections
with parenthesized names. Read the others in some depth. Read
the starred (*) ones in great detail. Eventually, you will have
read all sections thoroughly, and many many times, I promise you.
To start:
* Inside Macintosh: A Road Map
(User Interface Guidelines)
Structure of a Macintosh Application
* Putting Together a Macintosh Application
Then, (low-level sections are listed first):
* Memory Mgr Intro
(Memory Mgr)
* Resource Mgr (through "Using the Resource Mgr")
* QuickDraw
(Desk Mgr)
* Event Mgr (through "Event Mgr routines")
Window Mgr
Menu Mgr
(Dialog Mgr)
How do I get SKEL to run?
The best way is to use the special EXEC file SKELX, and insert a
Macintosh diskette into your Lisa. SKELX will write on it with
MacCom, and will set all info correctly so that the icon will appear.
You may also use Apple's EXEC file, or the Dartmouth exec files
T/EXEC or M/MACCOM. The first two will not set the icon correctly,
while M/MACCOM will do that right, and also refrain from recompiling
or repeating other steps if they are unnecessary.
What are the funny % describes for?
They are formatting commands for a Pascal formatter used at Dartmouth
on Lisa Pascal code, for producing a readable listing.
What is the history of SKEL?
v1.0 July 14, 1984 sm: major revision of earlier version
Sept 30, 1984 sm: used \14 for apple symbol in res. file,
bracketed OpenDeskAcc with Get and SetPort,
Oct 11, 1984 sm: changed FREF, BNDL resources from HEXA
to readable,
nested some routines in SKEL,
added constants for FILE menu items,
v2.0 Nov 12, 1984 sm: made resources pre-loaded and/or purgeable,
turned off range-checking,
documented no Resume proc passed to InitDialogs,
added SetUpMemory:
calls MoreMasters, MaxApplZone,
sets the NIL address to -1,
lots of general memory doc.
added a warning about passing doubly-
dereferenced handles,
removed en/disabling of Rattle and Frighten items,
v2.1 Dec 4, 1984 sm: added menu key handling,
put Rattle and Frighten strings in res file,
rewrote intro documentation
v2.2 Mar 6, 1985 sm: converted to % describes,
fixed SKELX for both 2.0 and 3.0 workshop,
set the event mask
}
{%describe '(declarations)'}
USES {$U-} {Turn off Lisa libraries}
{$U Obj/MemTypes } MemTypes, {use type defs in MemTypes unit}
{$U Obj/QuickDraw } QuickDraw, {Search "Obj/Quickdraw" for }
{$U Obj/OSIntf } OSIntf, { the "QuickDraw" unit, etc.}
{$U Obj/ToolIntf } ToolIntf,
{$U Obj/PackIntf } PackIntf, {these are not needed for SKEL,}
{$U Obj/Sane } Sane, { but may be useful later.}
{$U Obj/Elems } Elems, {Assume normal SANE, not SANELIB}
{$U Obj/Graf3D } Graf3D,
{$U Obj/MacPrint } MacPrint;
CONST
lastMenu = 2; { number of menus }
appleMenu = 1; { menu ID for desk accessory menu }
fileMenu = 2; { menu ID for File menu }
iRattle = 1; {items in the File menu}
iFrighten = 2;
{--------}
iQuit = 4;
VAR
screenPort: GrafPtr; {a port for the whole screen}
myWindow: WindowPtr; {our one window}
wRecord: WindowRecord; {storage for window record}
dragRect: Rect; {rect to drag within}
growRect: Rect; {bounds for the growth of the windows}
myMenus: ARRAY [1..lastMenu] OF MenuHandle; {our menus}
{%describe 'Print a string in dialog box'}
{############################ Report #################################}
{ We put up a dialog box, show the string, and wait for user to hit OK.}
PROCEDURE Report(reportstr: str255);
CONST RptBoxID = 257; {ID of our report dialog in resource file}
rptText = 2; {Item # of dialog's report text}
VAR
itemhit: INTEGER; {which Item was clicked on (only OK avail)}
ReportPtr: DialogPtr;
BEGIN {Report}
{set text to display}
ParamText(reportStr, '', '', '');
ReportPtr := getNewDialog(RptBoxID, NIL, pointer(-1)); {get from Resource file;
NIL => use heap storage;
-1 => make dlg frontmost}
ModalDialog(NIL, itemHit); {carry out dialog;
NIL => no FilterProc;
return item Hit when done}
DisposDialog(ReportPtr); {release storage and remove dialog from screen}
END; {Report}
{%describe 'Once-only initialization for Skel'}
{############################ SetUp #################################}
{ Initialize our program. It seems best to handle:
Memory inits first, ToolBox inits second, then the program variables' inits.
Note that the order of inits is important; see "Using the Dialog Manager"
in the Dialog Mgr section.}
PROCEDURE SetUp;
CONST
WindowID = 260; {Resource ID for my window}
VAR
screenRect: rect; {size of screen; could be machine-dependent}
{%describe 'SetUps for handling memory'}
{############################ SetUpMemory #################################}
{ This very important set of initializations can be left out of the first
versions of a program. We are making sure that memory is laid out as
we desire, with adequate protection against running out of memory, bad
handles, etc.}
Procedure SetUpMemory;
CONST
maxStackSize = 8192; {max size of stack; the heap gets the rest}
TYPE
loMemPtr = ^longint; {a pointer to low memory locations}
VAR
nilPtr: loMemPtr; {will have value NIL}
stackBasePtr: loMemPtr; {points to current stack base}
BEGIN {SetUpMemory}
{If you define a GrowZone function to handle bad memory problems,
you should define it at the top level (not nested), and set it here.
We don't.}
(* SetGrowZone(@MyGrowZone);
*)
{Place a longint -1 (an odd and therefore illegal address) in the
memory location that would be referenced by an accidentally-NIL
handle, so the error will be caught at handle-reference time (as
an Address error, ID=02) instead of later on.}
nilPtr := NIL;
nilPtr^ := -1;
{If you needed to use an Application heap limit other than the default
(which allows 8K for the stack), you'd set it here, possible using this
technique of explicitly specifying the maximum stack size and allocating
the rest to the heap. Should be independent of memory size. }
stackBasePtr := loMemPtr($908); {CurStackBase from Tlasm/sysequ.text}
SetApplLimit( pointer(stackBasePtr^ - maxStackSize) );
{Expand the application heap zone to its maximum size, without purging
any purgeable resources. This saves memory compactions and heap expansions later.}
MaxApplZone;
{get plenty of master pointers now; if we let the Memory Manager allocate
them as needed, they'd form non-relocatable islands in the heap.}
MoreMasters; MoreMasters; MoreMasters;
{Here you might install bulwarks against running out of memory unexpectedly.
One such (cheesy) technique is to here allocate a large handle, call it
"CheeseBuf", which you can de-allocate in your GrowZone function, when
you must obtain more memory to avoid a crash. While de-allocated,
the program could prevent the user from doing anything requiring memory,
and tell him he must discard windows or some such memory freeing action.
Each time he does so, the program can try to re-allocate CheeseBuf; if it
succeeds, the user can go on doing memory-eating operations.}
END; {SetUpMemory}
{%describe 'Once-only initialization for menus'}
{############################ SetUpMenus #################################}
{ We read in all menus from the resource file, and install them,
and all desk accessories (drivers).}
PROCEDURE SetUpMenus;
VAR
i: INTEGER;
BEGIN {SetUpMenus}
for i := 1 to lastMenu do {get all my menus in}
myMenus[i] := GetMenu(i); {use the fact that our menu ID's start at 1}
AddResMenu(myMenus[appleMenu], 'DRVR'); {pull in all desk accessories }
for i := 1 to lastMenu do
InsertMenu(myMenus[i], 0); {insert menus; 0 => put at end}
DrawMenuBar;
END; {SetUpMenus }
{%describe '(body of SetUp)'}
BEGIN {SetUp}
{init memory layout and protection}
SetUpMemory;
{init QuickDraw, and everybody else}
InitGraf(@thePort);
InitFonts;
InitWindows;
InitMenus;
TEInit;
InitDialogs(NIL); {NIL => no Restart proc; see Dialog Mgr and System Error Handler}
InitCursor;
{Init the system event mask, in case the previous program left it in
a bad state. If you set it non-standard here, FIX IT BEFORE EXITING,
because the Finder (1.1g) does NOT set it.}
SetEventMask(everyEvent - keyUpMask); {standard setting}
{Get the port which is the whole screen, to use when deactivating our window.
This prevents the current grafPort pointer from ever dangling.}
GetWMgrPort(screenPort); {get whole screen port that window mgr uses}
SetPort(screenPort); {and start off with it}
{get window: use wRecord storage. Port is set to that of the new window.
GetNewWindow posts an update event for the new window,
so it will be redrawn right away.}
myWindow := GetNewWindow(windowID, @wRecord, POINTER(-1)); {-1 => frontmost window}
{set up dragRect; we can drag the window within it}
screenRect := screenBits.bounds; {don't assume screen size}
{set drag rect to avoid menu bar, and keep at least 4 pixels on screen}
SetRect(dragRect, 4, 24, screenRect.right-4, screenRect.bottom-4);
{set up GrowRect, for limits on window growing}
SetRect(growRect, 48, 14, screenRect.right-7, screenRect.bottom-7);
{pull in and set up our menus}
SetUpMenus;
END; {SetUp}
{%describe 'Redraw my window'}
{############################ DrawWindow #################################}
{ We draw all the contents of our one window, myWindow. Note that this must include
scroll bar areas and the grow icon; the Window Manager will NOT handle those for us.
Since there are no scroll bars, we must erase the region they would be in. Echh.}
PROCEDURE DrawWindow;
VAR aRect: rect; {rectangle to erase}
BEGIN {DrawWindow}
{first, fill the window with dark gray; this fills scroll bars, too}
FillRect(myWindow^.portRect, dkGray);
{second, erase the scroll bars and draw the grow icon}
{erase the horizontal scroll bar}
SetRect(aRect, {cover the horizontal bar}
myWindow^.portRect.left, myWindow^.portRect.bottom-15,
myWindow^.portRect.right-15, myWindow^.portRect.bottom);
FillRect(aRect, white); {fill with white}
{erase the vertical scroll bar}
SetRect(aRect, {cover the vertical bar}
myWindow^.portRect.right-15, myWindow^.portRect.top,
myWindow^.portRect.right, myWindow^.portRect.bottom-15);
FillRect(aRect, white); {fill with white}
DrawGrowIcon(myWindow); {draw the size box in the corner of the window}
END; {DrawWindow}
{%describe 'Update the contents of the given window'}
{############################ UpdateWindow #################################}
{ This is our response to receipt of an update event for myWindow. Since the
window is likely to be inactive, the current grafPort will be elsewhere. We must
change it for drawing, yet leave it as it was.}
PROCEDURE UpdateWindow(aWindow: WindowPtr);
VAR
savePort: GrafPtr; {to save and restore the old port}
BEGIN {UpdateWindow}
BeginUpdate(aWindow); {reset ClipRgn etc to only redraw what's necessary.}
GetPort(savePort); {don't trash the port; we might be updating an inactive window}
SetPort(aWindow); {work in the specified window}
drawWindow; {redraw contents of window}
SetPort(savePort); {all nice and tidy as before}
EndUpdate(aWindow);
END; {UpdateWindow}
{%describe 'Change the size of the given window'}
{############################ ReSize #################################}
{ Called on a mouse-down in the grow box, this allows the user to change
the size of the window. We change the size, then
claim that the whole of the window contents is no longer validly drawn,
because we're too lazy to do so for just the scroll bar regions
that are actually subject to change. See the Window Manager.}
PROCEDURE ReSize(a_window : WindowPtr; downPt: Point);
VAR w, h : integer; {new width and height of the sized window}
newSize : longint; {the new size}
BEGIN {ReSize}
newSize := GrowWindow(a_window, downPt, growRect); {find new size}
w := LoWord(newSize); {find the width}
h := HiWord(newSize); {find the height}
SizeWindow(a_window, w, h, true); {change to the new window size}
{place whole window into update region to be sure it all gets updated.
This is more than is strictly necessary, but a lot easier than just
invalidating the regions that actually may have changed.}
InvalRect(a_window^.portRect);
END; {ReSize}
{%describe 'the main loop that handles events'}
{############################ MainEventLoop #################################}
{ Brace yourself: here's where the action is. Most Mac programs just wait for events
(as do we all), and then process them. There are two sorts of events: those directly
initiated by the user, like key presses and mouse-downs, and those consequent events
posted by the Event Manager, like update and activate events. The latter MUST be handled
correctly and carefully. In particular, it's important for all events to make sure
that the event occurred in or for the window you expect -- it's possible to get events
which are not for one of our windows, despite GetNextEvent's return value. Similarly,
be sure to check that the window it occured in is the active one, if it matters.
A common mistake in handling update and activate events is in finding out which window
they are for. It is "WindowPtr(myEvent.message)" that gives this information,
NOT "whichWindow" (the WindowPtr returned by FindWindow). The latter pointer merely tells
you what window the mouse was in at the time the event was posted -- completely irrelevant
for Update and Activate events. Think it through carefully.}
PROCEDURE MainEventLoop;
VAR
myEvent: EventRecord;
whichWindow: WindowPtr; {points to window of MouseDown}
windowCode: integer; {what mouse was in when event posted}
userDone: boolean; {true when user wants to exit program}
{%describe 'handle a command given through a menu selection'}
{############################ DoCommand #################################}
{ We carry out the command indicated by mResult.
If it was Quit, we return true, else false. Since the menu was highlighted by
MenuSelect, we must finish by unhighlighting it to indicate we're done.}
FUNCTION DoCommand(mResult: LongInt): boolean;
CONST
AboutSkelId = 1; {Resource ID of the string}
RattleID = 2;
FrightenID = 3;
VAR
refNum: integer;
theMenu, theItem: integer;
name: str255;
savePort: grafPtr; {for saving current port in when opening a desk acc}
aStr: str255; {a utility string}
BEGIN {DoCommand}
DoCommand := false; {assume Quit not selected}
theMenu := HiWord(mResult); {get the menu selected}
theItem := LoWord(mResult); {... and the item of that menu}
CASE theMenu OF
0: ; {user made no selection; do nothing}
appleMenu:
begin
if theItem = 1
then begin; {get string, and tell about Skel}
{It's important not to pass Report a de-referenced handle;
if Report were in another segment, loading it could
caused a memory compaction; the de-referenced handle
could become invalid. Watch out for this and similar
nasties everywhere in your program.
See the Memory Manager and the Segment Loader.}
aStr := GetString(AboutSkelId)^^;
report(aStr);
end
else begin {run a desk accessory; make sure port is preserved}
getPort(savePort);
GetItem(myMenus[appleMenu], theItem, name); {get name}
refNum := OpenDeskAcc(name); {run the desk accessory}
setPort(savePort);
end;
end;
fileMenu:
CASE theItem OF
iRattle: begin; {Rattle}
aStr := GetString(RattleId)^^;
report(aStr);
end;
iFrighten: begin; {Frighten}
aStr := GetString(FrightenId)^^;
report(aStr);
end;
iQuit: DoCommand := true {Quit}
END; {fileMenu case}
END; {menu case }
HiliteMenu(0) {turn off hilighting on the menu just used}
END; {DoCommand }
{%describe '(body of MainEventLoop)'}
BEGIN {MainEventLoop}
FlushEvents(EveryEvent, 0); {discard leftover events}
{get next event, and handle it appropriately, until user QUITs}
userDone := false;
REPEAT
systemTask; {handle desk accessories}
if GetNextEvent(everyEvent, myEvent) {get event; if for us...}
then begin
case myEvent.what of {handle each kind of event}
mouseDown:
begin
{find out what window the mouse went down in, and where in it}
windowCode := FindWindow(myEvent.where, whichWindow);
case windowCode of {handle mouse-down for each place}
inSysWindow: {handle the desk accessories}
SystemClick(myEvent, whichWindow);
inMenuBar: {handle the command}
userDone := DoCommand(MenuSelect(myEvent.where));
inDrag: {drag the window}
DragWindow(whichWindow, myEvent.where, dragRect);
inContent: {includes inGrow if window inactive. Activate window}
if whichWindow = myWindow {moke sure it's for mine}
then if whichWindow <> FrontWindow
then SelectWindow(whichWindow); {make it active}
inGrow: {window is already active; change its size}
if whichWindow = myWindow {moke sure it's for mine}
then ReSize(myWindow, myEvent.where);
inGoAway: {we don't have a GoAway region}
end; {case windowCode}
end; {mouseDown handling}
keyDown, autoKey: {if command key, pass the char to MenuKey}
if BitAnd(myEvent.modifiers, cmdKey) <> 0
then userDone := DoCommand(MenuKey(chr(BitAnd(myEvent.message, charCodeMask))));
updateEvt: {if it's for our window, update it}
if WindowPtr(myEvent.message) = myWindow
then UpdateWindow(myWindow); {redraw the window contents}
activateEvt: {if for our window, set port as nec.}
if WindowPtr(myEvent.message) = myWindow {my window}
then begin
DrawGrowIcon(myWindow); {redraw grow icon to reflect new state}
if odd(myEvent.modifiers) {odd means an activate event}
then SetPort(myWindow) {activate evt: work in our own port}
else SetPort(screenPort); {deactivate evt: our port is gone;
keep port from dangling}
end;
end; {case myEvent.what}
end; {THEN BEGIN for "it's our event"}
UNTIL userDone;
END; {MainEventLoop}
{%describe '(body of Skel)'}
BEGIN {Skel}
SetUp;
MainEventLoop;
END. {Skel}