supermario/bin/MPW-3.2.3/Examples/PExamples/Instructions

Instructions - The Pascal Examples

Copyright Apple Computer, Inc. 1987-1990
All rights reserved.


About the Examples

	Eight sample Pascal programs are included with MPW Pascal: an
	application, a tool, a desk accessory, and a program that
	demonstrates the use of performance tools:
	
		Sample     - a simple MultiFinder-Aware Sample application
		TESample   - a simple MultiFinder-Aware TextEdit application 
		SillyBalls - a simple Color Quickdraw sample application
						   (Requires Color Quickdraw, e.g. MacII)
		TubeTest   - a simple Color Quickdraw & Palette Manager 
							Sample application
							(Requires Color Quickdraw, e.g. MacII)
		ResEqual	  - an MPW tool
		Memory 	  - a sample desk accessory
		EditCdev   - a sample Control Panel Device with a TextEdit item 
		TestPerf	   - a performance demonstration tool

	The source files for each of these examples are in the
	"Examples:PExamples:" folder.  In addition, the makefiles
	containing the commands needed to build each of the
	examples are provided in the same folder.
	

Building the Examples

	You can easily build each of the sample programs using the Directory
	and Build menus.  (See Chapter 2 of the MPW Reference.)
	
	Set the default directory to "PExamples:"

		The simplest way to do this is to select from the Directory menu
		the menu item that ends in "PExamples:".  You can also set the
		default directory by using the Directory and SetDirectory commands.
		

	Build the program
	
		You can use any of the four Build items at the bottom of the Build
		menu to build the program you have selected.  Each of these menu
		items displays a dialog box that asks for the name of the program
		you want to build.  When this dialog box appears, type the name of
		one of the sample programs (Sample, TESample, SillyBalls,
		TubeTest, ResEqual, Memory, EditCdev or TestPerf).
		
		Each of the Build menu items behaves slightly differently:
		
			Build…  -  The program is automatically built.  The commands
			used, and any error messages, are displayed in the Worksheet.
			Only files that have been changed since you last built the
			program are compiled, saving considerable time.
	
			Full Build…  -  The program is completely rebuilt, ignoring
			any object files or intermediate files that may already exist
			from a previous build.  The commands used, and any errors, are
			displayed in the Worksheet.
			
			Show Build Commands…  -  The commands needed to build the program
			are written to the Worksheet, but not executed.  You can then
			select any or all of the commands and execute them yourself.
			(To execute the commands select them and press Enter.)
			
			Show Full Build Commands…  -  The commands needed to completely
			rebuild the program are written to the Worksheet.  This is a
			convenient way to see all of the commands used in building
			the program you have selected.


   Note: For more information about building the sample programs, see
   Chapter 2 of the MPW Reference.



Sample - A Simple MultiFinder-Aware Sample Application

	Sample is an example application that demonstrates how to initialize
	the commonly used toolbox managers, operate successfully under 
	MultiFinder, handle desk accessories and create, grow, and zoom windows.
	The source for Sample (or TESample below) provides an excellent
	framework for basing new applications.
 	The source is contained in the file Sample.p, resource
	descriptions are contained in the files Sample.h and Sample.r.
	The make dependency file is named Sample.make.

   To build Sample, simply select the line below and press Enter.

		BuildProgram Sample ∑∑ {Worksheet}

   To execute Sample, select the line below and press Enter.

		Sample



TESample - A Simple MultiFinder-Aware TextEdit Application

	TESample is an example application that demonstrates how to initialize
	the commonly used toolbox managers, operate successfully under 
	MultiFinder, handle desk accessories and create, grow, and zoom windows.
	The fundamental TextEdit toolbox calls and TextEdit autoscroll are 
	demonstrated. TESample also shows how to create and maintain scrollbar
	controls.
	The source for TESample (or Sample above) provides an excellent
	framework for basing new applications.
	The source is contained in the files TESample.p and TESampleGlue.a,
	resource descriptions are contained in the files TESample.h and
	TESample.r. The make dependency file is named TESample.make.

   To build TESample, simply select the line below and press Enter.

		BuildProgram TESample ∑∑ {Worksheet}

   To execute TESample, select the line below and press Enter.

		TESample



SillyBalls - A Simple Color Quickdraw Sample Application
	
	(Requires Color Quickdraw, e.g. MacII)

	SillyBalls is a very simple sample program that demonstrates 
	how to use Color QuickDraw.  It is about two pages of code, and 
	does nothing more than open a color window and draw randomly 
	colored ovals in the window.
	The purpose is to show how to get some initial results with Color 
	QuickDraw. It is a complete program and is very short to be as 
	clear as possible.
	The source is contained in the files SillyBalls.p.

   To build SillyBalls, simply select the line below and press Enter.

		BuildProgram SillyBalls ∑∑ {Worksheet}

   To execute SillyBalls, select the line below and press Enter.

		SillyBalls



TubeTest - A Simple Color Quickdraw & Palette Manager Sample Application

	(Requires Color Quickdraw, e.g. MacII)

	TubeTest is a simple demonstration of how to use 
	the Palette Manager in a color program.  It has a special color 
	palette that is associated with the main window.  The colors are
	animated using the Palette Manager to give a flowing tube effect.
	The program is very simple, and the Palette Manager and drawing 
	parts are put in separate subroutines to make it easier to figure 
	out what is happening.
	The source is contained in the files TubeTest.p and TubeTest.r

   To build TubeTest, simply select the line below and press Enter.

		BuildProgram TubeTest ∑∑ {Worksheet}

   To execute TubeTest, select the line below and press Enter.

		TubeTest



ResEqual - A Sample MPW Tool

	ResEqual is a sample MPW tool that compares resource files. A
	version of ResEqual is included with MPW, and is documented in
	the MPW Reference.  The source for ResEqual is in the files
	ResEqual.p, FStubs.a, and ResEqual.r.

   To build ResEqual, simply select the line below and press Enter.

		BuildProgram ResEqual ∑∑ {Worksheet}

   To test ResEqual, execute the following lines.

	  # The following three lines copy ResEqual into Dummy and renumbers
	  # one of the resources.
	  Echo "include ∂"ResEqual∂" not 'cmdo';" ∂
	  		 "include ∂"ResEqual∂" 'cmdo' (355) as 'cmdo' (356);" ∂
			 | Rez -o Dummy -t MPST -c 'MPS '
	  ResEqual ResEqual Dummy

   ResEqual should report that each file contains a resource not found
	in the other file.


Memory - A Sample Desk Accessory


   Memory is a sample desk accessory written in Pascal.  It displays the
	memory available in the application and system heaps, and on the boot
	disk.

   To build Memory, simply select the line below and press Enter.

		BuildProgram Memory ∑∑ {Worksheet}

	NOTE: If you don't have the MPW Assembler, you'll need to select the
			line below and press Enter. You won't be able to use SADE to
			debug DA's built without the assembler though...

		BuildProgram Memory.NOASM ∑∑ {Worksheet}
		
   The build process puts the desk accessory into a Font/DA Mover file.
   To install the Memory desk accessory, use the Font/DA Mover to copy
   resource Memory from the file Memory into the System file.
   
   After quitting the Font/DA Mover and returning to the MPW Shell, select
   "Memory" from the Apple menu.



EditCdev - A Sample Control Panel Device in Pascal

	EditCdev demonstrates how to implement a editText item
	in a Control Panel Device.  It utilizes the new undo, cut, copy,
	paste, and delete messages that are sent to cdevs in
	response to user menu selections.

   To build EditCdev, simply select the line below and press Enter.

		BuildProgram EditCdev ∑∑ {Worksheet}

	To execute EditCdev, after building it, simply select the Control
	Panel desk accessory from the Apple menu, and click on the EditCdev
	icon in the list of Control Panel Devices.
	


TestPerf - An example of Using Performance Tools in Pascal

	TestPerf is an MPW tool that demonstrates the use of the performance
	measurement tools.  MakeFile contains the commands for building TestPerf.

   To build TestPerf, simply select the line below and press Enter.

		BuildProgram TestPerf ∑∑ {Worksheet}

	To execute TestPerf, select and execute the following command. (This
	test will run about 15 to 60 seconds, depending upon the machine, with
	only internal computations being performed):
	
		TestPerf

	TestPerf's raw performance data is written to the file Perform.out.
	In this sample use of the performance measurement tools, the ROM was
	measured.  So the ROM link map file needs to be combined with the program
	link map file.  Because there are three different ROM maps, select and
	execute the line that corresponds to the machine TestPerf was run on:
	
	# For Macintosh Plus:
		Catenate "{MPW}ROM Maps:MacPlusROM.map" >> TestPerf.map

	# For Macintosh SE:
		Catenate "{MPW}ROM Maps:MacSEROM.map" >> TestPerf.map

	# For Macintosh II:
		Catenate "{MPW}ROM Maps:MacIIROM.map" >> TestPerf.map

	PerformReport is an MPW Tool that combines the output of the performance
	tools with the link map file and produces a list of procedures, sorted by
	estimated percent of time spent in each procedure.  To run PerformReport
	execute the following command:

		PerformReport -l TestPerf.map -m Perform.Out > Report.Out

	The output of PerformReport is written to the file Report.Out.  To examine
	this output, execute the following command:
	
		Open Report.Out


Writing Your Own Programs

	After building (and perhaps modifying) the sample programs, you will
	undoubtedly want to write a program of your own.  Use the New… item in
	the File menu, to create the source files.  Remember that Pascal
	source filenames should end in .p.
	
	Create Build Commands…  -  The Create Build Commands… item in the 
	Build menu runs a script that creates a makefile containing the
	commands for building programs written in C, Assembly Language, Pascal, 
	and/or Rez.  Selecting Create Build Commands… displays a dialog box that 
	allows you to enter information about your program.  Type the program's
	name, select its source files by clicking the Files… button, and click
	one of the radio buttons to indicate your choice of an application, tool,
	or desk accessory.  
	
	Create Build Commands… puts the makefile for your program in the file
	<program>.make.  Now you can use the Build menu to build and rebuild
	your program, just as with the examples.
	
	Larger Programs  -  If you add source files as your program grows,
	use Create Build Commands… again to add the new source files to the build
	instructions.  If you out-grow the capabilities of the simple Create
	Build Commands… script (perhaps by using tools other than Asm, C, Pascal,
	Rez, and Link in your builds) you can modify the makefile yourself.
	
	Modifying the Directory and Build Menus  -  The Directory and Build
	menus are both implemented using scripts written in the MPW Shell
	command language.  This has the big advantage that you can modify
	or customize them to match the way you work.