TweetFollow Us on Twitter

Prograph 2.5
Volume Number:8
Issue Number:1
Column Tag:Tools of the Trade

Related Info: Event Manager Font Manager Apple Event Mgr

Prograph 2.5

Fully System 7 compatible with a Database Engine that will make you drool!

By Terry Kilshaw, Kelowna, British Columbia

Terry Kilshaw is a free-lance consultant, writer and programmer who also teaches Prograph and HyperCard programming. He has been designing and implementing software systems since 1979 and spent three and a half years as Manager of Software Development with TGS Systems. His current interests lie in the areas of multi-media programming and old-growth forest preservation. He can be reached at (604) 762-4451]

A Bit of History

After five years of research in two Canadian universities and a further year and a half of commercial development, Prograph 1.0, consisting of the integrated Editor/Interpreter/Debugger, was released in October of 1988. A new entrant in the field of Data-Flow, Visual and Object-Oriented programming, Prograph was immediately recognized as innovative, but its real signi-ficance was not at first grasped. Macintosh users had seen Object-Oriented languages, such as SmallTalk and Object

Pascal, before. They had seen visual languages like V.I.P., and those had their problems. But what they had not yet seen was a seamless, object-oriented development environment where the code was a data-flow diagram and editing, execution and debugging could all happen simultaneously. Surely on a visual machine such as the Mac there should be a visual way of programming! And here it was.

Prograph 1.1 appeared in March of 1989 and brought numerous additions, new primitives and refinements to the control annotations and the System Classes and integrated application editors. System Classes, which represent the major interface building blocks of Application, Menu, Window, Button, Scroll List and so on, with WYSIWYG Window and Menu editors and dialogs for specifying details for window items, gave Prograph essentially the same capabilities as products like Prototyper and AppMaker. But those products just churned out C or Pascal code at the rear end. Prograph integrated these capabilities directly into the editing and execution environments.

In September of 1989, the first “real” release of Prograph, version 1.2, was made. In addition to a tutorial and reference manual and many sophisticated examples, Macintosh Toolbox access was extended to cover almost everything in Volumes I through IV of Inside Macintosh. The product came nicely packaged and, for the first time, was available from the big mail-order houses. It also won a MacUser Eddy award as the best programming tool for 1989, a Canadian Information Processing Society (CIPS) award for innovation, and a Nova Scotia Pinnacles award.

The last day of July 1990 saw the release of Prograph 2.0. The big news here was a compiler which produced native 680x0 code. Like the Prograph Editor, the Compiler was fully graphical. Icons represented Prograph source code files, MPW C and THINK C object files, libraries and resource files. The Editor/Interpreter had been further refined. The HyperText-like on-line help capabilities were extended and Inside Macintosh Volume V definitions added. The ability to call HyperCard XCMDs using CEL software’s XLink rounded out a maturing product.

The Highlights

2.5 is System 7 compatible. It knows all about Inside Macintosh Volume VI. It can use TextEditStyle records and TrueType outline fonts. There are small, but significant changes to the System Classes, including a Pop-up Menu class. Method compaction is now available in the interpreter, cutting the size of a method by up to 75%. Users can now get their hands on events before they are processed and, most important of all, it comes with a Database Engine.

Promised as add-ons, coming soon, (corporate programmers and consultants take note), are support for the Communications Manager, for DAL and for Oracle. For those of us who have C or Pascal libraries just crying out for a Macintosh-like front end, TGS Systems will be offering tools which programmers can use to define the interfaces to their own libraries, so that they can be called directly from Prograph code.

And now to the details.

System 7 Support

The new Prograph is 32-bit clean and can run in 24- or 32-bit mode, which among other things presumably means that it will also run under A/UX. If users follow Apple guidelines for their own applications and do not mess directly with master pointers or the variant code of window and control definitions, then applications produced with the Prograph compiler will also be 32-bit clean.

It supports TrueType outline fonts which look quite excellent and also implements the use of TextEditStyle records.

Prograph itself is Stationery aware and responds appropriately to Apple Events. In addition to the required set of Open Application, Open Documents, Print Documents and Quit Apple Events, the Prograph interpreter also responds to Open Window, Close Window and Do Menu Apple Events. A clever addition to the Application Editor allows programmers to specify a list of Apple Event classes and IDs that their application will respond to, and to associate each Apple Event with the name of a Prograph method. All events, low level, high level and Apple are now passed through to applications. For more details on the new event response mechanism see below.

Balloon Help is available in the Editor/Interpreter and the Compiler and tools are supplied for adding Balloon Help to your own applications.

New Event Management

In previous releases the events which were sent to a programmer’s application were limited. Internal Prograph code, which the programmer could not get his or her hands on, received an event, determined if it was one of the subset of events which should be dispatched to a user’s program, looked in the appropriate System Class to see if the name of a method had been specified by the programmer and dispatched the event to that method.

In 2.5 that has all changed. Now all events are passed to a method called notify in class Application. Users can, of course, write their own version of notify, but Prograph comes with a default set of event handling methods.

notify is a method with three inputs and 8 cases. The first input is the instance of the current Application class, the second the Mac EventRecord, and the third the current event ID. Each case deals with a different class of events as follows:

• Null events

• MouseDown events

• KeyDown and AutoKey events

• Update events

• Activate events

• Apple events

• Suspend & Resume events

• All other events.

The appropriate case of notify then deals with that event directly, calls another of the supplied event handling methods to deal with it or calls the method that the programmer specified, just as in earlier Prograph versions.

For example a mouseDown event is processed by case 2 of notify, which determines whether the click occurred in a window or not. If it did, the event information is passed to the method /mouse down in class Window; otherwise, it is passed to the method /mouse down in class Application.

Application/mouse down first checks to see if the click occurred in the menu bar. If so, control goes to the method /menu click in class Application where case 1 checks to see if the click was in the Apple menu and, if it was not, the appropriate menu item is identified, the name of its associated method is found and that method is executed.

Apple Events

Apple Events are treated a little differently, because of the way in which Apple designed them. The normal mechanism requires that the address of a callback routine be registered by calling AEInstallEventHandler for each Apple Event that your application can handle. When an Apple event is received by an application, AEProcessAppleEvent should then be called. This passes control to your callback routine. Because the programmer has to call AEProcessAppleEvent anyway, one wonders why Apple engineers packaged it this way.

Now for a number of reasons explained below, Prograph cannot easily provide callback addresses. So what the TGS engineers have done is to provide a generic callback routine which records the details of the incoming Apple Event and then suspends the reply which AEProcessAppleEvent would normally send automatically. The Apple Event is then dispatched to the method notify where the method provided by the programmer is called. All of this happens transparently.

This certainly makes the reception of Apple Events easy. But processing them is just the same in Prograph as in any other language. TGS Systems hopes in the near future to release a set of classes whose methods will simplify the handling of standardized suites of Apple Events.

The System Class Primitives

Some new primitives called “System Class Primitives” have been provided to simplify responding to events. There are System Class primitives for activating and zooming windows, finding which window item has been clicked on, highlighting and drawing window items, responding to Apple Events and so on. Two of these new System Class primitives allow for the insertion and deletion of Window items and Menu items to active windows and menus. Among other things, this will allow for the creation of forms from arbitrary record definitions, on the fly.

This new event handling mechanism will give sophisticated programmers much more control of events than before, but unless the contents of the System Class primitives is also divulged, there will still be areas of obscurity. I would like to see versions of those primitives written in Prograph or, failing that, the C code for the primitives made available for the sake of completeness.

Not surprisingly the System Classes have jumped from 27K in size in version 2.0 to 156K in 2.5, but method compaction reduces this to about 40K. There is however a performance penalty to be paid in interpreted code for this new event dispatching scheme. This can most easily be seen in windows which have many window items. It is only troublesome for Mac Plus/SE/Classic users and in compiled code this problem disappears. If you have a faster machine, you probably won’t even notice it.

An Unsolved Problem

It is still not possible to write code for toolbox callbacks as Prograph methods. The difficulty in implementing this functionality arises from the fact that all Prograph data items reside in Handles and that the Interpreter uses a linked list of its own stack frames rather than the Macintosh stack. Many callbacks require that no heap manipulation occur when they are called, some are time critical responses to asynchronous processes not at all suitable for interpreted environments, where the programmer may have his program in debug mode in the middle of the callback. But it has always been possible to write callbacks for Prograph in C and package them with a Prograph primitive which returns the address of the callback.

Engineers at TGS are studying this problem and may be able to offer a solution before long.

Method Compaction

Methods can now be uncompact, compact or execute only. Compacted methods have an in-memory size which is a quarter of the uncompacted size. The extra information is written to the resource fork of the application. Uncompaction reconstitutes the method(s). This will allow programmers to work with much larger programs than before, with the same amount of memory. The Prograph 2.5 Product Description says that execute-only methods let programmers “release interpreter source code which is protected from modification by the user”. The visual information for an execute-only method is not saved, and so the method cannot be uncompacted to look at the details of its source code. Its main value will lie in allowing third party libraries to be used in the interpreter, as well as the compiler, while protecting the developer’s investment by making the methods unreadable.

System Class Enhancements

Access to a dialog for specifying balloon help is given for the Menu and Menu Item classes and for all of the Window Item classes.

A new System Class, Pop-up Menu, has been added. It comes as a subclass of Click Item and like all the other System Classes, you can create and modify Pop-up Menu items in the WYSIWYG window editor. All the usual Click Item attributes can be specified such as whether the Pop-up is active or grayed out, is visible or not, its location within the owning window and so on. It has attributes for being a fixed width, or varying with the width of the current value, and the text style of each item is setable.

The Edit Text and Scroll Text classes now use TextEditStyle records and Prograph 2.5 comes with an example program which defines three menus for changing the size, font type and style (bold, underline, etc ) of selected text. Because TrueType outline fonts are also implemented, it is possible to create some very nice textual effects.

The Canvas, Edit Text and Scroll Text classes now have a border? attribute which allows the programmer the option to turn off the single pixel border which normally frames these window items.

The Scroll List class now allows for the specification of font, size and style and single or multiple selection. It is also possible to specify invisibility from the editing dialog. Scroll Lists are now selectable items and support the use of arrow keys.

So what’s missing? When I mentioned to the people at TGS that I would like to have seen a floating windoid class their immediate response was that a sub-class of Window with just that capability will ship with 2.5. And when I pointed out that there is still no System Class support for hierarchical menus, they indicated that a mechanism for installing instances of class Menu as sub-menus will also come as a 2.5 example.

The Database Engine

TGS Systems has done a very thorough job of providing core functionality for database applications. The Database Engine provides the tools that are required to construct [more or less] any kind of database application that you would like. TGS Systems claim that flat file, relational, network and object-oriented databases can all be constructed from the Database Engine.

The engine comes as a set of Prograph primitives. Physically a database consists of two files, a data file and a key file. The name of the database is the same as the name of the data file, e.g., myInfo. The key file has the same name as the datafile with the suffix keys added, e.g., “myInfo keys”.

Four entities serve to define a Prograph database: database, table, cluster and key.

A database consists of a named collection (0 or more) of tables. A table is made up of 0 or more clusters. Each table has a name. A table may have associated with it 0 or more keys and each key also has a name. A key is used to define the ordering of clusters within a table. For example we might define a key called last name which allows us to access clusters in alphabetical order.

A cluster is an arbitrarily complex Prograph data item which has been reduced to a stream of bytes. For example an instance of a class, Person, may have as attributes, a name, an age, an instance of class address and a picture (i.e., a PICT referenced by a Mac Handle). Before storage in the database this is reduced to a stream of bytes (i.e., a cluster). Primitives are also provided to clusterize data items independently of the database. The cluster could then be sent through a serial port, across a net-work or through an IAC call. This makes Prograph 2.5 an ex-cellent candidate for the creation of distributed database systems.

The ability to save the contents of Mac Handles has also been added to the load and save mechanisms of the Editor/Interpreter. For Mac data types, however, it will only save the contents of the Handle. Any further levels of indirection are ignored. This is sufficient for entities such as PICTs, icons and sounds though you should note that resource information, such as resource ID number and name, is not saved with the contents of the Handle.

Opening a database returns to the programmer a database ID. This is a number which specifies an access path to the database. Similarly, opening a table returns a table ID and opening a key, a key ID. These various IDs are used as inputs to the database primitives and allow for some sophisticated pro-gramming. For example, it is possible to have multiple databases open with multiple paths open to each database, table or key and, of course, multiple tables and keys open at the same time.

A database can be opened in one of three modes: update, query, or share. Update allows single-user read and write access. Share allows multi-user read and write access, and query allows multi-user read-only access. Locking is available on the cluster level. I would also like to see locking available on the table and database level. This would make certain types of maintenance easier.

In a database, each cluster is stored at a unique offset within the data file and is referenced through the table to which it belongs. This byte offset becomes the cluster ID. You should note that a cluster can be of arbitrary length, and that no information is kept in the database about the type of infor-mation which is stored in a cluster. Though the database designer could easily use the database engine to store their own database dictionary.

A cluster can be accessed directly through its table ID and cluster ID. Sequential and random access is facilitated through the keys which the programmer associates with a table. It is important to realize that the mapping of the key information onto a cluster in a given table is not constrained by the information in the cluster. For example, I may create a table of sounds with each cluster consisting of a clusterized sound resource. I may have a key called name associated with the table of sounds, and with each sound I may specify its key value to be an appropriate name, such as “larks in the morning” or “kangaroos courting”. Each string will each be associated with its cluster, but will appear only in the key file and not within the clusterized data.

Of course, more conventional database models can also be constructed, where each table maps to a record definition and where each key refers to a field of the record.

Database primitives are also provided for importing and exporting text files of records with tab delimited fields.

TGS Systems claim that an object-oriented database can be constructed by saving any instance of a class as a cluster and identifying each cluster directly by its cluster ID. This does mean that such a database could not be compacted, as compaction will necessarily change cluster IDs.

The Database Engine seems like an excellent piece of work. Keys are maintained using a standard B+ Tree application. Multi-user access is accommodated and, together with the Prograph language and interface editors, all the tools are available for the rapid creation of sophisticated programs which need database functionality.

The Compiler

The Prograph 2.5 compiler is essentially the same as before but with some new items for System 7 support.

These include Accept Suspend/Resume, Can Background, doesActivateOnFGSwitch, Background Only, Get Front Clicks, Accept Child Died Events, 32-Bit Compatible, High Level Event Aware, Use Remote HL Event, Stationery Aware and Use Inline Text Service. There is also a new option to optimize for speed or size.

It is still not possible to compile standalone code resources such as device drivers or HyperCard XCMDs, nor to make any form of compiled Prograph code callable from the interpreter.


One small addition may make all the difference in the world to those Prograph programmers who have a passion for creating datalinks which are precisely horizontal or vertical. A key combination of “option-arrow key” will now move a selected icon by one pixel in the chosen direction. Also an “option-click” in the zoom box of a window now expands the window only enough to show all of the window’s contents.

There are some changes to the Options Dialog. Update Preferences and Menu Help Messages have gone and there are two new options. Cmd-click to create changes the behavior in edit windows so that a Cmd-click key combination is required to create an object. This will help those users who accidentally end up creating classes or operations when they did not mean to.

Startup Messages is an option which, when chosen, will cause Prograph to display a dialog which gives information about which external and primitive packages are being loaded when Prograph is started up.

There are some new reflexive primitives which will enable users to write code to help in the creation of call graphs and so on. For example called-from-meth is a primitive which takes as input the name of a class and the name of method. It returns on its three outputs, a list of method names, get method names and set method names, which are called from the original method.

Some new cosmetic features for those who have the hardware and software to support it. Prograph offers true grays in title bars, menus and menu items and when drawing inactive windows, menus and menu items.


Prograph 2.0 came with a Tutorial manual and a Reference manual. Early buyers of Prograph 2.5 got these two manuals and an 85-page, separately bound addendum describing the new features. Current buyers (version 2.5.1 onward) are getting a revised and updated set of Tutorial and Reference manuals which are 247 and 475 pages long respectively. Each manual has an index.


In addition to the examples already mentioned, Prograph 2.5 will come with many other example programs, classes and code fragments. Some of these, such as Algorithms and Document Shell, will be familiar from previous releases. A HyperText example utilizes the Database Engine. Some classes should help in the creation of input forms: these include a Check Text class, to verify the contents of an input field whenever another text item or Scroll List is selected or the window is closed, and a class to facilitate the modal control of windows. There are other examples to play sounds, control scrollbars, put up floating windows, display hierarchical menus, support printing, and so on. TGS Systems have always been very generous with their examples but are limited by the space on the disks which are shipped. Any examples mentioned here which are not in the product they say will be made available on a “Goodies” disk or disks for a small extra cost.


TGS Systems have done an excellent job of bringing full System 7 compatibility to Prograph 2.5. Programmers will be especially pleased by how easy it is to turn out their own System 7 compatible applications, 32-bit clean with balloon help, outline fonts and Apple Event awareness.

Access to the event management allows the functionality of the System Classes to be greatly extended.

Method compaction makes possible the development of much larger applications in the same amount of memory.

The Database Engine is a beautifully designed addition which should have consultants and corporate programmers drooling at the mouth, especially when the C and Pascal interfaces and the DAL API, Oracle Call Interface and Communication Toolbox additions are available.

Prograph Extension Products

The Prograph Extension Products are available directly from TGS Systems. These include: DAL API: $199; Oracle API: $199; Pascal Interface: $149; C Interface: $149; Comm Toolbox: $149; Visual Effects Manager: $79; Goodies Disk: $49.

About the author

Terry Kilshaw is a free-lance consultant, writer and programmer who also teaches Prograph and HyperCard programming. He has been designing and implementing software systems since 1979 and spent three and a half years as Manager of Software Development with TGS Systems. His current interests lie in the areas of multi-media programming and old-growth forest preservation. He can be reached at 604/762-4451.

For more information, contact:

TGS Systems, Suite 200, 2745 Dutch Village Rd.

Halifax, Nova Scotia B3L 4G7 Canada

902/455-4446, 800/565-1978

Retail Price: US $495, 2.0 users can upgrade for $49.99.

Prograph 1.2 users should contact the company.


Community Search:
MacTech Search:

Software Updates via MacUpdate

World of Tanks Generals guide - Tips and...
World of Tanks Generals is a brand new card game by the developer behind the World of Tanks shooter franchise. It plays like a cross between chess and your typical card game. You have to keep in consideration where you place your tanks on the board... | Read more »
TruckSimulation 16 guide: How to succeed...
Remember those strangely enjoyable truck missions in Grand Theft Auto V whereit was a disturbing amount of fun to deliver cargo? TruckSimulation 16 is reminiscent of that, and has you play the role of a truck driver who has to deliver various... | Read more »
The best GIF making apps
Animated GIFs have exploded in popularity recently which is likely thanks to a combination of Tumblr, our shorter attention spans, and the simple fact they’re a lot of fun. [Read more] | Read more »
The best remote desktop apps for iOS
We've been sifting through the App Store to find the best ways to do computer tasks on a tablet. That gave us a thought - what if we could just do computer tasks from our tablets? Here's a list of the best remote desktop apps to help you use your... | Read more »
Warhammer 40,000: Freeblade guide - How...
Warhammer 40,000: Freebladejust launched in the App Store and it lets you live your childhood dream of blowing up and slashing a bunch of enemies as a massive, hulking Space Marine. It's not easy being a Space Marine though - and particularly if... | Read more »
Gopogo guide - How to bounce like the be...
Nitrome just launched a new game and, as to be expected, it's a lot of addictive fun. It's called Gopogo, and it challenges you to hoparound a bunch of platforms, avoiding enemies and picking up shiny stuff. It's not easy though - just like the... | Read more »
Sago Mini Superhero (Education)
Sago Mini Superhero 1.0 Device: iOS Universal Category: Education Price: $2.99, Version: 1.0 (iTunes) Description: KAPOW! Jack the rabbit bursts into the sky as the Sago Mini Superhero! Fly with Jack as he lifts impossible weights,... | Read more »
Star Wars: Galaxy of Heroes guide - How...
Star Wars: Galaxy of Heroes is all about collecting heroes, powering them up, and using them together to defeat your foes. It's pretty straightforward stuff for the most part, but increasing your characters' stats can be a bit confusing because it... | Read more »
The best cooking apps (just in time for...
It’s that time of year again, where you’ll be gathering around the dinner table with your family and a huge feast in front of you. [Read more] | Read more »
Square Rave guide - How to grab those te...
Square Rave is an awesome little music-oriented puzzle game that smacks of games like Lumines, but with its own unique sense of gameplay. To help wrap your head around the game, keep the following tips and tricks in mind. [Read more] | Read more »

Price Scanner via

Cyber Monday: Target offers 15% discount on A...
Target has discounted Apple Watches by 15% for Cyber Monday. Choose free shipping or free local store pickup (if available). Sale prices for online orders only, in-store prices may vary: - Apple... Read more
Sunday roundup of Holiday weekend Mac sales:...
Take up to $500 off MSRP on the price of a new Mac at B&H Photo today as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only. These prices are... Read more
Holiday weekend: Apple Watch on sale for $50-...
B&H Photo has the Apple Watch on sale today for $50-$100 off MSRP. Shipping is free, and B&H charges NY sales tax only: - Apple Watch Sport: $50 off - Apple Watch: $50-$100 off Read more
Holiday weekend: iPad Air 2s on sale for up t...
B&H Photo has iPad Air 2s on sale for up to $80 off MSRP including free shipping plus NY sales tax only: - 16GB iPad Air 2 WiFi: $459 $40 off - 64GB iPad Air 2 WiFi: $569 $30 off - 128GB iPad Air... Read more
Holiday weekend Mac sales roundup: B&H Ph...
B&H Photo continues to have all new Macs on sale for up to $500 off MSRP as part of their Black Friday/Holiday weekend sale. Shipping is free, and B&H charges NY tax only: - 15″ 2.2GHz Retina... Read more
iMobie Releases its Ace iOS Cleaner PhoneClea...
iMobie Inc. has announced the new update of PhoneClean 4, its iOS cleaner designed to reclaim wasted space on iPhone/iPad for use and keep the device fast. Alongside, iMobie hosts a 3-day giveaway of... Read more
U.S. Cellular Offering iPad Pro
U.S. Cellular today announced that it is offering the new iPad Pro with Wi-Fi + Cellular, featuring a 12.9-inch Retina display with 5.6 million pixels — the most ever in an iOS device. U.S. Cellular... Read more
Newegg Canada Unveils Black Friday Deals for...
Newegg Canada is offering more than 1,000 deep discounts to Canadian customers this Black Friday, available now through Cyber Monday, with new deals posted throughout the week. “Black Friday is... Read more
Black Friday: Macs on sale for up to $500 off...
BLACK FRIDAY B&H Photo has all new Macs on sale for up to $500 off MSRP as part of their early Black Friday sale including free shipping plus NY sales tax only: - 15″ 2.2GHz Retina MacBook Pro: $... Read more
Black Friday: Up to $125 off iPad Air 2s at B...
BLACK FRIDAY Walmart has the 16GB iPad Air 2 WiFi on sale for $100 off MSRP on their online store. Choose free shipping or free local store pickup (if available): - 16GB iPad Air 2 WiFi: $399, save $... Read more

Jobs Board

Technical Program Manager, Strategic Merchant...
# Technical Program Manager, Strategic Merchants - Apple Pay Job Number: 44001177 Santa Clara Valley, Califo ia, United States Posted: Oct. 30, 2015 Weekly Hours: 40.00 Read more
Frameworks Engineer, *Apple* Watch - Apple...
# Frameworks Engineer, Apple Watch Job Number: 41403122 Santa Clara Valley, Califo ia, United States Posted: Jul. 1, 2015 Weekly Hours: 40.00 **Job Summary** Join the Read more
Software Engineer - *Apple* Pay - Apple (Un...
# Software Engineer - Apple Pay Job Number: 44003246 Santa Clara Valley, Califo ia, United States Posted: Nov. 16, 2015 Weekly Hours: 40.00 **Job Summary** Apple Pay Read more
Merchant Operations Manager: *Apple* Pay -...
# Merchant Operations Manager: Apple Pay Job Number: 43593822 Santa Clara Valley, Califo ia, United States Posted: Nov. 10, 2015 Weekly Hours: 40.00 **Job Summary** The Read more
Product Design Engineer - *Apple* Watch - A...
# Product Design Engineer - Apple Watch Job Number: 41727161 Santa Clara Valley, Califo ia, United States Posted: Jul. 22, 2015 Weekly Hours: 40.00 **Job Summary** Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.