Advanced Search

Log In | Not a Member?

Contact ADC

Next Page > Hide TOC

NSPrintOperation Class Reference

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

• + EPSOperationWithView:insideRect:toData:
• + EPSOperationWithView:insideRect:toData:printInfo:
• + EPSOperationWithView:insideRect:toPath:printInfo:
• + PDFOperationWithView:insideRect:toData:
• + PDFOperationWithView:insideRect:toData:printInfo:
• + PDFOperationWithView:insideRect:toPath:printInfo:
• + printOperationWithView:
• + printOperationWithView:printInfo:

Setting the Current NSPrintOperation for This Thread

• + currentOperation
• + setCurrentOperation:

Determining the Type of Operation

• – isCopyingOperation

Modifying the NSPrintInfo Object

• – printInfo
• – setPrintInfo:

Getting the NSView Object

• – view

Running a Print Operation

• – runOperation
• – runOperationModalForWindow:delegate:didRunSelector:contextInfo:
• – cleanUpOperation
• – deliverResult

Modifying the User Interface

• – showsPrintPanel
• – setShowsPrintPanel:
• – showsProgressPanel
• – setShowsProgressPanel:
• – jobTitle
• – setJobTitle:
• – printPanel
• – setPrintPanel:

Managing the Drawing Context

• – context
• – createContext
• – destroyContext

Managing Page Information

• – currentPage
• – pageRange
• – pageOrder
• – setPageOrder:

Managing Printing-Related Threads

• – canSpawnSeparateThread
• – setCanSpawnSeparateThread:

Deprecated Methods

• – setShowPanels: Deprecated in Mac OS X v10.4 and later
• – showPanels Deprecated in Mac OS X v10.4 and later
• – accessoryView Deprecated in Mac OS X v10.5
• – jobStyleHint Deprecated in Mac OS X v10.5
• – setAccessoryView: Deprecated in Mac OS X v10.5
• – setJobStyleHint: Deprecated in Mac OS X v10.5

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

See Also

• + setCurrentOperation:

Declared In

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

See Also

• + EPSOperationWithView:insideRect:toData:printInfo:
• + EPSOperationWithView:insideRect:toPath:printInfo:
• – runOperation

Declared In

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

See Also

• + EPSOperationWithView:insideRect:toData:
• + EPSOperationWithView:insideRect:toPath:printInfo:
• – runOperation

Declared In

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

See Also

• + EPSOperationWithView:insideRect:toData:
• + EPSOperationWithView:insideRect:toData:printInfo:
• – runOperation

Declared In

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

See Also

• + PDFOperationWithView:insideRect:toData:printInfo:
• + PDFOperationWithView:insideRect:toPath:printInfo:
• – runOperation

Declared In

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

See Also

• + PDFOperationWithView:insideRect:toData:
• + PDFOperationWithView:insideRect:toPath:printInfo:
• – runOperation

Declared In

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

See Also

• + PDFOperationWithView:insideRect:toData:
• + PDFOperationWithView:insideRect:toData:printInfo:
• – runOperation

Declared In

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

See Also

• + printOperationWithView:printInfo:
• – runOperation

Declared In

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

See Also

• + printOperationWithView:
• – runOperation

Declared In

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

See Also

• + currentOperation

Declared In

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

See Also

• – setCanSpawnSeparateThread:

Declared In

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

See Also

• – runOperation

Declared In

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

See Also

• – createContext
• – destroyContext

Declared In

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

See Also

• – context
• – destroyContext

Declared In

currentPage

Returns the current page number being printed.

- (NSInteger)currentPage

Return Value

The current page being printed.

Availability

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

See Also

• – pageOrder
• – setPageOrder:

Declared In

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

See Also

• – runOperation

Declared In

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

See Also

• – context
• – createContext

Declared In

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

Declared In

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 Mac OS X v10.5 and later.

See Also

• – setJobTitle:
• – printJobTitle (NSView)

Declared In

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

See Also

• – currentPage

Declared In

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 Mac OS X v10.5 and later.

See Also

• – knowsPageRange: (NSView)

Declared In

printInfo

Returns the receiver’s NSPrintInfo object.

- (NSPrintInfo *)printInfo

Return Value

The print settings of the receiver.

Availability

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

See Also

• – setPrintInfo:

Declared In

printPanel

Returns the NSPrintPanel object used when running the operation.

- (NSPrintPanel *)printPanel

Return Value

The print panel object for the operation.

Availability

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

See Also

• – accessoryView
• – setAccessoryView:
• – setPrintPanel:
• – setShowPanels:
• – showPanels

Declared In

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

See Also

• – cleanUpOperation
• – deliverResult

Declared In

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

Declared In

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

See Also

• – canSpawnSeparateThread

Declared In

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 Mac OS X v10.5 and later.

See Also

• – jobTitle
• – printJobTitle (NSView)

Declared In

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

See Also

• – currentPage
• – pageOrder

Declared In

setPrintInfo:

Sets the receiver’s NSPrintInfo object.

- (void)setPrintInfo:(NSPrintInfo *)aPrintInfo

Parameters

aPrintInfo

The new print settings for the receiver.

Availability

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

See Also

• – printInfo

Declared In

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

See Also

• – accessoryView
• – printPanel
• – setAccessoryView:
• – setShowPanels:
• – showPanels

Declared In

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 Mac OS X v10.4 and later.

See Also

• – setShowsProgressPanel:
• – showsPrintPanel

Declared In

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 Mac OS X v10.4 and later.

See Also

• – setShowsPrintPanel:
• – showsProgressPanel

Declared In

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 Mac OS X v10.4 and later.

See Also

• – setShowsPrintPanel:

Declared In

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 Mac OS X v10.4 and later.

See Also

• – setShowsProgressPanel:

Declared In

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

Declared In

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

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

Declared In

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

Next Page > Hide TOC

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.

	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. | Terms of use | Privacy Notice