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 |
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
Determining the Type of Operation
Modifying the NSPrintInfo Object
Getting the NSView Object
Printing Quality
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
Managing Page Information
Managing Printing-Related Threads
Deprecated Methods
-
– accessoryViewDeprecated in OS X v10.5 -
– jobStyleHintDeprecated in OS X v10.5 -
– setAccessoryView:Deprecated in OS X v10.5 -
– setJobStyleHint:Deprecated in OS X v10.5 -
– setShowPanels:Deprecated in OS X v10.4 and later -
– showPanelsDeprecated in OS X v10.4 and later
Class Methods
currentOperation
Returns the current print operation for this thread.
Return Value
The print operation object, or nil if there is no current operation.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hEPSOperationWithView:insideRect:toData:
Creates and returns a new NSPrintOperation object ready to control the copying of EPS graphics from the specified view.
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
NSMutableDataobject. 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.
See Also
Declared In
NSPrintOperation.hEPSOperationWithView: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.
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
NSMutableDataobject. 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.
See Also
Declared In
NSPrintOperation.hEPSOperationWithView: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.
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.
See Also
Declared In
NSPrintOperation.hPDFOperationWithView:insideRect:toData:
Creates and returns a new NSPrintOperation object ready to control the copying of PDF graphics from the specified view.
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
NSMutableDataobject. 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.
See Also
Declared In
NSPrintOperation.hPDFOperationWithView: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.
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
NSMutableDataobject. 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.
See Also
Declared In
NSPrintOperation.hPDFOperationWithView: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.
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.
See Also
Declared In
NSPrintOperation.hprintOperationWithView:
Creates and returns an NSPrintOperation object ready to control the printing of the specified view.
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.hprintOperationWithView:printInfo:
Creates and returns an NSPrintOperation object ready to control the printing of the specified view using custom print settings.
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.
See Also
Declared In
NSPrintOperation.hsetCurrentOperation:
Sets the current print operation for this thread.
Parameters
- operation
The print operation to make current. You may specify
nilto clear the current print operation.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hInstance Methods
canSpawnSeparateThread
Returns a Boolean value indicating whether the receiver is allowed to spawn a separate printing thread.
Return Value
YES if the receiver is allowed to spawn a separate thread; otherwise, NO.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hcleanUpOperation
Called at the end of a print operation to remove the receiver as the current operation.
Discussion
You typically do not invoke this method directly.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hcontext
Returns the graphics context object used for generating output.
Return Value
The graphics context object used for drawing during the operation.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hcreateContext
Creates the graphics context object used for drawing during the operation.
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.
See Also
Declared In
NSPrintOperation.hcurrentPage
Returns the current page number being printed.
Return Value
The current page being printed.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hdeliverResult
Delivers the results of the print operation to the intended destination.
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.
See Also
Declared In
NSPrintOperation.hdestroyContext
Destroys the receiver’s graphics context.
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.
See Also
Declared In
NSPrintOperation.hisCopyingOperation
Returns a Boolean value indicating whether the receiver is an EPS or PDF copy operation.
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.hjobTitle
Returns the title of the print job.
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.
See Also
-
– setJobTitle: -
– printJobTitle(NSView)
Declared In
NSPrintOperation.hpageOrder
Returns the print order for the pages.
Return Value
The print order. For a list of possible values, see “Constants.”
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hpageRange
Returns the range of pages associated with the print operation.
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
-
– knowsPageRange:(NSView)
Declared In
NSPrintOperation.hpreferredRenderingQuality
Returns the printing quality.
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.hprintInfo
Returns the receiver’s NSPrintInfo object.
Return Value
The print settings of the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hprintPanel
Returns the NSPrintPanel object used when running the operation.
Return Value
The print panel object for the operation.
Availability
- Available in OS X v10.0 and later.
Declared In
NSPrintOperation.hrunOperation
Runs the print operation on the current thread.
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.
See Also
Declared In
NSPrintOperation.hrunOperationModalForWindow:delegate:didRunSelector:contextInfo:
Runs the print operation, calling your custom delegate method upon completion.
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.hsetCanSpawnSeparateThread:
Sets whether the receiver is allowed to spawn a separate printing thread.
Parameters
- canSpawnSeparateThread
YESif 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.
See Also
Declared In
NSPrintOperation.hsetJobTitle:
Assigns a custom title to the print job.
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.
See Also
-
– jobTitle -
– printJobTitle(NSView)
Declared In
NSPrintOperation.hsetPageOrder:
Sets the print order for the pages of the operation.
Parameters
- order
The print order. For a list of possible values, see “Constants.”
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hsetPrintInfo:
Sets the receiver’s NSPrintInfo object.
Parameters
- aPrintInfo
The new print settings for the receiver.
Availability
- Available in OS X v10.0 and later.
See Also
Declared In
NSPrintOperation.hsetPrintPanel:
Sets the NSPrintPanel object to be used during the operation.
Parameters
- panel
The print panel object to use for the operation.
Availability
- Available in OS X v10.0 and later.
Declared In
NSPrintOperation.hsetShowsPrintPanel:
Sets whether the receiver displays a print panel for this operation.
Parameters
- flag
YESif 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.
Declared In
NSPrintOperation.hsetShowsProgressPanel:
Sets whether the receiver displays a progress panel for this operation.
Parameters
- flag
YESif 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.
Declared In
NSPrintOperation.hshowsPrintPanel
Returns a Boolean value indicating whether a print panel is displayed during the operation,
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.
See Also
Declared In
NSPrintOperation.hshowsProgressPanel
Returns a Boolean value indicating whether a progress panel is displayed during the operation.
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.
See Also
Declared In
NSPrintOperation.hview
Returns the view object that generates the actual data for the print operation.
Return Value
The view object that generates the data.
Availability
- Available in OS X v10.0 and later.
Declared In
NSPrintOperation.hConstants
NSPrintingPageOrder
These constants specify the page order.
typedef enum _NSPrintingPageOrder {
NSDescendingPageOrder = (-1),
NSSpecialPageOrder = 0,
NSAscendingPageOrder = 1,
NSUnknownPageOrder = 2
} NSPrintingPageOrder;
Constants
NSAscendingPageOrderAscending (back to front) page order.
Available in OS X v10.0 and later.
Declared in
NSPrintOperation.h.NSDescendingPageOrderDescending (front to back) page order.
Available in OS X v10.0 and later.
Declared in
NSPrintOperation.h.NSSpecialPageOrderThe 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.NSUnknownPageOrderNo 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.hException Name
This is the name of an exception that can be raised by NSPrintOperation.
NSString *NSPrintOperationExistsException;
Constants
NSPrintOperationExistsExceptionThe name of an exception raised when there is already a print operation in process.
The methods that raise this exception are the
EPSOperation...andprintOperation....Available in OS X v10.0 and later.
Declared in
NSPrintOperation.h.
Declared In
NSPrintOperation.hNSPrintRenderingQuality
These constants specify the print quality in use.
enum {
NSPrintRenderingQualityBest,
NSPrintRenderingQualityResponsive
};
typedef NSInteger NSPrintRenderingQuality;
Constants
NSPrintRenderingQualityBestRenders the printing at the best possible quality, regardless of speed.
Available in OS X v10.7 and later.
Declared in
NSPrintOperation.h.NSPrintRenderingQualityResponsiveSacrifices 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.
© 2011 Apple Inc. All Rights Reserved. (Last updated: 2011-07-07)