Technical Q&A GXNEW01

Differences between QuickDraw GX 1.1.1 and 1.0.x

If there is a gxDriverOutputType resource in the DTP, the user cannot bring up the Input Trays dialog. Is this something that the driver has to put in the DTP when it is created?

A Unfortunately, the GX v1.1.1b1 release notes are missing some important information regarding the API changes made to GX printing.

Here's the missing information from the QuickDraw GX v1.1.b1 Release Notes:

New resource: 'mfpr'

The following resource has been added to allow disabling of manual-feed alerts on a desktop-printer by desktop-printer basis. If a desktop printer contains a 'mfpr' resource with ID gxPrintingBaseID, and QuickDraw GX is initiating the alert, the decision whether to display alerts is based on the following structure:

REZ:

// Resource type for manual feed preferences, stored in DTP.

#define gxManualFeedAlertPrefsType 'mfpr'
#define gxManualFeedAlertPrefsID  (gxPrintingDriverBaseID)


// Desktop printer resource to specify manual feed alert preferences. ('mfpr')

#define gxShowAlerts  0x00000001        // Enable manual feed alerts (default).
#define gxAlertOnPaperChange 0x00000002 // ...but only if the
                                        // papertype changes

type gxManualFeedAlertPrefsType {
   unsigned bitstring[16]; // flags -- for driver's private use.
   unsigned bitstring[16]; // flags -- predefined. gxShowAlerts,
                           // gxShowAlerts +gxAlertOnPaperChange,
                           // or 0.
};

C:

struct gxManualFeedAlertPrefs {
   longalertFlags; //  flags -- first word is for driver's private
                   //  use, the rest is predefined.
};
typedef struct gxManualFeedAlertPrefs gxManualFeedAlertPrefs,
 *gxManualFeedAlertPrefsPtr, **gxManualFeedAlertPrefsHdl;

enum { // bit fields in alertFlags field of gxManualFeedAlertPrefs.
   gxShowAlerts = 0x00000001,          // Show alerts for this desktop printer.
   gxAlertOnPaperChange = 0x00000002   // ...only if the papertype changes.
};

#define gxDefaultMFeedAlertSettings (gxShowAlerts | gxAlertOnPaperChange)

The first word of the structure is for driver use.

If the gxShowAlerts bit is set, manual-feed alerts are displayed. In addition, if the gxAlertOnPaperChange bit is set, alerts are only displayed when the manually fed papertype is not the same as the last papertype printed on.

Here are some examples of what the flags do:

Settings: alertFlags = 0 or alertFlags = gxAlertOnPaperChange

No manual feed alerts are generated by QuickDraw GX, since the gxShowAlerts mask isn't set.

Settings: alertFlags = gxShowAlerts

Manual feed alerts are generated for every manually fed page.

Given a document consisting of seven pages:

1. auto feed US Letter

2. manual feed A4

3. manual feed A4

4. auto feed B5

5. manual feed A4

6. manual feed US Legal

7. manual feed US Legal

Manual feed alerts are displayed for pages 2, 3, 5, 6, and 7.

Settings: alertFlags = gxShowAlerts | gxAlertOnPaperChange

Manual feed alerts are generated for every manually fed page that doesn't use the same papertype as the previous page.

Given a document consisting of seven pages:

1. auto feed US Letter

2. manual feed A4

3. manual feed A4

4. auto feed B5

5. manual feed A4

6. manual feed US Legal

7. manual feed US Legal

Manual feed alerts are displayed for pages 2, 5, and 6.

gxShowAlerts | gxAlertOnPaperChange are the default settings if no resource is found in the desktop printer.

The information in this structure is only used if QuickDraw GX is generating the alert (i.e., the driver isn't generating the alert via GXAlertTheUser). For consistency, we recommend that printer-driver developers who want to allow enabling and disabling of manual-feed alerts do so based on this resource type.

New resource: 'outp'

The 'outp' resource allows printer drivers to indicate the characteristics of a desktop printer's output device. This resource indicates whether or not the desktop printer is an output device that can be configurable for different papertypes. For example, for the GeoPort express modem driver, it makes no sense to display paper-mismatch or manual-feed dialogs, since the user cannot configure the device with different paper. The structure of the 'outp' resource follows:

REZ:

// Resource type for desktop printer output characteristics, stored in DTP.

#define gxDriverOutputType 'outp'
#define gxDriverOutputTypeID   (1)

// Desktop printer resource to specify whether
// or not this desktop printer has trays.

#define gxCanConfigureTrays0x00000001  // Can configure trays for
                                       // this printer.

type gxDriverOutputType {
   longint; // flags -- for driver's private use.
   longint; // flags -- predefined. Currently,
            // gxCanConfigureTrays or 0.
};


C:
enum { // bit fields in outputSettings field of GXDriverOutputSettings.
   gxCanConfigureTrays = 0x00000001 // Desktop printer represents a
                                    // device with a paper feed.
};

typedef struct GXDriverOutputSettings {
   longdriverflags;     //  flags -- for use by driver.
   longoutputSettings;  //  flags -- predefined.
} GXDriverOutputSettings, *GXDriverOutputSettingsPtr,
  **GXDriverOutputSettingsHdl;

The first longword is for the driver's private use.

If the desktop printer contains an 'outp' resource that has the gxCanConfigureTrays mask set in the second longword (or the resource is not available), mismatch and manual-feed alerts are displayed as usual. If the resource contains an 'outp' resource without the gxCanConfigureTrays mask set, no mismatch or manual-feed alerts are generated. In this case, paper mismatching behaves as "Blast and Pray," meaning that QuickDraw GX expects that the requested papertype is in the device.

Notes:

Since the resource ID of the gxDriverOutputType resource is positive, it is downloaded to all clients of a shared desktop printer at device-communication time. Because this resource is stored in the desktop printer, it is possible for a driver which supports "tray configurable" desktop printers, as well as those that aren't, to create both types of desktop printers. Normally, the gxDriverOutputType resource is stored in a desktop printer (using GXWriteDTPData) in an override to gxDefaultDesktopPrinter after forwarding the message.

If no 'outp' resource is found in the desktop printer, QuickDraw GX assumes that the desktop printer is tray-configurable, and displays the manual-feed and paper-mismatch alerts, unless the output is directed to a disk file, as indicated by the job's 'dest' job-collection item.

New Message:

    gxSetupPageImageData (available only in builds 1.1.1a4 and later)

A new message, which indicates the final format, page shape, and imaging data for a given page, was added. Note that, until this message is sent, these parameters are subject to change. The gxSetupPageImageData message is sent once for every page, just prior to gxStartSendPage. Driver writers may wish to override this message to determine the final characteristics of the data to be sent to the printer. Overrides should forward the gxSetupPageImageData message.

Prototypes:

OSErr Send_GXSetupPageImageData (gxFormat theFormat, gxShape thePage,
void *imageData);

OSErr Forward_GXSetupPageImageData (gxFormat theFormat, gxShape thePage,
void *imageData);

New Message:

    gxPostScriptEjectPendingPage

A new message has been added to the PostScript engine within QuickDraw GX. gxPostScriptEjectPendingPage checks to see if there's a previously imaged page waiting to be ejected, and if there is, sends the gxPostScriptEjectPage message for it. On return, the pageWasEjected parameter is set to true if a page was ejected, and false otherwise. Overrides should forward the gxPostScriptEjectPendingPage message.

Note: This message is most useful for PostScript drivers which do their own page handling. For example, if a driver is going to display a manual-feed alert, it's usually desirable to eject the previous page (if any) before asking the user to insert the manual-feed paper. This can be accomplished by sending the gxPostScriptEjectPendingPage message.

OSErr Send_GXPostScriptEjectPendingPage (long ejectFlags,
Boolean *pageWasEjected);

OSErr Forward_GXPostScriptEjectPendingPage (long ejectFlags,
Boolean *pageWasEjected);

Note that, as of the beta release of QuickDraw GX 1.1.1, the override will be:

OSErr Send_GXPostScriptEjectPendingPage (Boolean *pageWasEjected);

OSErr Forward_GXPostScriptEjectPendingPage (Boolean *pageWasEjected);

In other words, the ejectFlags parameter was removed.

Other changes and areas to test:

New dialogs:

The paper-matching and manual-feed operation were extensively rewritten. Tiling and manual-feed options were added to the paper-mismatch dialog, and automatic feeding (and crop, scale, and tile) options were added to the manual-feed dialog of the Laserwriter.

Please confirm that your drivers and extensions behave as expected with the new dialogs. Note that the new "expected behavior" is that desktop printers with configurable trays generate a paper mismatch whenever the paper a document is formatted for is not in the printer in use. This includes desktop printers which have never been configured. This represents a change in behavior from GX 1.0.1 and 1.0.2, which used to "Blast and Pray" to unconfigured desktop printers. This change was made because QuickDraw GX printing is more likely to produce the desired results once a desktop printer is configured, and many new users won't realize that they need to configure desktop printers from the Finder's Printing menu. To make this default behavior less inconvenient, mismatch dialogs which are invoked for an unconfigured desktop printer will default to "Load tray XXX with YYY paper," and have the "Make change permanent" checkbox selected. Therefore, simply clicking continue (or hitting enter) configures the desktop printer.

Raster and PostScript paper mismatch handling:

Paper-mismatch handling for raster and PostScript drivers is dramatically improved. If your driver doesn't perform paper-mismatch handling (cropping, scaling, tiling, and redirecting to different trays) as expected, make sure that your driver does not make assumptions about the page's format or imageDataHandle prior to sending the new gxSetupPageImageData message. There are a number of drivers which expect the page shape, format, and imageDataHandle available at gxDespoolPage time to be the ones actually used to image the page. In the case of a paper mismatch, or of output modifying printing extensions, this is an invalid assumption which causes paper-mismatch handling to generate improper output.

Note: The LaserWriter IIsc sample which shipped on the QuickDraw GX 1.0 SDK had the same problem. A new sample is available through Developer Technical Support.

Updated: 1-May-95