Technical Note TN1058

QuickDraw GX 'ptyp' Resource: Calculations, Uses & Limitations

CONTENTS The 'ptyp' Resource Defined Calculating the Page and Paper Rectangle Values Making Your Paper Type the Default Type Making Sure Your New Paper Type Appears in the Print Dialog The Paper Type Editor Summary References Downloadables

For some time now, Apple developers have been confused by the 'ptyp' (paper type) resource in QuickDraw GX. This is a result of sparse documentation and problems with QuickDraw GX's use of this resource. This Technote: discusses the 'ptyp' resource in detail shows how to calculate your page and paper rectangles for the resource discusses how to set your paper type as the default paper type gives an overview of the known bugs and their workarounds gives a brief overview of how to create a paper type with QuickDraw GX's Paper Type Editor and how to alter those paper types into 'ptyp' resources. This Note is primarily intended for QuickDraw GX printer driver developers who wish to use the 'ptyp' resource in their printer drivers. Important for all Apple Printing and Graphics Developers: The information in this Technote is still relevant up to and including Mac OS 7.6 with QuickDraw GX 1.1.5. Beginning with the release of Mac OS 8.0, however, Apple plans to deliver a system which incorporates QuickDraw GX graphics and typography only. QuickDraw GX printer drivers and GX printing extensions will not be supported in Mac OS 8.0 or in future Mac OS releases. Apple's goal is to simplify the user experience of printing by unifying the Macintosh graphic and printing architectures and standardizing on the classic Printing Manager.  Updated: [July 1 1996]

The 'ptyp' Resource Defined

Table 3-9 on page 3-54 of Inside Macintosh: QuickDraw GX Printing Extensions and Drivers summarizes all of the possible resources that you can use in your QuickDraw GX printer driver. The 'ptyp' resource is mentioned in this table, but not discussed or documented further in the Inside Macintosh: QuickDraw GX series. GX printer driver developers need to understand the definition of this resource in order to create customized paper types for their drivers.

The following section introduces you to the internal structure of the 'ptyp' resource.

Definition

The paper type resource, of type gxPaperTypeType, provides you with a mechanism to create paper types that are customized for their QuickDraw GX printer driver. This resource is optional.

The structure of paper type resource is:

The paper type resource consists of entries, flags and one or more collection items:

• Paper Type Name: The name to display in the paper type list presented to the user in the page set-up dialog.
• Page Rectangle: The page rectangle measurements of the paper type.
• Paper Rectangle: The paper rectangle measurements of the paper type.
• Base Paper: The base paper type from which this new paper type is derived.

• Creator Type: The creator of the paper type.
• Unit of Measure: Unit of measure the paper is in.

• PaperType Style flags: Notates whether this paper type is for old, new or both old and new print dialogs.

- Collection tag:

A collection tag is a four-character identifier that, in conjunction with the collection ID, uniquely identifies the collection item.

- Collection ID:

A collection ID is a long value that, in conjunction with the collection tag, uniquely identifies the collection item.

- Collection attribute bits- lock:

locks the item down to avoid replacement.

- Collection attribute bits- persistent:

identifies whether or not to flatten this item when flattening the collection.

- Reserved attribute bits:

bits that are reserved internally.

- User attribute bits:

bits you can define for purposes suitable to your needs.

- Data:

contains the actual data of the collection item.

For more information on collection items, see Chapter 5 of Inside Macintosh: QuickDraw GX Environment and Utilities.

The structure of the 'ptyp' resource can be seen in GXPrintingResTypes.r on the Developer CD Series: Mac OS SDK Edition.

Back to top

Calculating the Page and Paper Rectangle Values

Developers often ask how to calculate the hexadecimal values from their page size. For instance, if you have US Letter paper with a page rectangle that measures 8.10667 inches by 10.7867 inches, what hexadecimal values do you place in the page rectangle area of the 'ptyp' resource? To calculate the correct value for the horizontal measurement, simply follow these steps:

1. Convert inches to pixels. Multiply 8.10667 by 72 (for 72 dpi). The result is 583.68005 pixels.
2. Convert the pixel value to hexadecimal to get 0x0247AE18.
   For the vertical value, repeat steps 1 and 2, multiplying 10.7867 inches instead of 8.10667.

The same calculation steps also are valid for calculations of the paper size area in the 'ptyp' resource.

Once you are finished with the calculations, the top portion of your 'ptyp' resource will look like the following:

resource gxPaperTypeType (gxPrintingDriverBaseID+1, "US Letter",
kResAttributes)
{

"US Letter",

/*page rectangle*/
0x00000000,     /*0.0*/
0x00000000,     /*0.0*/
0x0247AE18,     /*8.10667*/
0x0308A3DC,     /*10.7867*/

/*paper rectangle*/
0xFFF1D70C,     /*-0.196666*/
0xFFF870A8,     /*-0.104999*/
0x0247AE18,     /*8.30333*/
0x0308A3DC,     /*10.895*/

usLetterType,
kCreatorType,

inch,
etc.
}

Back to top

Making Your Paper Type the Default Type

This section introduces you to a flag to make your new paper type the default in your printer driver. It also discusses some known bugs in QuickDraw GX and their workarounds.

The Flag

In order to set your paper type as the default, you need to set the isDefaultPaperType flag in your 'ptyp' resource. Setting this flag lets QuickDraw GX "know" that this is the paper type your driver should default to.

If QuickDraw GX encounters more than one paper type in your driver with the isDefaultPaperType flag set, QuickDraw GX will either fail or choose the first paper type it "sees." In either case, it is not a good idea to have more than one paper type in your resource fork with the isDefaultPaperType flag set.

A Known bug

There is a known bug in QuickDraw GX related to default paper types and paper matching. For instance, if you set a default paper type of 'A4 portrait' in your driver, it often does not turn out to be the default paper type in your print dialog. The reason is that QuickDraw GX internally adds the standard papertypes (e.g., A4, US Letter, etc,) to your driver. During paper matching QuickDraw GX "thinks" it is finding a better fit for the current page dimensions than the assigned 'A4 portrait' papertype. It will then default to QuickDraw GX's internal A4 papertype instead.

Several Workarounds

There are a few workarounds to this bug, depending on the behavior you are seeing.

Workaround #1:

If you are defaulting to a non-standard papertype, such as Letterhead, Stationery or Three-hole Punch, the best workaround is to remove that papertype from the Extensions folder.

Workaround #2:

If you are defaulting to another standard papertype, the easiest thing you can do is to open your driver with ResEdit and either remove or edit the 'ptyp' resource for the incorrectly matched papertype.

Currently, these are the only known workarounds. Neither may be very user-friendly, but in both cases, they ought to force the driver to default to the correct papertype.

Back to top

Making Sure Your New Paper Type Appears in the Print Dialog

Many GX developers want their paper types to appear in the print dialogs. In order for this to happen for both old and new print dialogs, two conditions must be met: First, the 'ptyp' resource must be present in the resource fork of the driver, as opposed to a paper type file in the System Extensions folder. Second, the 'ptyp' must have the oldAndNewStylePaperType flag set. If you want to limit the paper types to just old or new print dialogs, you can set either the oldStylePaperType or the newStylePaperType flags.

Back to top

The Paper Type Editor

QuickDraw GX ships with the Paper Type Editor utility. You can install this utility from the GX utilities section when you install QuickDraw GX on your Macintosh. The Paper Type Editor allows you to create your own custom paper types, which are then placed in the Extensions folder.

Developers are usually interested in how they can use the Paper Type Editor to create paper type resources to ship with their QuickDraw GX printer drivers. In order to convert the paper type that the Paper Type Editor creates into a 'ptyp' resource, you need to DeRez the paper type, set the oldAndNewStylePaperType flag (and the isDefaultPaperType flag if necessary), Rez it back and copy it into your printer driver's resource fork. After restarting, the paper types should correctly appear in your QuickDraw GX printer driver.

Back to top

Summary

The 'ptyp' resource can very useful to QuickDraw GX printer driver developers because it allows you to create custom paper types. The 'ptyp' resource is not adequately documented in the Inside Macintosh: QuickDraw GX suite of books. Despite some known bugs with the QuickDraw GX's use of the resource, there are several good workarounds to allow you to continue with your GX development.

Back to top

References

Inside Macintosh: QuickDraw GX Printing Extensions and Drivers.

Inside Macintosh: QuickDraw GX Printing.

Inside Macintosh: QuickDraw GX Environment and Utilities.

Macintosh Technical Note 1028.

Developer CD Series: Mac OS SDK Edition: Development Kits (Disc I): Interfaces and Libraries: Interfaces: RIncludes: GXPrintingResTypes.r.

Back to top

Downloadables

Back to top