![]() Acrobat file (159K) |
![]() ClarisWorks 4 file (44K) |
![]() not available yet |
Technote 1058 | JULY 1996 |
By Ingrid Kelly
inge@apple.com
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 :
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:
Constant |
|
unknownBase |
|
usLetterBase |
|
usLegalBase |
|
a4LetterBase |
|
b5LetterBase |
|
tabloidBase |
|
Constant |
|
pica |
|
mm |
|
inch |
|
Constant |
|
newStylePaperType |
|
oldStylePaperType |
|
oldAndNewStylePaperType |
|
The structure of the 'ptyp' resource can be seen in GXPrintingResTypes.r on the Developer CD Series: Mac OS SDK Edition.
For the vertical value, repeat steps 1 and 2, multiplying 10.7867 inches
instead of 8.10667.
Once you are finished with the calculations, the top portion of your 'ptyp'
resource will look like the following:
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.
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.
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.
Main |
Top of Section |
What's New |
Apple Computer, Inc. |
Find It |
Feedback |
Help
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:
The same calculation steps also are valid for calculations of the paper size
area in the 'ptyp' resource.
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.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.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. 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