PMSessionSetDocumentFormatGeneration

Requests a specified spool file format and supplies the graphics context type to use for drawing pages within the print loop.

Declaration

OSStatus PMSessionSetDocumentFormatGeneration (
   PMPrintSession printSession,
   CFStringRef docFormat,
   CFArrayRef graphicsContextTypes,
   CFTypeRef options
);

Parameters

printSession:
The printing session whose spool file format and graphics context type you want to specify.
docFormat:
A Core Foundation string that specifies the desired spool file format as a MIME type. See Document_format_strings for a description of the constants you can use to specify the document format.
graphicsContexts:
A reference to a Core Foundation array of graphics contexts to use for drawing pages within the print loop. You can supply a QuickDraw graphics context (kPMGraphicsContextQuickDraw) or a Quartz 2D graphics context (kPMGraphicsContextCoreGraphics). An array of length 1 is the only length that is supported, regardless of graphics context type. See Graphics_context_types for a description of the constants you can use to specify a graphics context.
options:
Reserved for future use.

Return Value

A result code. See Result Codes.

Overview

You only need to call the function PMSessionSetDocumentFormatGeneration if you want to specify a format other than the default format (PDF) or a graphics context other than the default context (QuickDraw). If you want to use the default format for the operating system and to draw with QuickDraw, then you do not need to call this function. If you want to generate PICT + PS to use as one of the supported formats, then call PMSessionSetDocumentFormatGeneration to set the graphics context to QuickDraw and the format to PICT + PS. Note that the PICT + PS format is not available on Intel-based systems.

If you want to use a Quartz 2D graphics context to draw each page, you can call the following code to inform the printing system in all versions of macOS.

static OSStatus MyPMSessionBeginCGDocument (
    PMPrintSession printSession,
    PMPrintSettings printSettings,
    PMPageFormat pageFormat)
{
    OSStatus err = noErr;
 
    // Use the simpler call if it is present.
    if(&PMSessionBeginCGDocument != NULL) {
        err = PMSessionBeginCGDocument (printSession, printSettings, pageFormat);
    }
    else {
        CFStringRef s[1] = { kPMGraphicsContextCoreGraphics };
        CFArrayRef graphicsContextsArray = CFArrayCreate (
            kCFAllocatorDefault, (const void**)s, 1, &kCFTypeArrayCallBacks);
        err = PMSessionSetDocumentFormatGeneration (
            printSession, kPMDocumentFormatPDF, graphicsContextsArray, NULL);
        CFRelease (graphicsContextsArray);
        if(!err)
            err = PMSessionBeginDocument (
                printSession, printSettings, pageFormat);
    }
    return err;
}

The previous code informs the printing system that you want a Quartz graphics context, but you get the actual context for your printing port only after you call the function PMSessionBeginPage and then call the following code.

static OSStatus MyPMSessionGetCGGraphicsContext (
    PMPrintSession printSession,
    CGContextRef *printingContextP)
{
    OSStatus err = noErr;
 
    // Use the simpler call if it is present.
    if(&PMSessionGetCGGraphicsContext != NULL) {
        err = PMSessionGetCGGraphicsContext (printSession, printingContextP);
    }
    else {
        err = PMSessionGetGraphicsContext (
            printSession, kPMGraphicsContextCoreGraphics,
            (void**)printingContextP);
    }
    return err;
}

The printing context you get is a Quartz context into which you can draw. Note that the default coordinate system for Quartz 2D is not the same as that used for QuickDraw. Quartz 2D defines the coordinates of the lower-left corner of the sheet as (0,0) whereas the origin for the QuickDraw port is the upper-left corner of the imageable area.

You must call this function between the creation and release of a printing session. See the function PMCreateSession. You must call the function PMSessionSetDocumentFormatGeneration before you call PMSessionBeginDocument or PMSessionBeginDocumentNoDialog. Before requesting a spool file format using this function, you should call the function PMSessionGetDocumentFormatGeneration to get the list of supported formats.

Special Considerations

The PICT + PS spool file format is not available on Intel-based systems.