PATH  Documentation > Mac OS X > Application Kit Reference: Objective-C

Table of Contents

NSPrintInfo


Inherits from:
NSObject
Conforms to:
NSCoding
NSCopying
NSObject (NSObject)
Declared in:
AppKit/NSPrintInfo.h




Class Description


An NSPrintInfo object stores information that's used to generate output. A shared NSPrintInfo object is automatically created for an application and is used by default for all printing jobs for that application. You can create any number of additional NSPrintInfo objects; however, only one can be "active" at a time, set using the setSharedPrintInfo: class method. You get the shared NSPrintInfo object using the sharedPrintInfo class method.

An NSPrintInfo object is used by NSPrintOperation objects to control printing (it is passed to a NSPrintOperation object which makes a copy of it to use during an operation). If you create special instances of NSPrintInfo objects for a specific printing task, you must ensure that your NSPrintInfo object is the shared one, or instantiate an NSPrintOperation object specifying your NSPrintInfo object.

Normally you don't set NSPrintInfo attributes directly-this is done by instances of NSPageLayout and NSPrintPanel. The NSView that's being printed may also supercede some NSPrintInfo settings. In particular, an NSView can supply the range of pages in the document and can provide its own pagination mechanism through the knowsPageRange: and rectForPage: methods (see the documentation of these methods in the NSView class for details).

If the NSView doesn't supply pagination information, the NSPrintInfo's vertical and horizontal pagination constants are used to trigger these built-in pagination mechanisms:


Pagination Constant Meaning
NSAutoPagination The image is diced into equal-sized rectangles and placed in one column of pages.
NSFitPagination The image is scaled to produce one column or one row of pages.
NSClipPagination The image is clipped to produce one column or row of pages.

Vertical and horizontal pagination needn't be the same. However, if either dimension is scaled (NSFitPagination), the other dimension is scaled by the same amount to avoid stretching the image. If both dimensions are scaled, the scaling factor that produces the smallest image is used. Note that NSPrintInfo's scaling factor is independent of the scaling that's imposed by pagination and is applied after the document has been paginated.

NSPrintInfo uses points as the unit of measurement for paper size and margin width in the methods described below. See the NSFont specification for a discussion of points.


NSPrinterInfo Attributes


An NSPrinterInfo contains a dictionary that stores its attribute settings. These are the keys that allow you to access the appropriate value contained in the dictionary:


Key Type Description
NSPrintPaperName NSString The paper name.
NSPrintPaperSize NSSize Height and width of paper in points.
NSPrintMustCollate BOOL If YES, collates output.
NSPrintFormName NSString Form name such as "Letter" or "Letter Small".
NSPrintOrientation NSPrintingOrientation NSPortraitOrientation or NSLandscapeOrientation
NSPrintLeftMargin float The left margin in points.
NSPrintRightmargin float The right margin in points.
NSPrintTopMargin float The top margin in points.
NSPrintBottomMargin float The bottom margin in points.
NSPrintHorizontallyCentered BOOL If YES, pages are centered horizontally.
NSPrintVerticallyCentered BOOL If YES, pages are centered vertically.
NSPrintHorizontalPagination NSPrintingPaginationMode NSAutoPagination, NSFitPagination, or NSClipPagination. See setHorizontalPagination: for details.
NSPrintVerticalPagination NSPrintingPaginationMode NSAutoPagination, NSFitPagination, or NSClipPagination. See setVerticalPagination: for details.
NSPrintScalingFactor float Scale factor before pagination.
NSPrintAllPages BOOL If YES, includes all pages in output.
NSPrintReversePageOrder BOOL If YES, prints last page first.
NSPrintFirstPage int The first page in the print job.
NSPrintLastPage int The last page in the print job.
NSPrintCopies int Number of copies to spool.
NSPrintPagesPerSheet int The number of pages of the document that are printed on a single sheet of paper. This number is rounded up to the power of two when used by the system.
NSPrintJobFeatures NSMutableDictionary Features from the NSPrinter object where keys are the feature name and values are the settings. For example, the key NSPrintPaperFeed might have the value *InputSlot/Upper. See the NSPrinter class description.
NSPrintPaperFeed NSString The printer slot. For example, InputSlot/Upper or NSPrintManualFeed.
NSPrintPrinter NSPrinter The printer to use.
NSPrintJobDisposition NSString NSPrintSpoolJob, NSPrintFaxJob, NSPrintPreviewJob, NSPrintSaveJob, or NSPrintCancelJob. See setJobDisposition: for details.
NSPrintSavePath NSString Pathname to save as a file if job disposition is NSPrintSaveJob.
NSPrintFaxReceiverNames NSArray Array of NSStrings containing receiver names for a fax job.
NSPrintFaxReceiverNumbers NSArray Array of NSStrings containing the receiver phone numbers for a fax job.
NSPrintFaxSendTime NSDate When to send the fax.
NSPrintFaxUseCoverSheet BOOL If YES, send cover sheet.
NSPrintFaxCoverSheetName NSString The filename containing the cover sheet.
NSPrintFaxReturnReceipt BOOL If YES, sends confirmation email when fax is sent.
NSPrintFaxHighResolution BOOL If YES, sends fax at high resolution.
NSPrintFaxTrimPageEnds BOOL If YES, trims page ends, otherwise sends complete pages.
NSPrintFaxModem NSPrinter The fax modem to use.




Constants


These constants specify pagination modes. They're used by horizontalPagination, setHorizontalPagination:, verticalPagination, and setVerticalPagination:.


Pagination Constant Meaning
NSAutoPagination The image is diced into equal-sized rectangles and placed in one column of pages.
NSFitPagination The image is scaled to produce one column or one row of pages.
NSClipPagination The image is clipped to produce one column or row of pages.

These constants specify page orientations. They're used by orientation, and setOrientation:.


Mode Meaning
NSPortraitOrientation Description forthcoming.
NSLandscapeOrientation Description forthcoming.



Adopted Protocols


NSCoding
- encodeWithCoder:
- initWithCoder:
NSCopying
- copyWithZone:


Method Types


Initializing an NSPrintInfo
- initWithDictionary:
Managing the shared NSPrintInfo
+ setSharedPrintInfo:
+ sharedPrintInfo
Managing the printing rectangle
+ sizeForPaperName:
- bottomMargin
- leftMargin
- orientation
- paperName
- paperSize
- rightMargin
- setBottomMargin:
- setLeftMargin:
- setOrientation:
- setPaperName:
- setPaperSize:
- setRightMargin:
- setTopMargin:
- topMargin
Pagination
- horizontalPagination
- setHorizontalPagination:
- setVerticalPagination:
- verticalPagination
Positioning the image on the page
- isHorizontallyCentered
- isVerticallyCentered
- setHorizontallyCentered:
- setVerticallyCentered:
Specifying the printer
+ defaultPrinter
+ setDefaultPrinter:
- printer
- setPrinter:
Controlling printing
- jobDisposition
- setJobDisposition:
- setUpPrintOperationDefaultValues
Accessing the dictionary
- dictionary


Class Methods



defaultPrinter

+ (NSPrinter *)defaultPrinter

Returns the user's default printer. Returns nil if the printer cannot be found.

See Also: + setDefaultPrinter:



setDefaultPrinter:

+ (void)setDefaultPrinter:(NSPrinter *)aPrinter

Sets the user's default printer to aPrinter. Unless the receiver's printer was specified using setPrinter:, this default printer is used.

See Also: + defaultPrinter, - printer



setSharedPrintInfo:

+ (void)setSharedPrintInfo:(NSPrintInfo *)printInfo

Sets the shared NSPrintInfo object to printInfo. The shared NSPrintInfo object defines the settings for the NSPageLayout panel and print operations that will be used if no NSPrintInfo object is specified for those operations. printInfo should never be nil.

See Also: + sharedPrintInfo



sharedPrintInfo

+ (NSPrintInfo *)sharedPrintInfo

Returns the shared NSPrintInfo object.

See Also: + setSharedPrintInfo:



sizeForPaperName:

+ (NSSize)sizeForPaperName:(NSString *)name

Returns the size for the specified type of paper in points. name identifies the type of paper, such as "Letter" or "Legal". Paper names are implementation specific.


Instance Methods



bottomMargin

- (float)bottomMargin

Returns the height of the bottom margin in points.

See Also: - setBottomMargin:



dictionary

- (NSMutableDictionary *)dictionary

Returns the receiver's dictionary that stores its attribute settings. The key/value pairs contained in the dictionary are described in "NSPrinterInfo Attributes" . Modifying the returned dictionary will change the receiver's attributes.

horizontalPagination

- (NSPrintingPaginationMode)horizontalPagination

Returns the horizontal pagination mode. It can return one of the pagination modes described in "Constants" .

See Also: - setVerticalPagination:, - verticalPagination



initWithDictionary:

- (id)initWithDictionary:(NSDictionary *)aDictionary

Initializes a newly allocated NSPrintInfo object by assigning it the parameters specified in aDictionary. This is the designated initializer for this class. The possible key/value pairs contained in aDictionary are in "NSPrinterInfo Attributes" . Non-object values should be stored as NSValues in the dictionary.

See Also: - dictionary



isHorizontallyCentered

- (BOOL)isHorizontallyCentered

Returns YES if the image is centered horizontally, NO otherwise.

See Also: - isVerticallyCentered, - setHorizontallyCentered:



isVerticallyCentered

- (BOOL)isVerticallyCentered

Returns YES if the image is centered vertically, NO otherwise.

See Also: - isHorizontallyCentered, - setVerticallyCentered:



jobDisposition

- (NSString *)jobDisposition

Returns the action specified for the job. See setJobDisposition: for a description of return values.

leftMargin

- (float)leftMargin

Returns the width of the left margin in points.

See Also: - setLeftMargin:



orientation

- (NSPrintingOrientation)orientation

Returns the orientation attribute. See setOrientation: for a description of return values.

paperName

- (NSString *)paperName

Returns the paper name such as "Letter" or "Legal". Paper names are implementation specific.

See Also: - setPaperName:



paperSize

- (NSSize)paperSize

Returns the size of the paper in points.

See Also: - setPaperSize:



printer

- (NSPrinter *)printer

Returns the NSPrinter to be used for printing.

See Also: - setPrinter:



rightMargin

- (float)rightMargin

Returns the width of the right margin in points.

See Also: - setRightMargin:



setBottomMargin:

- (void)setBottomMargin:(float)margin

Sets the bottom margin to margin specified in points.

See Also: - bottomMargin



setHorizontalPagination:

- (void)setHorizontalPagination:(NSPrintingPaginationMode)mode

Sets the horizontal pagination to mode. mode can be one of the pagination modes described in "Constants" .

See Also: - horizontalPagination, - setVerticalPagination:, - verticalPagination



setHorizontallyCentered:

- (void)setHorizontallyCentered:(BOOL)flag

If flag is YES the image will be centered horizontally.

See Also: - isHorizontallyCentered, - isVerticallyCentered, - setVerticallyCentered:



setJobDisposition:

- (void)setJobDisposition:(NSString *)disposition

Sets the action specified for the job to disposition. disposition can be one of:
Disposition Meaning
NSPrintSpoolJob Normal print job.
NSPrintFaxJob Fax job.
NSPrintPreviewJob Send to Preview application.
NSPrintSaveJob Save to a file.
NSPrintCancelJob Cancel print job.

See Also: - jobDisposition



setLeftMargin:

- (void)setLeftMargin:(float)margin

Sets the left margin to margin specified in points.

See Also: - leftMargin



setOrientation:

- (void)setOrientation:(NSPrintingOrientation)orientation

Sets the page orientation to orientation where orientation is either NSPortraitOrientation or NSLandscapeOrientation. This method may change either the paper name or size for consistency. To avoid this side effect set the values in the dictionary directly.

See Also: - dictionary, - initWithDictionary:, - orientation



setPaperName:

- (void)setPaperName:(NSString *)name

Sets the paper name to name (e.g. Letter or Legal). Paper names are implementation specific.This method may change either the size or orientation for consistency. To avoid this side effect set the values in the dictionary directly.

See Also: - dictionary, - initWithDictionary:, - paperName



setPaperSize:

- (void)setPaperSize:(NSSize)aSize

Sets the width and height of the paper to aSize specified in points. This method may change either the paper name or orientation for consistency. To avoid this side effect set the values in the dictionary directly.

See Also: - dictionary, - initWithDictionary:, - paperSize



setPrinter:

- (void)setPrinter:(NSPrinter *)aPrinter

Sets the printer used in subsequent printing jobs to aPrinter. This method iterates through the dictionary. If a feature in the dictionary is not supported by this new printer (as determined by a query to the PPD file), that feature is removed from the dictionary

See Also: - printer



setRightMargin:

- (void)setRightMargin:(float)margin

Sets the right margin to margin specified in points.

See Also: - rightMargin



setTopMargin:

- (void)setTopMargin:(float)margin

Sets the top margin to margin specified in points.

See Also: - topMargin



setUpPrintOperationDefaultValues

- (void)setUpPrintOperationDefaultValues

Invoked when the print operation is about to start. Subclasses may override this method to set default values for any attributes that are not set.

setVerticalPagination:

- (void)setVerticalPagination:(NSPrintingPaginationMode)mode

Sets the vertical pagination to mode. mode can be one of the pagination modes described in "Constants" .

See Also: - horizontalPagination, - setHorizontalPagination:, - verticalPagination



setVerticallyCentered:

- (void)setVerticallyCentered:(BOOL)flag

If flag is YES, the image will be vertically centered.

See Also: - isHorizontallyCentered, - isVerticallyCentered, - setHorizontallyCentered:



topMargin

- (float)topMargin

Returns the top margin in points.

See Also: - setTopMargin:



verticalPagination

- (NSPrintingPaginationMode)verticalPagination

Returns the vertical pagination mode. It can return one of the pagination modes described in "Constants" .

See Also: - horizontalPagination, - setHorizontalPagination:




Table of Contents