NSPrintOperation Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/AppKit.framework
Availability
Available in 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:.

Tasks

Creating an NSPrintOperation

Setting the Current NSPrintOperation for This Thread

Determining the Type of Operation

Modifying the NSPrintInfo Object

Getting the NSView Object

Printing Quality

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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Declared In
NSPrintOperation.h

currentPage

Returns the current page number being printed.

- (NSInteger)currentPage
Return Value

The current page being printed.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
See Also
Declared In
NSPrintOperation.h

preferredRenderingQuality

Returns the printing quality.

- (NSPrintRenderingQuality)preferredRenderingQuality
Return Value

The preferred printing quality. See “NSPrintRenderingQuality” for the possible values.

Discussion

If the print sheet is unresponsive or sluggish due to the time is takes to fully render a page, you can check this method in drawRect: and other printing methods such as beginDocument and knowsPageRage: to determine if the print operation prefers speed over fidelity. Most applications render each page fast enough and do not need to call this method. Only use this method after establishing that best quality rendering does indeed make the user interface unresponsive.

The following is an example use of this method:

- (void)drawRect:(NSRect)rect {
    NSGraphicsContext *currentContext = [NSGraphicsContext currentContext];
    if (![currentContext isDrawingToScreen]) {
        NSPrintOperation *printOperation = [NSPrintOperation currentOperation]
        if ([printOperation preferredRenderingQuality] == NSPrintRenderingQualityResponsive) {
            // Render with the best possible quality such that the user interface remains responsive
        } else {
            // Printing, do a full render
        }
    }
}
Availability
  • Available in OS X v10.7 and later.
Declared In
NSPrintOperation.h

printInfo

Returns the receiver’s NSPrintInfo object.

- (NSPrintInfo *)printInfo
Return Value

The print settings of the receiver.

Availability
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
Related Sample Code
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.5 and later.
Related Sample Code
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.0 and later.
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
  • Available in OS X v10.4 and later.
Related Sample Code
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
  • Available in OS X v10.4 and later.
Related Sample Code
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
  • Available in OS X v10.4 and later.
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
  • Available in OS X v10.4 and later.
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
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.

Declared in NSPrintOperation.h.

NSDescendingPageOrder

Descending (front to back) page order.

Available in 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 OS X v10.0 and later.

Declared in NSPrintOperation.h.

NSUnknownPageOrder

No page order specified.

Available in OS X v10.0 and later.

Declared in NSPrintOperation.h.

Discussion

These constants are used by pageOrder and setPageOrder:.

Availability
  • Available in OS X v10.0 and later.
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 OS X v10.0 and later.

Declared in NSPrintOperation.h.

Declared In
NSPrintOperation.h

NSPrintRenderingQuality

These constants specify the print quality in use.

enum {
   NSPrintRenderingQualityBest,
   NSPrintRenderingQualityResponsive
};
typedef NSInteger NSPrintRenderingQuality;
Constants
NSPrintRenderingQualityBest

Renders the printing at the best possible quality, regardless of speed.

Available in OS X v10.7 and later.

Declared in NSPrintOperation.h.

NSPrintRenderingQualityResponsive

Sacrifices the least possible amount of rendering quality for speed to maintain a responsive user interface. This option should be used only after establishing that best quality rendering does indeed make the user interface unresponsive.

Available in OS X v10.7 and later.

Declared in NSPrintOperation.h.