Copyright ã1994 by NeXT Computer, Inc.  All Rights Reserved.

NSPrintOperation 

Inherits From:	NSObject

Conforms To:	NSObject (NSObject)

Declared In:	AppKit/NSPrintOperation.h

Class Description

NSPrintOperation controls operations that generate Encapsulated PostScript (EPS) code or PostScript print jobs. Generally, EPS code is used to transfer images between applications, which happens when the user copies and pastes graphics, uses a Service, or uses ObjectLinks. PostScript print jobs are generated when the user prints and faxes documents. An NSPrintOperation does not generate PostScript code itself; it just controls the overall process, relying on an NSView object to generate the actual code.

NSPrintOperation relies mainly on two other objects: an NSPrintInfo object, which specifies how the code should be generated, and an NSView object, which performs the actual code generation. You specify these two objects in the method you use to create the NSPrintOperation. If no NSPrintInfo is specified, NSPrintOperation uses the shared NSPrintInfo, which contains default values. The shared NSPrintInfo works well for applications that are not document-based. Document-based applications should create an NSPrintInfo for each document that might be printed or copied and use that object instead. 

You should create an NSPrintOperation in any method that is invoked when a user executes a Print command or a Copy command. That method also must send NSPrintOperation a runOperation message to start the operation. A print: method for a document-based application might look like this:

- (void)print:sender {
	[[NSPrintOperation printOperationWithView:[self myView] printInfo:[document 
		docPrintInfo]] runOperation];
}

This method creates an NSPrintOperation for a print job that uses the document's NSPrintInfo. Because this is a print job, a Print panel (NSPrintPanel object) is displayed to allow the user to select printing options. The NSPrintOperation copies the NSPrintInfo, updates this copy with information from the Print panel, and uses the specified NSView to perform the operation. 

The information stored in an NSPrintInfo that's retained between operations is information that's likely to remain constant for a document, such as its page size. All information that's likely to change between operations is set to a default value in the NSPrintInfo before the operation begins. In this way, even though NSPrintOperation updates the NSPrintInfo with information from the Print panel for print jobs, that information is reset back to the default values for each print job. Because NSPrintOperation keeps a copy of the NSPrintInfo it uses, you could duplicate a specific print job by storing that copy and reusing it.

Creating and Initializing an NSPrintOperation Object

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView	
insideRect:(NSRect)rect	Returns a new NSPrintOperation that controls the
toData:(NSMutableData *)data		copying of EPS graphics from the area specified by rect in aView, using the parameters in the default NSPrintInfo. The code is written to data. Raises NSPrintOperationExistsException if there is already a print operation in progress.

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView	
insideRect:(NSRect)rect	Returns a new NSPrintOperation that controls the
toData:(NSMutableData *)data		copying of EPS graphics from the area specified by rect
printInfo:(NSPrintInfo *)aPrintInfo		in aView, using the parameters in aPrintInfo. The code is written to data. Raises NSPrintOperationExistsException if there is already a print operation in progress.

+ (NSPrintOperation *)EPSOperationWithView:(NSView *)aView	
insideRect:(NSRect)rect	Returns a new NSPrintOperation that controls the
toPath:(NSString *)path		copying of EPS graphics from the area specified by rect
printInfo:(NSPrintInfo *)aPrintInfo		in aView, using the parameters in aPrintInfo. The code is written to path. Raises NSPrintOperationExistsException if there is already a print operation in progress.

+ (NSPrintOperation *)printOperationWithView:(NSView *)aView
	Returns a new NSPrintOperation that controls the printing of aView, using the parameters in the shared NSPrintInfo object. Raises NSPrintOperationExistsException if there is already a print operation in progress.

+ (NSPrintOperation *)printOperationWithView:(NSView *)aView	
printInfo:(NSPrintInfo *)aPrintInfo	Returns a new NSPrintOperation that controls the printing of aView, using the parameters in aPrintInfo. Raises NSPrintOperationExistsException if there is already a print operation in progress.

- (id)initEPSOperationWithView:(NSView *)aView	Initializes a newly allocated NSPrintOperation to 
insideRect:(NSRect)rect		control the copying of EPS graphics from the area 
toData:(NSMutableData *)data		specified by rect in aView, using the parameters in 
printInfo:(NSPrintInfo *)aPrintInfo		aPrintInfo. The code is written to data.

- (id)initWithView:(NSView *)aView	Initializes a newly allocated NSPrintOperation to
printInfo:(NSPrintInfo *)aPrintInfo		control the printing of aView, using the parameters in aPrintInfo.

Setting the Print Operation

+ (NSPrintOperation *)currentOperation	Returns the NSPrintOperation that represents the current operation or nil if there is no such operation.

+ (void)setCurrentOperation:(NSPrintOperation *)operation
	Sets the NSPrintOperation that represents the current operation.

Determining the Type of Operation

- (BOOL)isEPSOperation	Returns YES if the receiver controls an EPS operation and NO if the receiver controls a printing operation.

Controlling the User Interface

- (NSPrintPanel *)printPanel	Returns the NSPrintPanel object that's used when the operation is run.

- (BOOL)showPanels	Returns whether the Print panel will appear when the operation is run.

- (void)setPrintPanel:(NSPrintPanel *)panel	Sets the NSPrintPanel object that's used when the operation is run.

- (void)setShowPanels:(BOOL)flag	Sets whether the Print panel appears when the operation is run.

Managing the DPS Context

- (NSDPSContext *)createContext	Used by the NSPrintOperation object to create the DPS context for output generation, using the current NSPrintInfo settings.

- (NSDPSContext *)context	Returns the DPS context used for the receiver's operation.

- (void)destroyContext	Used by the NSPrintOperation object to destroy the DPS context at the end of the operation.

Page Information

- (int)currentPage	Returns the page number of the page being printed.

- (NSPrintingPageOrder)pageOrder	Returns the order in which pages will be printed.

- (void)setPageOrder:(NSPrintingPageOrder)order	Sets the order in which pages will be printed.

Running a Print Operation

- (void)cleanUpOperation	Invoked at end of an operation's run to set the current operation to nil.

- (BOOL)deliverResult	Delivers the results generated by runOperation to the intended destination: the print spooler, preview application, etc. Returns YES upon successful delivery and NO otherwise.

- (BOOL)runOperation	Causes the operation (copying EPS graphics or printing) to take place. Returns YES upon successful completion and NO otherwise.

Getting the NSPrintInfo Object

- (NSPrintInfo *)printInfo	Returns the receiver's NSPrintInfo object.

- (void)setPrintInfo:(NSPrintInfo *)aPrintInfo	Sets the receiver's NSPrintInfo object to aPrintInfo.

Getting the NSView Object

- (NSView *)view	Returns the NSView object that performs the operation controlled by the receiving object.