Legacy Document

Inside Macintosh: Macintosh Toolbox Essentials /

Chapter 7 - Finder Interface / Using the Finder Interface

Supporting Stationery Pads

Stationery pads are special documents that the user creates as templates. Opening
a stationery pad should not open the document itself; instead, it should open a new document with the same contents as the stationery pad. To turn any document into
a stationery pad, the user selects it, chooses Get Info from the File menu, and clicks
the Stationery pad checkbox in the information window. The Finder tags a document as being a stationery pad by setting the isStationery bit in the file's Finder flags field.

When the user opens a stationery pad from the Finder, the Finder first checks your application's size resource to see if your application supports stationery. The 'SIZE' resource tells the Finder and the Process Manager which features your application supports and how much memory to allocate when it starts up your application.
Listing 7-10 illustrates a size resource.

Listing 7-10 Rez input for a size resource

resource 'SIZE' (-1, purgeable)  {
   reserved,
   acceptSuspendResumeEvents,
   reserved,
   canBackground, 
   doesActivateOnFGSwitch, 
   backgroundAndForeground,
   dontGetFrontClicks,
   ignoreAppDiedEvents,
   is32BitCompatible,
   isHighLevelEventAware,
   localAndRemoteHLEvents,
   isStationeryAware,         /*support stationery pads*/
   dontUseTextEditServices,
   reserved, reserved, reserved,
   kPrefSize * 1024,
   kMinSize * 1024
};

Notice that the twelfth field, isStationeryAware, tells the Finder that this application supports stationery pads.

If the isStationeryAware bit is not set in the size resource, the Finder creates a
new document from the template and prompts the user for a name. The Finder then starts up your application as usual, passing it the name of the new document.

If the isStationeryAware bit is set, as shown in Listing 7-10, the Finder informs your application that the user has opened a document and passes your application the name of the stationery pad.

To support stationery, your application should

• specify the isStationeryAware constant in its size resource
• always check the isStationery bit of a document before opening it

Listing 7-11 on page 7-33 illustrates a simple function that takes a file system specification record and returns TRUE or FALSE, indicating whether the file is a stationery document or not.

Listing 7-11 Determining whether a document is a stationery pad

FUNCTION IsStationeryDoc (myFSSpec: FSSpec): Boolean;
VAR
    myErr:      OSErr;
    myFInfo:    FInfo;
BEGIN
    myErr := FSpGetFInfo(myFSSpec, myFInfo);
    IF myErr = noErr THEN
        IsStationeryDoc := BTST(myFInfo.fdFlags, isStationery)
    ELSE
        IsStationeryDoc := FALSE;
END;

The isStationery bit alone identifies whether a document is stationery. If the isStationery bit is set for a file that the user wants to open, your application should copy the template's contents into a new document and open the document in an untitled window. (For information about opening documents and about the File Manager function FSpGetFInfo, see Inside Macintosh: Files.)

Your application can check the sfFlags field of the standard file reply record to determine whether the isStationery bit is set. Unlike the Finder, the Standard File Package always passes your application the stationery pad itself, not a copy of it, regardless of the setting of the isStationery bit. When the user opens a stationery
pad from within your application, the Standard File Package checks your application's size resource. If your application does not support stationery, the Standard File Package displays an alert box warning the user that the stationery pad itself, not a copy of it,
is being opened. As you can see, the user can still easily change the template and mistakenly write over it by choosing Save without assigning a new name. You can prevent this unnecessary user frustration by making your application stationery-aware.

You can supply the icon to be displayed for stationery pads created from your application's documents by using the resources described in "Creating Icons for the Finder" beginning on page 7-10. If you do not supply your own stationery pad icon, the Finder uses the default stationery pad icon illustrated in Figure 7-5 on page 7-12.

In your documentation, tell users to choose the Get Info command to make stationery pads. You may also want to give examples of useful stationery pads created with your application. For example, if your application supports text and graphics, you may provide samples of stationery pads for business letterheads or billing statements.