ADC Home > Reference Library > Reference > Cocoa > Printing > NSPrintOperation Class Reference >

Next Page > Hide TOC

NSPrintOperation Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in Mac OS X v10.0 and later.
Companion guide
Declared in
NSPrintOperation.h
Related sample code

Overview

An NSPrintOperation object controls operations that generate Encapsulated PostScript (EPS) code, Portable Document Format (PDF) code, or print jobs. An NSPrintOperation object works in conjunction with two other objects: an NSPrintInfo object, which specifies how the code should be generated, and an NSView object, which generates the actual code.

It is important to note that the majority of methods in NSPrintOperation copy the instance of NSPrintInfo passed into them. Future changes to that print info are not reflected in the print info retained by the current NSPrintOperation object. All changes should be made to the print info before passing to the methods of this class. The only method in NSPrintOperation which does not copy the NSPrintInfo instance is setPrintInfo:.

Note: You should not subclass NSPrintOperation. Methods that return an NSPrintOperation object return an instance of a concrete subclass whose implementation is private.

Tasks

Creating an NSPrintOperation

Setting the Current NSPrintOperation for This Thread

Determining the Type of Operation

Modifying the NSPrintInfo Object

Getting the NSView Object

Running a Print Operation

Modifying the User Interface

Managing the Drawing Context

Managing Page Information

Managing Printing-Related Threads

Deprecated Methods

Class Methods

currentOperation

Returns the current print operation for this thread.

+ (NSPrintOperation *)currentOperation

Return Value

The print operation object, or nil if there is no current operation.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

EPSOperationWithView:insideRect:toData:

Creates and returns a new NSPrintOperation object ready to control the copying of EPS graphics from the specified view.

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView insideRect:(NSRect)rect toData:(NSMutableData *)data

Parameters
aView

The view containing the data to be turned into EPS data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as EPS data.

data

An empty NSMutableData object. After the job is run, this object contains the EPS data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the EPS data.

Discussion

The new NSPrintOperation object uses the default NSPrintInfo object. This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

EPSOperationWithView:insideRect:toData:printInfo:

Creates and returns a new NSPrintOperation object ready to control the copying of EPS graphics from the specified view using the specified print settings.

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView insideRect:(NSRect)rect toData:(NSMutableData *)data printInfo:(NSPrintInfo *)aPrintInfo

Parameters
aView

The view containing the data to be turned into EPS data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as EPS data.

data

An empty NSMutableData object. After the job is run, this object contains the EPS data.

aPrintInfo

The print settings to use when generating the EPS data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the EPS data.

Discussion

This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

EPSOperationWithView:insideRect:toPath:printInfo:

Creates and returns a new NSPrintOperation object ready to control the copying of EPS graphics from the specified view and write the resulting data to the specified file.

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView insideRect:(NSRect)rect toPath:(NSString *)path printInfo:(NSPrintInfo *)aPrintInfo

Parameters
aView

The view containing the data to be turned into EPS data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as EPS data.

path

The path to a file. After the job is run, this file contains the EPS data.

aPrintInfo

The print settings to use when generating the EPS data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the EPS data.

Discussion

This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

PDFOperationWithView:insideRect:toData:

Creates and returns a new NSPrintOperation object ready to control the copying of PDF graphics from the specified view.

+ (NSPrintOperation *)PDFOperationWithView:(NSView *)aView insideRect:(NSRect)rect toData:(NSMutableData *)data

Parameters
aView

The view containing the data to be turned into PDF data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as PDF data.

data

An empty NSMutableData object. After the job is run, this object contains the PDF data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the PDF data.

Discussion

The new NSPrintOperation object uses the default NSPrintInfo object. This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

PDFOperationWithView:insideRect:toData:printInfo:

Creates and returns a new NSPrintOperation object ready to control the copying of PDF graphics from the specified view using the specified print settings.

+ (NSPrintOperation *)PDFOperationWithView:(NSView *)aView insideRect:(NSRect)rect toData:(NSMutableData *)data printInfo:(NSPrintInfo *)aPrintInfo

Parameters
aView

The view containing the data to be turned into PDF data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as PDF data.

data

An empty NSMutableData object. After the job is run, this object contains the PDF data.

aPrintInfo

The print settings to use when generating the PDF data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the PDF data.

Discussion

This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

PDFOperationWithView:insideRect:toPath:printInfo:

Creates and returns a new NSPrintOperation object ready to control the copying of PDF graphics from the specified view and write the resulting data to the specified file.

+ (NSPrintOperation *)PDFOperationWithView:(NSView *)aView insideRect:(NSRect)rect toPath:(NSString *)path printInfo:(NSPrintInfo *)aPrintInfo

Parameters
aView

The view containing the data to be turned into PDF data.

rect

The portion of the view (specified in points in the view's coordinate space) to be rendered as PDF data.

path

The path to a file. After the job is run, this file contains the PDF data.

aPrintInfo

The print settings to use when generating the PDF data.

Return Value

The new NSPrintOperation object. You must run the operation to generate the PDF data.

Discussion

This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Declared In
NSPrintOperation.h

printOperationWithView:

Creates and returns an NSPrintOperation object ready to control the printing of the specified view.

+ (NSPrintOperation *)printOperationWithView:(NSView *)aView

Parameters
aView

The view whose contents you want to print.

Return Value

The new NSPrintOperation object. You must run the operation to print the view.

Discussion

The new NSPrintOperation object uses the settings stored in the shared NSPrintInfo object. This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

printOperationWithView:printInfo:

Creates and returns an NSPrintOperation object ready to control the printing of the specified view using custom print settings.

+ (NSPrintOperation *)printOperationWithView:(NSView *)aView printInfo:(NSPrintInfo *)aPrintInfo

Parameters
aView

The view whose contents you want to print.

aPrintInfo

The print settings to use when printing the view.

Return Value

The new NSPrintOperation object. You must run the operation to print the view.

Discussion

This method raises an NSPrintOperationExistsException if there is already a print operation in progress; otherwise the returned object is made the current print operation for this thread.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

setCurrentOperation:

Sets the current print operation for this thread.

+ (void)setCurrentOperation:(NSPrintOperation *)operation

Parameters
operation

The print operation to make current. You may specify nil to clear the current print operation.

Availability
See Also
Declared In
NSPrintOperation.h

Instance Methods

canSpawnSeparateThread

Returns a Boolean value indicating whether the receiver is allowed to spawn a separate printing thread.

- (BOOL)canSpawnSeparateThread

Return Value

YES if the receiver is allowed to spawn a separate thread; otherwise, NO.

Availability
See Also
Declared In
NSPrintOperation.h

cleanUpOperation

Called at the end of a print operation to remove the receiver as the current operation.

- (void)cleanUpOperation

Discussion

You typically do not invoke this method directly.

Availability
See Also
Declared In
NSPrintOperation.h

context

Returns the graphics context object used for generating output.

- (NSGraphicsContext *)context

Return Value

The graphics context object used for drawing during the operation.

Availability
See Also
Declared In
NSPrintOperation.h

createContext

Creates the graphics context object used for drawing during the operation.

- (NSGraphicsContext *)createContext

Return Value

The graphics context object used for drawing. This object is created using the settings from the receiver's NSPrintInfo object.

Discussion

Do not invoke this method directly—it is invoked before any output is generated.

Availability
See Also
Declared In
NSPrintOperation.h

currentPage

Returns the current page number being printed.

- (NSInteger)currentPage

Return Value

The current page being printed.

Availability
See Also
Declared In
NSPrintOperation.h

deliverResult

Delivers the results of the print operation to the intended destination.

- (BOOL)deliverResult

Return Value

YES if the results were successfully delivered; otherwise, NO.

Discussion

This method may be called to deliver the results to the printer spool or preview application. Do not invoke this method directly—it is invoked automatically when the print operation is done.

Availability
See Also
Declared In
NSPrintOperation.h

destroyContext

Destroys the receiver’s graphics context.

- (void)destroyContext

Discussion

Do not invoke this method directly—it is invoked at the end of a print operation.

Availability
See Also
Declared In
NSPrintOperation.h

isCopyingOperation

Returns a Boolean value indicating whether the receiver is an EPS or PDF copy operation.

- (BOOL)isCopyingOperation

Return Value

YES if the receiver is an EPS or PDF copy operation; otherwise, NO.

Availability
Declared In
NSPrintOperation.h

jobTitle

Returns the title of the print job.

- (NSString *)jobTitle

Return Value

A string containing the print job title. If set, this value overrides the title returned by the printing view.

Availability
See Also
Declared In
NSPrintOperation.h

pageOrder

Returns the print order for the pages.

- (NSPrintingPageOrder)pageOrder

Return Value

The print order. For a list of possible values, see “Constants.”

Availability
See Also
Declared In
NSPrintOperation.h

pageRange

Returns the range of pages associated with the print operation.

- (NSRange)pageRange

Return Value

The range of page numbers. Page numbers are one-based values where the index of page one is 1, the index of page two is 2, and so on. Depending on the information returned by the printing view, the starting page number may not be 1. Also, if the number of pages being printed is not known, the page count may be set to NSIntegerMax.

Availability
See Also
Declared In
NSPrintOperation.h

printInfo

Returns the receiver’s NSPrintInfo object.

- (NSPrintInfo *)printInfo

Return Value

The print settings of the receiver.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

printPanel

Returns the NSPrintPanel object used when running the operation.

- (NSPrintPanel *)printPanel

Return Value

The print panel object for the operation.

Availability
See Also
Declared In
NSPrintOperation.h

runOperation

Runs the print operation on the current thread.

- (BOOL)runOperation

Return Value

YES if the operation was successful; otherwise, NO.

Discussion

The operation runs to completion in the current thread, blocking the application. A separate thread is not spawned, even if canSpawnSeparateThread is YES. Use runOperationModalForWindow:delegate:didRunSelector:contextInfo: to use document-modal sheets and to allow a separate thread to perform the operation.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

runOperationModalForWindow:delegate:didRunSelector:contextInfo:

Runs the print operation, calling your custom delegate method upon completion.

- (void)runOperationModalForWindow:(NSWindow *)docWindow delegate:(id)delegate didRunSelector:(SEL)didRunSelector contextInfo:(void *)contextInfo

Parameters
docWindow

The document window to receive a print progress sheet.

delegate

The printing delegate object. Messages are sent to this object.

didRunSelector

The delegate method called after the completion of the print operation.

contextInfo

A pointer to any data you want passed to the method in the didRunSelector parameter.

Discussion

The method specified by the didRunSelector parameter must have the following signature:

- (void)printOperationDidRun:(NSPrintOperation *)printOperation  success:(BOOL)success  contextInfo:(void *)contextInfo

The value of success is YES if the print operation ran to completion without cancellation or error, and NO otherwise.

If you send setCanSpawnSeparateThread: to an NSPrintOperation object with an argument of YES, then the delegate specified in a subsequent invocation of runOperationModalForWindow:delegate:didRunSelector:contextInfo: may be messaged in that spawned, non-main thread.

Availability
Related Sample Code
Declared In
NSPrintOperation.h

setCanSpawnSeparateThread:

Sets whether the receiver is allowed to spawn a separate printing thread.

- (void)setCanSpawnSeparateThread:(BOOL)canSpawnSeparateThread

Parameters
canSpawnSeparateThread

YES if the receiver is allowed to spawn a separate thread; otherwise, NO.

Discussion

If canSpawnSeparateThread is YES, an NSThread object is detached when the print panel is dismissed (or immediately, if the panel is not to be displayed). The new thread performs the print operation, so that control can return to your application. A thread is detached only if the print operation is run using the runOperationModalForWindow:delegate:didRunSelector:contextInfo: method. If canSpawnSeparateThread is NO, the operation runs on the current thread, blocking the application until the operation completes.

If you send setCanSpawnSeparateThread: to an NSPrintOperation object with an argument of YES, then the delegate specified in a subsequent invocation of runOperationModalForWindow:delegate:didRunSelector:contextInfo: may be messaged in that spawned, non-main thread.

Availability
See Also
Related Sample Code
Declared In
NSPrintOperation.h

setJobTitle:

Assigns a custom title to the print job.

- (void)setJobTitle:(NSString *)jobTitle

Parameters
jobTitle

The print job title. The receiver makes its own copy of the specified string.

Discussion

Assigning a title with this method overrides the job title provided by the printing view’s printJobTitle method. Specifying nil for the jobTitle parameter causes the receiver to once again take its title from the printing view.

Availability
See Also
Declared In
NSPrintOperation.h

setPageOrder:

Sets the print order for the pages of the operation.

- (void)setPageOrder:(NSPrintingPageOrder)order

Parameters
order

The print order. For a list of possible values, see “Constants.”

Availability
See Also
Declared In
NSPrintOperation.h

setPrintInfo:

Sets the receiver’s NSPrintInfo object.

- (void)setPrintInfo:(NSPrintInfo *)aPrintInfo

Parameters
aPrintInfo

The new print settings for the receiver.

Availability
See Also
Declared In
NSPrintOperation.h

setPrintPanel:

Sets the NSPrintPanel object to be used during the operation.

- (void)setPrintPanel:(NSPrintPanel *)panel

Parameters
panel

The print panel object to use for the operation.

Availability
See Also
Declared In
NSPrintOperation.h

setShowsPrintPanel:

Sets whether the receiver displays a print panel for this operation.

- (void)setShowsPrintPanel:(BOOL)flag

Parameters
flag

YES if you want to display a print panel; otherwise, NO.

Discussion

This method does not affect the display of a progress panel; that operation is controlled by the setShowsProgressPanel: method.

Operations that generate EPS or PDF data do no display a progress panel, regardless of the value in the flag parameter.

Availability
See Also
Declared In
NSPrintOperation.h

setShowsProgressPanel:

Sets whether the receiver displays a progress panel for this operation.

- (void)setShowsProgressPanel:(BOOL)flag

Parameters
flag

YES if you want to display a progress panel; otherwise, NO.

Discussion

This method does not affect the display of a print panel; that operation is controlled by the setShowsPrintPanel: method.

Operations that generate EPS or PDF data do no display a progress panel, regardless of the value in the flag parameter.

Availability
See Also
Declared In
NSPrintOperation.h

showsPrintPanel

Returns a Boolean value indicating whether a print panel is displayed during the operation,

- (BOOL)showsPrintPanel

Return Value

YES if the operation displays a print panel; otherwise, NO.

Discussion

Operations that generate EPS or PDF data do no display a print panel (instance of NSPrintPanel), regardless of the value returned by this method.

Availability
See Also
Declared In
NSPrintOperation.h

showsProgressPanel

Returns a Boolean value indicating whether a progress panel is displayed during the operation.

- (BOOL)showsProgressPanel

Return Value

YES if the operation displays a progress panel; otherwise, NO.

Discussion

Operations that generate EPS or PDF data do no display a progress panel, regardless of the value returned by this method.

Availability
See Also
Declared In
NSPrintOperation.h

view

Returns the view object that generates the actual data for the print operation.

- (NSView *)view

Return Value

The view object that generates the data.

Availability
Declared In
NSPrintOperation.h

Constants

NSPrintingPageOrder

These constants specify the page order. 

typedef enum _NSPrintingPageOrder {
   NSDescendingPageOrder = (-1),
   NSSpecialPageOrder    = 0,
   NSAscendingPageOrder  = 1,
   NSUnknownPageOrder    = 2
} NSPrintingPageOrder;

Constants
NSAscendingPageOrder

Ascending (back to front) page order.

Available in Mac OS X v10.0 and later.

Declared in NSPrintOperation.h.

NSDescendingPageOrder

Descending (front to back) page order.

Available in Mac OS X v10.0 and later.

Declared in NSPrintOperation.h.

NSSpecialPageOrder

The spooler does not rearrange pages—they are printed in the order received by the spooler.

Available in Mac OS X v10.0 and later.

Declared in NSPrintOperation.h.

NSUnknownPageOrder

No page order specified.

Available in Mac OS X v10.0 and later.

Declared in NSPrintOperation.h.

Discussion

These constants are used by pageOrder and setPageOrder:.

Availability
Declared In
NSPrintOperation.h

Exception Name

This is the name of an exception that can be raised by NSPrintOperation.

NSString *NSPrintOperationExistsException;

Constants
NSPrintOperationExistsException

The name of an exception raised when there is already a print operation in process.

The methods that raise this exception are the EPSOperation... and printOperation....

Available in Mac OS X v10.0 and later.

Declared in NSPrintOperation.h.

Declared In
NSPrintOperation.h

Next Page > Hide TOC

© 2007 Apple Inc. All Rights Reserved. (Last updated: 2007-03-02)

Did this document help you?
Yes: Tell us what works for you.
It’s good, but: Report typos, inaccuracies, and so forth.
It wasn’t helpful: Tell us what would have helped.