---

CGPDFContext Reference

Overview

The CGPDFContext header file defines functions that create and get information about a Quartz PDF context. A CGPDFContext object is a type of CGContextRef that is used for drawing PDF content. The functions in this reference operate only on Quartz PDF graphics contexts created using the functions CGPDFContextCreate or CGPDFContextCreateWithURL.

When you draw to the PDF context using CGContext functions the drawing operations are recorded in PDF format. The PDF commands that represent the drawing are written to the destination specified when you create the PDF graphics context.

Functions by Task

Creating a Context

• CGPDFContextCreate
• CGPDFContextCreateWithURL

Beginning and Ending Pages

• CGPDFContextBeginPage
• CGPDFContextEndPage

Working with Destinations

• CGPDFContextAddDestinationAtPoint
• CGPDFContextSetDestinationForRect
• CGPDFContextSetURLForRect

Closing a PDF Context

• CGPDFContextClose

Functions

CGPDFContextAddDestinationAtPoint

Sets a destination to jump to when a point in the current page of a PDF graphics context is clicked.

void CGPDFContextAddDestinationAtPoint (
   CGContextRef context,
   CFStringRef name,
   CGPoint point
);

Parameters

context

A PDF graphics context.

name

A destination name.

point

A location in the current page of the PDF graphics context.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

CGPDFContextBeginPage

Begins a new page in a PDF graphics context.

void CGPDFContextBeginPage (
   CGContextRef context,
   CFDictionaryRef pageInfo
);

Parameters

context

A PDF graphics context.

pageInfo

A dictionary that contains key-value pairs that define the page properties.

Discussion

You must call the function CGPDFContextEndPage to signal the end of the page.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

CGPDFContextClose

Closes a PDF document.

void CGPDFContextClose(
   CGContextRef context
);

Parameters

context

A PDF graphics context.

Discussion

After closing the context, all pending data is written to the context destination, and the PDF file is completed. No additional data can be written to the destination context after the PDF document is closed.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CGPDFContext.h

CGPDFContextCreate

Creates a PDF graphics context.

CGContextRef CGPDFContextCreate (
   CGDataConsumerRef consumer,
   const CGRect *mediaBox,
   CFDictionaryRef auxiliaryInfo
);

Parameters

consumer

The data consumer to receive the PDF output data.

mediaBox

A pointer to a rectangle that defines the size and location of the PDF page, or NULL. The origin of the rectangle should typically be (0,0). Quartz uses this rectangle as the default bounds of the page’s media box. If you pass NULL, Quartz uses a default page size of 8.5 by 11 inches (612 by 792 points).

auxiliaryInfo

A dictionary that specifies any additional information to be used by the PDF context when generating the PDF file, or NULL. The dictionary is retained by the new context, so on return you may safely release it. See “Auxiliary Dictionary Keys” for keys you can include in the dictionary.

Return Value

A new PDF context, or NULL if the context cannot be created. You are responsible for releasing this object using CGContextRelease.

Discussion

This function creates a PDF drawing environment to your specifications. When you draw into the new context, Quartz renders your drawing as a sequence of PDF drawing commands that are passed to the data consumer object.

Availability

• Available in Mac OS X version 10.0 and later.

Related Sample Code

• CarbonSketch

Declared In

CGPDFContext.h

CGPDFContextCreateWithURL

Creates a URL-based PDF graphics context.

CGContextRef CGPDFContextCreateWithURL (
   CFURLRef url,
   const CGRect *mediaBox,
   CFDictionaryRef auxiliaryInfo
);

Parameters

url

A Core Foundation URL that specifies where you want to place the resulting PDF file.

mediaBox

A rectangle that specifies the bounds of the PDF. The origin of the rectangle should typically be (0,0). The CGPDFContextCreateWithURL function uses this rectangle as the default page media bounding box. If you pass NULL, CGPDFContextCreateWithURL uses a default page size of 8.5 by 11 inches (612 by 792 points).

auxiliaryInfo

A dictionary that specifies any additional information to be used by the PDF context when generating the PDF file, or NULL. The dictionary is retained by the new context, so on return you may safely release it.

Return Value

A new PDF context, or NULL if a context could not be created. You are responsible for releasing this object using CGContextRelease.

Discussion

When you call this function, Quartz creates a PDF drawing environment—that is, a graphics context—to your specifications. When you draw into the resulting context, Quartz renders your drawing as a series of PDF drawing commands stored in the specified location.

Availability

• Available in Mac OS X version 10.0 and later.

Related Sample Code

• CarbonSketch

Declared In

CGPDFContext.h

CGPDFContextEndPage

Ends the current page in the PDF graphics context.

void CGPDFContextEndPage (
   CGContextRef context
);

Parameters

context

A PDF graphics context.

Discussion

You can call CGPDFContextEndPage only after you call the function CGPDFContextBeginPage.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

CGPDFContextSetDestinationForRect

Sets a destination to jump to when a rectangle in the current PDF page is clicked.

void CGPDFContextSetDestinationForRect (
   CGContextRef context,
   CFStringRef name,
   CGRect rect
);

Parameters

context

A PDF graphics context.

name

A destination name.

rect

A rectangle that specifies an area of the current page of a PDF graphics context. The rectangle is specified in default user space (not device space).

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

CGPDFContextSetURLForRect

Sets the URL associated with a rectangle in a PDF graphics context.

void CGPDFContextSetURLForRect (
   CGContextRef context,
   CFURLRef url,
   CGRect rect
);

Parameters

context

A PDF graphics context.

url

A CFURL object that specifies the destination of the contents associated with the rectangle.

rect

A rectangle specified in default user space (not device space).

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

Constants

Auxiliary Dictionary Keys

Keys that used to set up a PDF context.

CFStringRef kCGPDFContextAuthor;
CFStringRef kCGPDFContextCreator;
CFStringRef kCGPDFContextTitle;
CFStringRef kCGPDFContextOwnerPassword;
CFStringRef kCGPDFContextUserPassword;
CFStringRef kCGPDFContextAllowsPrinting;
CFStringRef kCGPDFContextAllowsCopying;
CFStringRef kCGPDFContextOutputIntent;
CFStringRef kCGPDFContextOutputIntents;
CFStringRef kCGPDFContextSubject;
CFStringRef kCGPDFContextKeywords;
CFStringRef kCGPDFContextEncryptionKeyLength;

Constants

kCGPDFContextAuthor

The corresponding value is a string that represents the name of the person who created the document. This key is optional.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextCreator

The corresponding value is a string that represents the name of the application used to produce the document. This key is optional.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextTitle

The corresponding value is a string that represents the title of the document. This key is optional.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextOwnerPassword

The owner password of the PDF document. If this key is specified, the document is encrypted using the value as the owner password; otherwise, the document will not be encrypted. The value of this key must be a CFString object that can be represented in ASCII encoding. Only the first 32 bytes are used for the password. There is no default value for this key. If the value of this key cannot be represented in ASCII, the document is not created and the creation function returns NULL.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextUserPassword

The user password of the PDF document. If the document is encrypted, then the value of this key will be the user password for the document. If not specified, the user password is the empty string. The value of this key must be a CFString object that can be represented in ASCII encoding; only the first 32 bytes will be used for the password. If the value of this key cannot be represented in ASCII, the document is not created and the creation function returns NULL.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextAllowsPrinting

Whether the document allows printing when unlocked with the user password. The value of this key must be a CFBoolean value. The default value of this key is kCFBooleanTrue.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextAllowsCopying

Whether the document allows copying when unlocked with the user password. The value of this key must be a CFBoolean object. The default value of this key is kCFBooleanTrue.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextOutputIntent

The output intent PDF/X. This key is optional. If present, the value of this key must be a CFDictionary object. The dictionary is added to the /OutputIntents entry in the PDF file document catalog. The keys and values contained in the dictionary must match those specified in section 9.10.4 of the PDF 1.4 specification, ISO/DIS 15930-3 document published by ISO/TC 130, and Adobe Technical Note #5413.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextOutputIntents

Output intent dictionaries. This key is optional. If present, the value must be an array of one or more kCGPDFContextOutputIntent dictionaries. The array is added to the PDF document in the /OutputIntents entry in the PDF file's document catalog. Each dictionary in the array must be of form specified for the kCGPDFContextOutputIntent key, except that only the first dictionary in the array is required to contain the "S" key with a value of GTS_PDFX. If both the kCGPDFContextOutputIntent and kCGPDFContextOutputIntents keys are specified, the former is ignored.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextSubject

The subject of a document. Optional; if present, the value of this key must be a CFString object.

Declared in CGPDFContext.h.

Available in Mac OS X v10.5 and later.

kCGPDFContextKeywords

The keywords for this document. This key is optional. If the value of this key is a CFString object, the /Keywords entry will be the specified string. If the value of this key is a CFArray object, then it must be an array of CFString objects. The /Keywords entry will, in this case, be the concatenation of the specified strings separated by commas (","). In addition, an entry with the key "/AAPL:Keywords" is stored in the document information dictionary; its value is an array consisting of each of the specified strings. The value of this key must be in one of the above forms; otherwise, this key is ignored.

Declared in CGPDFContext.h.

Available in Mac OS X v10.5 and later.

kCGPDFContextEncryptionKeyLength

The encryption key length in bits; see Table 3.18 "Entries common to all encryption dictionaries", PDF Reference: Adobe PDF version 1.5 (4th ed.) for more information. Optional; if present, the value of this key must be a CFNumber object with value which is a multiple of 8 between 40 and 128, inclusive. If this key is absent or invalid, the encryption key length defaults to 40 bits.

Declared in CGPDFContext.h.

Available in Mac OS X v10.5 and later.

Discussion

For more information about using these keys in a PDF context, see CGPDFContextCreate and CGPDFContextCreateWithURL.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

Box Dictionary Keys

Keys that specify various PDF boxes.

CFStringRef kCGPDFContextMediaBox
CFStringRef kCGPDFContextCropBox
CFStringRef kCGPDFContextBleedBox
CFStringRef kCGPDFContextTrimBox
CFStringRef kCGPDFContextArtBox

Constants

kCGPDFContextMediaBox

The media box for the document or for a given page. This key is optional. If present, the value of this key must be a CFData object that contains a CGRect (stored by value, not by reference).

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextCropBox

The crop box for the document or for a given page. This key is optional. If present, the value of this key must be a CFData object that contains a CGRect (stored by value, not by reference).

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextBleedBox

The bleed box for the document or for a given page. This key is optional. If present, the value of this key must be a CFData object that contains a CGRect (stored by value, not by reference).

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextTrimBox

The trim box for the document or for a given page. This key is optional. If present, the value of this key must be a CFData object that contains a CGRect (stored by value, not by reference).

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFContextArtBox

The art box for the document or for a given page. This key is optional. If present, the value of this key must be a CFData object that contains a CGRect (stored by value, not by reference).

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

Discussion

For more information about using these keys in a PDF context, see CGPDFContextCreate and CGPDFContextCreateWithURL.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

Output Intent Dictionary Keys

Keys to specify output intent options.

CFStringRef kCGPDFXOutputIntentSubtype;
CFStringRef kCGPDFXOutputConditionIdentifier;
CFStringRef kCGPDFXOutputCondition;
CFStringRef kCGPDFXRegistryName;
CFStringRef kCGPDFXInfo;
CFStringRef kCGPDFXDestinationOutputProfile;

Constants

kCGPDFXOutputIntentSubtype

The output intent subtype. This key is required. The value of this key must be a CFString object equal to "GTS_PDFX"; otherwise, the dictionary is ignored.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFXOutputConditionIdentifier

A string identifying the intended output device or production condition in a human- or machine-readable form. This key is required. The value of this key must be a CFString object. For best results, the string should be restricted to characters in the ASCII character set.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFXOutputCondition

A text string identifying the intended output device or production condition in a human- readable form. This key is optional. If present, the value of this key must be a CFString object.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFXRegistryName

A string identifying the registry in which the condition designated by kCGPDFXOutputConditionIdentifier is defined. This key is optional. If present, the value of this key must be a CFString object. For best results, the string should be lossless in ASCII encoding.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFXInfo

A human-readable text string containing additional information or comments about the intended target device or production condition. This key is required if the value of kCGPDFXOutputConditionIdentifier does not specify a standard production condition. It is optional otherwise. If present, the value of this key must be a CFString object.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

kCGPDFXDestinationOutputProfile

An ICC profile stream defining the transformation from the PDF document's source colors to output device colorants. This key is required if the value of kCGPDFXOutputConditionIdentifier does not specify a standard production condition. It is optional otherwise. If present, the value of this key must be an ICC-based color space specified as a CGColorSpace object.

Available in Mac OS X v10.4 and later.

Declared in CGPDFContext.h.

Discussion

For more information about using these keys in a PDF context, see CGPDFContextCreate and CGPDFContextCreateWithURL.

Availability

• Available in Mac OS X v10.4 and later.

Declared In

CGPDFContext.h

---