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

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.

Miscellaneous

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.

Documentation

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.

Examples

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.

Conclusions

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.

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.