Technotes


Download

Acrobat file (159K)
Download

ClarisWorks 4 file (44K)
QuickView version

not available yet

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



Technote 1058JULY 1996



By Ingrid Kelly

Apple Developer Technical Support (DTS)

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 :

This Note is primarily intended for QuickDraw GX printer driver developers who wish to use the 'ptyp' resource in their printer drivers.

CONTENTS

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.

For details on Apple's official announcement, refer to </technotes/gxchange.html>

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:

'ptyp' Type
Paper Type Name pstring
Page Rectangle gxRectangle
Paper Rectangle gxRectangle
Base Paper longint
Creator Type literal longint
Unit of Measure byte
PaperType Style flags unsigned bitstring
Default flags unsigned bitstring
Reserved flags unsigned bitstring
Embedded Collection longint
array- Collection Items
- Collection tag longint
- Collection id longint
- Collection attribute bits- lock Boolean
- Collection attribute bits- persistent Boolean
- Reserved attribute bits unsigned bitstring
- User attribute bits unsigned bitstring
- Data wstring

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

The Collection Item entries tell QuickDraw GX about the paper type's collection information and include the following fields:
- 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.

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.
}

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.

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.

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.

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.

Further References

Acknowledgments

Thanks to Daniel Lipton, Guillermo Ortiz and Dave Polaschek for reviewing this Technote.




Technotes
Previous Technote | Contents | Next Technote