Volume Number: 14 (1998)
Issue Number: 11
Column Tag: Programming Techniques

Programmer's Introduction to Mac OS 8.5

by Dan Parks Sydow

An overview of the Allegro features to incorporate into Mac programs

Overview

A few years back, Apple's years-in-the-making Copland promised to be the operating sytem to modernize the Macintosh. As we all now know, the Copland effort fell behind and was scrapped. But many of Copland's technologies were preserved, and emerged in the 1997 introduction of Mac OS 8. With millions of copies of Mac OS 8 sold in just months, it's obvious that users were anxious to put a new user interface on their Macs. Now, the first major upgrade to Mac OS 8 has arrived. While the changes and enhancements from Mac OS 8 to Mac OS 8.5 (code-named Allegro) may not be quite as dramatic as those from Mac OS 7.x to Mac OS 8, they are still very impressive. Like Mac OS 8, Mac OS 8.5 will be considered a "must have" operating system upgrade by many Mac users. With this in mind, you'll want to make sure that your own Macintosh applications support the features expected of a program running under Mac OS 8.5.

Mac OS 8.5 includes a host of new user-friendly features and user interface improvements, including improved Internet functionality, an enhanced Find command (that includes file-content and Internet searching), HTML-based help system, and much more. While all these improvements are a boon to the Mac user, not all are of direct relevance to the Mac programmer. For instance, desktop-related Mac OS 8.5 enhancements (such as the improved Find command) don't affect a Mac programmer. On the other hand, the integration of the Appearance Manager and Navigation Services into the operating system do affect the Mac developer.

Mac OS 8.5 also includes a number of behind-the-scenes changes such as more PowerPC-native code and a PowerPC-native AppleScript. While these changes may help your application indirectly, you won't need to expend any effort to include them in your program. For example, more PowerPC-native code may speed up your program's execution without you rebuilding the program. Other non-interface changes are of importance to programmers. Most notable are the new Toolbox routines that bump up the version number to 2.0 for each of three managers: Window Manager, Dialog Manager, and Menu Manager.

This article provides an overview of how to implement the new interface features of Mac OS 8.5 (such as Appearance and Navigation Services) and a summary of some of the most important new Toolbox functions accompanying Mac OS 8.5.

Appearance Manager

The sleek look provided by the Appearance Manager is often referred to as Appearance. For the user, Appearance is provided by the Appearance control panel. This tabbed control panel allows the user to choose a theme that defines the overall look of user interface elements (Figure 1 shows the Appearance control panel with the Themes tab selected). A theme is simply the combination of a number of Appearance control panel options, including appearance, font, desktop pattern, and so forth. Of these options, it's the appearance that's most thought of as the theme itself - the appearance establishes the overall look of interface elements such as windows and menus. Mac OS 8.5 ships with a number of Apple-supplied themes, all based on the Apple platinum appearance. Notable by their absence are the oft-mentioned Gizmo and Hi-Tech appearances. Though these appearances may resurface in the future.

Figure 1. The Appearance control panel with the Themes tab selected.

Apple's user interface guidelines exist so that all Mac programmers develop applications that have a certain commonality in their look and behavior. For users, this similarity in look-and-feel between applications is comforting, and lessens the time needed to learn how to use new applications. Giving the user the power to radically alter the look of windows and their user interface elements seems to defy Apple's user interface guidelines. If done on a systemwide level, though, it doesn't. While the desktop GUI elements may look different on one Mac than they do on another, to each individual user his or her machine displays things in a consistent manner. So machine-to-machine differences aren't relevant (though one could argue that a novice forced to work on different Macs might get confused).

For the programmer, the Appearance Manager consists of a number of new Toolbox routines. While Mac OS 8.5 integrates the Appearance Manager into the operating system, the benefits of this manager were available to developers prior to Mac OS 8.5. By including Appearance Manager function calls in your own source code, linking your compiled code to the Apple-supplied Appearance shared library, and distributing your application with the Appearance Extension, you had the option of supplying pre-Mac OS 8.5 users with Appearance features. Because the new look provided by the Appearance Manager has been described in other sources, including the January 1998 issue of MacTech Magazine (Vol. 14, No. 1), it is covered only lightly here.

Checking for Appearance

Appearance is built into Mac OS 8.5 - there's no need for the Appearance Extension to be present in the Mac OS 8.5 user's System Folder. But unless you know for certain that your own Appearance-savvy application will be running on only Mac OS 8.5 or later systems (a very unlikely scenario), your program needs to check the user's machine for the presence of Appearance. To do this, pass the gestaltAppearanceAttr selector to the Gestalt() function and test the response against gestaltAppearanceExists.

If the Appearance Manager isn't present, your application is running on a Mac with a pre-Allegro version of the Mac OS that doesn't have the Appearance Extension installed (or has it present but disabled). You'll want to let the user know that Appearance is necessary, and you'll want to supply further instructions (such as how to install the Appearance control panel and extension if you supply them with your application). If the Appearance Manager is present, call RegisterAppearance() to initialize this manager.

Navigation Services

The Open and Save dialog boxes provided by Standard File can be a source of confusion for users new to the Macintosh. This confusion stems from the differences in how file browsing is accomplished on the desktop and in the Standard File dialog boxes. Other drawbacks to these dialog boxes include the inability to select multiple files and the lack of a means to quickly reselect recently chosen files. Navigation Services was designed to overcome all these limitations and to add several other enhancements to the Open and Save dialog boxes (the Open dialog box is shown in Figure 2).

Figure 2. The Open dialog box provided by Navigation Services.

For the programmer, Navigation Services, like the Appearance Manager, consists of a number of new Toolbox routines. Again like the Appearance Manager, Navigation Services have been integrated into Mac OS 8.5, but its features were available prior to this latest version of the Mac operating system. By including Navigation Services function calls in your project's source code and linking your compiled code to the Apple-supplied Navigation shared library, you were able to supply pre-Mac OS 8.5 users with Navigation features. Because Navigation Services support the Appearance Manager, in the past it was also required that a program making use of Navigation Services shipped with the Appearance Extension. Programming with Navigation Services has been described in a number of other sources, including the August 1998 issue of MacTech Magazine (Vol. 14, No. 9), so the topic will only be touched upon here.

Checking for Navigation Services

Navigation Services are built into Mac OS 8.5, so there'll be no Navigation Services extension in the Mac OS 8.5 user's System Folder. There's also no Navigation-related control panel. Prior to Mac OS 8.5 the Navigation Services code was present in a Navigation shared library. Because your application will most likely be running on pre-Allegro systems, it should test for the availability of Navigation Services. Unlike checking for the presence of Appearance, a call to Gestalt() won't reveal the presence or absence of Navigation. That's because Gestalt() might not detect the Navigation code (which won't be in memory unless an application has already loaded the shared library). Instead, simply call the NavServicesAvailable() function.

Opening and Saving Files

To display the new version of the Open dialog box, call the NavGetFile() function. One of the parameters NavGetFile() accepts is of the new data type NavTypeList. This structure is made up of fields that hold your application's signature, a number that specifies the number of different file types that your application can open, and an array naming those file types. Use this NavTypeList structure to supply the dialog box with the types of files your application is capable of opening.

To display the new version of the Save dialog box, call the NavPutFile() function. You'll use two of the NavPutFile() parameters to specify the file type and the file creator for the document to save.

Window Manager 2.0

With the release of Mac OS 8.5 comes a new version of the Window Manager. Version 2.0 includes the many routines you've come to know and love - and a slew of new functions that you'll soon come to also know and love.

Creating a Window

Prior to Window Manager 2.0, a programmer used one of two techniques to create a window: the window's characteristics were defined in a WIND resource and then loaded into memory by a call to GetNewWindow(), or the window's characteristics were defined on-the-fly as arguments in a call to NewWindow(). Regardless of the method used, the result was the same: the data that defined a window was loaded into memory, and a WindowPtr by which the window could be referenced was returned to the program. Both these window-creation techniques are still valid, but Window Manager 2.0 provides two more efficient alternatives.

If you currently define a window's characteristics in a WIND resource, consider using the new wind resource type. To load the wind data to memory call the new CreateWindowFromResource() function. Like a call to GetNewWindow(), CreateWindowFromResource() returns a standard WindowPtr.

If you want to define the characteristics of a window via parameter data rather than from resource data, use the new CreateWindow() function. This routine can be thought of as a leaner NewWindow() - it does the same work as NewWindow(), but requires fewer arguments. CreateWindow(), like NewWindow(), returns a standard WindowPtr.

Persistent Window Data

Version 2.0 of the Window Manager introduces a third, more powerful technique, for creating a window. In the past, associating application-defined data with a window, and making that data persistent (retrievable in a subsequent running of the program), was the responsibility of the programmer. With Window Manager 2.0, the programmer and the Toolbox now share this task.

The advantage of using a wind resource is that the window-defining data in the wind resource can be saved collectively with other data associated with the window and saved to disk. Saving a window and it's associated data (a document to the user) involves the use of the new wind resource, a couple of new Window Manager routines, and a few not-so-new functions from the Collection Manager and Resource Manager.

To save a window some data associated with that window to a single resource, begin by creating a collection. A collection is used to collectively store any number of items. Like an array, the items in a collection are individually accessible. Unlike an array, the items in a collection can be variable in size. Once created, items can be added, removed, or accessed during runtime. Collections and the Toolbox routines used to manipulate collections are a part of the Collection Manager. If you've programmed with QuickDraw GX, you may have worked with collections. If the topic of collections is new to you, don't panic - you only need to know a little about collections in order to use them in conjunction with saving window data.

In particular, you use the Collection Manager routine NewCollection() to create a new, empty collection. Next, add the window-defining information (which may initially have come from a WIND resource, a wind resource, or runtime parameters) to this new collection by calling the Window Manager function StoreWindowIntoCollection(). Now call the Collection Manager routine AddCollectionItem() to add window-associated data to the same collection. As a trivial example, consider a window that displays two strings. To associate the strings with the window, call AddCollectionItem() twice, with each call specifying the collection to add the string to, a means to later reference this one item, the byte-size of the item, and the data that makes up the item (the characters in the string).

With the collection complete, call the Collection Manger routine FlattenCollection() to, yes, flatten the collection. The result is a stream of unformatted bytes, ready to be saved to disk. This last step is accomplished by calling the Resource Manager function AddResource(), specifying cltn (for collection resource) as the resource type).

To later reconstruct a window from a collection resource, reverse the window-saving process. Call the Resource Manager function GetResource() to load the cltn resource into memory. Then call the Collection Manager function UnflattenCollection() to restore formatting to the flattened stream of bytes that make up the collection. Once again call the Collection Manager function NewCollection() to create a new, empty collection. Then call the new Window Manager 2.0 function CreateWindowFromCollection(). Recall that when the collection was previously created, the call to StoreWindowIntoCollection() stored all of the window's defining characteristics into the collection. That call in essence placed a wind resource into the collection. Now, calling CreateWindowFromCollection() extracts that wind data to reconstruct the window.

At this point the window is created, but any associated data is still in the collection (the result of loading the cltn resource data into memory). Retrieve each item by repeatedly calling the Collection Manager function GetCollectionItem().

Floating Windows

A floating window is one that always appears in front of any and all document windows - regardless of whether a document window is active. Floating windows aren't new to Mac OS 8.5, but the level of Toolbox support of windows of this type is.

One of the arguments to the previously mentioned CreateWindow() function is windowClass, a value of the new data type WindowClass. A number of Apple-defined constants (such as kDocumentWindowClass and kAlertWindowClass) can be used here to categorize the type of window that's to be created. The windowClass parameter helps define the look of a window, as well as the window's general behavior. If the Apple-defined constant kFloatingWindowClass is used as the windowClass parameter, then the newly created window will be a floating window. When the kFloatingWindowClass constant is used in the creation of a window, the proper front-to-back display order of the window becomes automatically handled by the system. This means that your own code need no longer support the behavior of your application's palettes.

Three new Window Manager functions are now present to assist you in working collectively with all open floating windows. HideFloatingWindows() hides all of your application's floating windows. Conversely, ShowFloatingWindows() shows all open floating windows. Use AreFloatingWindowsVisible() to determine the current visibility of your program's floating windows.

A common window-related task is the determination of the frontmost window. Typically, "action" takes place in a document window rather than a floating window (which often serves as a palette), so your program most often is interested specifically in the frontmost document window rather than the frontmost of all open windows. The original FrontWindow() function provides your program with the frontmost of all windows, which could result in a pointer to a floating window being returned to your program. To accompany FrontWindow() Window Manager 2.0 adds the FrontNonFloatingWindow() routine. As its name implies, this function returns a WindowPtr that points to the application's frontmost visible non-floating window.

Finder and Theme Support

In Mac OS 8.5, opening a window on the desktop results in an animated effect: a small outline of the window appears at the window's source (such as a folder icon) and quickly grows to the size of the about-to-appear window. A similar scenario exists for a window that's about to close. Optionally, as the window opens or closes a sound may play - whether or not the sound plays is dependent on the currently selected theme. Window Manager 2.0 adds support for window animation and window theme-appropriate sounds for your application's windows.

A single new function, TransitionWindow(), takes care of the display of an application window's animation as well as the window's playing of a theme sound. You're encouraged to call TransitionWindow() in place of ShowWindow() and HideWindow() (one of the TransitionWindow() parameters specifies whether the specified window should be displayed or hidden). Using this new Window Manager 2.0 function guarantees that your program follows the theme selected by the user.

Other New Window Manager Topics

The Window Manager is the most enhanced of the new managers. A few other areas worthy of investigation are summed up here:

• Zooming The new ZoomWindowIdeal() function supplants the older ZoomWindow() routine. ZoomWindowIdeal() toggles a window between a standard state and a user state. The ZoomWindowIdeal() function automatically determines the best standard state for a window based on human interface guidelines. For instance, a window should be positioned entirely on one screen of a multiple-monitor system. The user indirectly sets the user state (ZoomWindowIdeal() uses the size and position of the window before it was last zoomed).
• Content color If you use a window color resource of type wctb to establish the content color of a window, you should switch techniques to now use the new Window Manager 2.0 SetWindowContentColor() function. There's also a SetWindowContentPattern() routine that lets you specify a pattern (a PixPat, or pixel pattern) to which a window's content will be redrawn.
• Proxy icon Looking at an open in window on the desktop of a machine running Mac OS 8.5 you see that a small icon appears to the left of the window's title in the title bar. This proxy icon looks and acts like the document's icon does in the Finder (that is, you can control-click it to bring up a contextual menu, you can drag it off the title bar and move the icon to a different location on the desktop, and so forth). You can easily add a proxy icon to the document windows created by your own application by calling the new SetWindowProxyFSSpec() function. Prior to calling this function you should create an FSSpec structure for the document (a File Manager technique that remains unchanged from previous Mac OS versions, and something your program will do when saving a document).

Dialog Manager 2.0

Mac OS 8.5 introduces a new version of the Dialog Manager - version 2.0. Enhancements to the Dialog Manager are minimal, so we can summarize this manager's changes in just a few paragraphs.

Simulating User Response

When a dialog is posted, it remains on screen until the user specifies some action. Typically this action will either be accepting the information changes made in the dialog box (by pressing a Done or OK or some similarly named button) or rejecting the changes (by pressing a Cancel button). The Dialog Manager 2.0 introduces a method of dismissing a dialog box - one that requires no intervention on the user's part. Using the SetDialogTimeout() function you can supply a period of time after which a dialog box will be dismissed without the user having taken any action. This function also allows you to specify which item should be the recipient of a simulated selection. One application of this technique could be to force a selection of dialog box Cancel button after a considerable period of inactivity (under the assumption that the user is confused as to what path to take in order to continue using your program).

The new Dialog Manager also defines a GetDialogTimeout() function so that you can query the original timeout duration and the countdown time remaining. You could make use of this routine to watch for the impending automatic dismissal of a dialog box and to then provide the user with an alert that warns that after some specified period the displayed dialog box will be dismissed.

Event Filtering

A modal dialog box is the recipient of only a limited number of event types - events of other types are automatically filtered out and ignored. Dialog Manager 2.0 changes that by defining the SetModalDialogEventMask() function. After creating a dialog box, you can specify the event types the dialog box should handle by passing the appropriate event mask to SetModalDialogEventMask(). If you do specify additional event types to handle (such as disk insert events or operating system events), you'll need to also define an event filter function that includes the code that actually does handle events of these types. The process for defining such a filter function and for including it as a parameter to the standard ModalDialog() function remain unchanged.

Menu Manager 2.0

Mac OS 8.5 introduces a new version of the Menu Manager - version 2.0. Changes to this manager aren't dramatic, but they are important enough to warrant a quick study.

Menu Bar Display

In the past there has been some confusion regarding the best way to hide, and later redisplay, the menu bar. That's because there was no single, simple, one-function call to carry out the act of hiding or showing the menu bar. Now, finally, there is! The new HideMenuBar() function accepts no arguments - just invoke it to make the menu bar invisible and to make any menus and menu items in it unselectable by the user. The new companion routine ShowMenuBar() redisplays and activates the previously hidden menu bar. If your program need to check on the current visibility of the menu bar it can call the new IsMenuBarVisible() function.

Menu and Menu Item Enabling

When it came to disabling or enabling menu item, you may have been satisfied with the workings of the DisableItem() and EnableItem() functions. Unless you wrote applications that included menus with more than 31 menu items. The DisableMenuItem() and EnableMenuItem() functions work as the old routines did, but these two new functions are able to handle menus with any number of items. If your program needs to check on the current state of a particular menu item, call the new IsMenuItemEnabled() function. As in the past, after changing the state of a menu item you should call DrawMenuBar() to update the display of a menu bar and its menus.

Setting a Menu's Font

You can call SetMenuFont() to establish a particular font and font size to be used in the display of menu items for a single specified menu. Typically all of the menus in your program's menu bar will display item names in the same font, but they don't have to. More typical is the use of this routine in the setting of the look of menu item names in a pop-up menu (where convention doesn't dictate that item properties match those of some other menu). The companion GetMenuFont() function is used to determine the current font characteristics of a particular menu.

Getting Ready for Mac OS X

As you get started programming for Mac OS 8.5, you may have Mac OS X on your mind. If you're concerned that your efforts traversing (traveling) the Allegro learning curve may be wasted, don't be. The new Toolbox routines you rely on to implement Allegro features will be present in the Mac OS X Carbon API. You can - and should - Carbon date your application's code to verify that these and other Toolbox routine invoked by your Mac application are Carbon-compliant. Carbon dating is a simple process that involves running Apple's Carbon Dater tool to analyze the code in a completed application. You email to Apple the text file that Carbon Dater generates and Apple, through an automated process, quickly analyzes the text file, generates a detailed Carbon-compatibility report in HTML format, and emails the report back to you. The Carbon Dater and instructions for its use can be downloaded from Apple at http://developer.apple.com/macosx/.

Last Word

This article provided an overview of the Appearance Manager and Navigation Services, two developer-related technologies that provide Mac OS 8.5 improvements visible to the user. To learn more about these technologies, download the Appearance Manager SDK (software developer kit) and the Navigation Services SDK from Apple at http://developer.apple.com/sdk. For more information on Appearance-related Toolbox functions, refer to the Mac OS 8 Toolbox Reference volume of Inside Macintosh. Details about Navigation Service functions can be found in Apple's Programming with Navigation Services document. Both of these documents are a part of their respective SDK. For overviews of Appearance Manager and Navigation Services, check out the two MacTech Magazine back issues cited earlier in this article.

Here you also read about several developer-related implementation changes, such as the handling of windows, that don't result in behavior changes noticeable to the user. What this article didn't give you was in-depth detail and complete sample code. Look for an update to the volumes of Inside Macintosh for a compilation of these changes. You'll also want to look to future issues of MacTech Magazine for more articles on Allegro-related technologies.

Dan Parks Sydow is the author of over a dozen Macintosh programming books.