CGPDFContext Reference

Derived from	`CGContextRef`
Framework	ApplicationServices/ApplicationServices.h
Companion guide	Quartz 2D Programming Guide
Declared in	CGPDFContext.h

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

Beginning and Ending Pages

Working with Destinations

Working with Metadata

Closing a PDF Context

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 iOS 2.0 and later.

Declared In

CGPDFContext.h

CGPDFContextAddDocumentMetadata

Associates custom metadata with the PDF document.

void CGPDFContextAddDocumentMetadata(
   CGContextRef context,
   CFDataRef metadata
);

Parameters

context: A PDF graphics context.
metadata: A stream of XML data that is formatted according to the Extensible Metadata Platform, as described in section 10.2.2., ‚ÄúMetadata Streams‚Äù, of the PDF 1.7 specification.

Availability

Available in iOS 4.0 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 iOS 2.0 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 iOS 2.0 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

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

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 iOS 2.0 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 iOS 2.0 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

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 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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.

Available in iOS 2.0 and later.

Declared in CGPDFContext.h.

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.

Available in iOS 2.0 and later.

Declared in CGPDFContext.h.

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.

Available in iOS 2.0 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

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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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 iOS 2.0 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

Last updated: 2010-04-30

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.