Inherits from | |
Conforms to | |
Framework | /System/Library/Frameworks/AppKit.framework |
Availability | Available in Mac OS X v10.0 and later. |
Companion guide | |
Declared in | NSPrintInfo.h |
Related sample code |
An NSPrintInfo
object stores information that’s used to generate printed output. A shared NSPrintInfo
object is automatically created for an application and is used by default for all printing jobs for that application.
The printing information in an NSPrintInfo
object is stored in a dictionary. To access the standard attributes in the dictionary directly, this class defines a set of keys and provides the dictionary
method. You can also initialize an instance of this class using the initWithDictionary:
method.
You can use this dictionary to store custom information associated with a print job. Any non-object values should be stored as NSNumber
or NSValue
objects in the dictionary. See NSNumber Class Reference for a list of types which should be stored as numbers. For other non-object values, use the NSValue
class.
Beginning in Mac OS X v10.5, to store custom information that belongs in printing presets you should use the dictionary returned by the printSettings
method.
– bottomMargin
– imageablePageBounds
– leftMargin
– orientation
– paperName
– localizedPaperName
– paperSize
– rightMargin
– setBottomMargin:
– setLeftMargin:
– setOrientation:
– setPaperName:
– setPaperSize:
– setRightMargin:
– setTopMargin:
– topMargin
– printSettings
– PMPrintSession
– PMPageFormat
– PMPrintSettings
– updateFromPMPageFormat
– updateFromPMPrintSettings
+ defaultPrinter
+ setDefaultPrinter:
Deprecated in Mac OS X v10.2
+ sizeForPaperName:
Deprecated in Mac OS X v10.2
Deprecated.
+ (NSPrinter *)defaultPrinter
NSPrintInfo.h
Sets the shared NSPrintInfo
object to the specified object.
+ (void)setSharedPrintInfo:(NSPrintInfo *)printInfo
The new shared printer information. This value must not be nil
.
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.
NSPrintInfo.h
Returns the shared NSPrintInfo
object.
+ (NSPrintInfo *)sharedPrintInfo
The shared printer information.
NSPrintInfo.h
Returns the height of the bottom margin.
- (CGFloat)bottomMargin
The bottom margin, measured in points in the user coordinate space.
NSPrintInfo.h
Returns the receiver’s dictionary.
- (NSMutableDictionary *)dictionary
The key-value pairs contained in the dictionary are described in “Constants.” Modifying the returned dictionary changes the receiver’s attributes.
NSPrintInfo.h
Returns the horizontal pagination mode.
- (NSPrintingPaginationMode)horizontalPagination
One of the pagination modes described in “Constants.”
NSPrintInfo.h
Returns the imageable area of a sheet of paper specified by the receiver.
- (NSRect)imageablePageBounds
The imageable area, measured in points in the user coordinate space.
This method takes into account the current printer, paper size, and orientation settings, but not scaling factors. “Imageable area” is the maximum area that can possibly be marked on by the printer hardware, not the area defined by the current margin settings.
The origin (0, 0) of the returned rectangle is in the lower-left corner of the oriented sheet. The imageable bounds may extend past the edges of the sheet when, for example, a printer driver specifies it so that borderless printing can be done reliably.
NSPrintInfo.h
Returns an NSPrintInfo
object initialized with the parameters in the specified dictionary.
- (id)initWithDictionary:(NSDictionary *)aDictionary
The possible key-value pairs contained in aDictionary are described in “Constants.”
An initialized NSPrintInfo
object, or nil if the object could not be created.
This method is the designated initializer for this class. Non-object values should be stored in NSValue
objects (or an appropriate subclass like NSNumber
) in the dictionary. See NSNumber
for a list of types which should be stored using the NSNumber
class; otherwise use NSValue
.
NSPrintInfo.h
Returns a Boolean value indicating whether the image is centered horizontally.
- (BOOL)isHorizontallyCentered
YES
if the image is centered horizontally; otherwise, NO
.
NSPrintInfo.h
Returns a Boolean value indicating whether the image is centered vertically.
- (BOOL)isVerticallyCentered
YES
if the image is centered vertically; otherwise, NO
.
NSPrintInfo.h
Returns the action specified for the job.
- (NSString *)jobDisposition
One of the following value:
NSPrintSpoolJob
is a normal print job.
NSPrintPreviewJob
sends the print job to the Preview application.
NSPrintSaveJob
saves the print job to a file.
NSPrintCancelJob
aborts the print job.
NSPrintFaxJob
is deprecated.
NSPrintInfo.h
Returns the width of the left margin.
- (CGFloat)leftMargin
The left margin, measured in points in the user coordinate space.
NSPrintInfo.h
Returns the human-readable name of the currently selected paper size, suitable for presentation in user interfaces.
- (NSString *)localizedPaperName
The name of the paper size.
This is typically different from the name returned by paperName
, which is almost never suitable for presentation to the user.
NSPrintInfo.h
Returns the orientation attribute.
- (NSPrintingOrientation)orientation
One of the following values: NSPortraitOrientation
or NSLandscapeOrientation
.
NSPrintInfo.h
Returns the name of the currently selected paper size.
- (NSString *)paperName
The string contains a value such as Letter or Legal. Paper names are implementation specific.
NSPrintInfo.h
Returns the size of the paper.
- (NSSize)paperSize
The size of the paper, measured in points in the user coordinate space.
NSPrintInfo.h
Returns a Core Printing object configured with the receiver’s page format information.
- (void *)PMPageFormat
A pointer to a PMPageFormat
object, an opaque data type that stores information such as the paper size, orientation, and scale of pages in a printing session. You should not call PMRelease
to release the returned object, except to balance calls to PMRetain
that your code also issued.
The information in the returned PMPageFormat
object is consistent with the receiver’s page format information at the time this method is called. Subsequent changes to the receiving NSPrintInfo
object do not result in changes to the information in the PMPageFormat
object.
If you make changes to the data in the PMPageFormat
object, you should invoke the updateFromPMPageFormat
method to synchronize those changes with the NSPrintInfo
object that created the object.
NSPrintInfo.h
Returns a Core Printing object configured with the receiver’s session information.
- (void *)PMPrintSession
A pointer to a PMPrintSession
object, an opaque type that stores information about a print job. You should not call PMRelease
to release the returned object, except to balance calls to PMRetain
that your code also issued.
The information in the returned PMPrintSession
object is consistent with the receiver’s session information at the time this method is called. Subsequent changes to the receiving NSPrintInfo
object do not result in changes to the information in the PMPrintSession
object.
NSPrintInfo.h
Returns a Core Printing object configured with the receiver’s print settings information
- (void *)PMPrintSettings
A pointer to a PMPrintSettings
object, an opaque data type used to store information such as the number of copies and the range of pages in a printing session. You should not call PMRelease
to release the returned object, except to balance calls to PMRetain
that your code also issued.
The information in the returned PMPrintSettings
object is consistent with the receiver’s print settings at the time this method is called. Subsequent changes to the receiving NSPrintInfo
object do not result in changes to the information in the PMPrintSettings
data type.
If you make changes to the data in the PMPrintSettings
object, you should invoke the updateFromPMPrintSettings
method to synchronize those changes with the NSPrintInfo
object that created the object.
NSPrintInfo.h
Returns the NSPrinter
object to be used for printing.
- (NSPrinter *)printer
The printer object.
NSPrintInfo.h
Returns a mutable dictionary containing the print settings from Core Printing.
- (NSMutableDictionary *)printSettings
A mutable dictionary containing the printing system’s current settings.
You can use this method to get and set values from the system print settings. The keys in the returned dictionary represent the values returned by the Core Printing function PMPrintSettingsGetValue
. They correspond to the settings currently in the print panel and include everything from custom values set by your accessory panels to values provided by the printer driver’s print dialog extension.
Adding keys to the dictionary is equivalent to calling the Core Printing function PMPrintSettingsSetValue
. Your new keys are added to the current print settings and are saved with any user preset files generated by the Mac OS X printing system. Because the print settings are stored in a property list, any values you add to the dictionary must correspond to scalar types such as strings, numbers, dates, booleans, and data objects or collection types such as dictionaries and arrays.
Other parts of the printing system use key strings like com.apple.print.PrintSettings.PMColorSyncProfileID
to identify print settings. Cocoa replaces the periods in such strings with underscores. Thus, the preceding key string would be com_apple_print_PrintSettings_PMColorSyncProfileID
instead. If you use reverse-DNS style key strings for your custom attributes, you should follow the same convention of using underscore characters instead of periods.
NSPrintInfo.h
Returns the width of the right margin.
- (CGFloat)rightMargin
The right margin, measured in points in the user coordinate space.
NSPrintInfo.h
Sets the bottom margin to the specified size.
- (void)setBottomMargin:(CGFloat)margin
The new size for the right margin, measured in points in the user coordinate space.
NSPrintInfo.h
Sets whether the image is centered horizontally.
- (void)setHorizontallyCentered:(BOOL)flag
YES
if you want the image to be centered horizontally; otherwise, NO
.
NSPrintInfo.h
Sets the horizontal pagination to the specified mode.
- (void)setHorizontalPagination:(NSPrintingPaginationMode)mode
One of the pagination modes described in “Constants.”
NSPrintInfo.h
Sets the action specified for the job
- (void)setJobDisposition:(NSString *)disposition
One of the following value:
NSPrintSpoolJob
is a normal print job.
NSPrintPreviewJob
sends the print job to the Preview application.
NSPrintSaveJob
saves the print job to a file.
NSPrintCancelJob
aborts the print job.
NSPrintFaxJob
is deprecated.
NSPrintInfo.h
Sets the left margin to the specified size.
- (void)setLeftMargin:(CGFloat)margin
The new size for the left margin, measured in points in the user coordinate space.
NSPrintInfo.h
Sets the page orientation to the specified value.
- (void)setOrientation:(NSPrintingOrientation)orientation
This parameter can be one of the following values: NSPortraitOrientation
or NSLandscapeOrientation
.
For consistency, this method may change either the paper name or the paper size.
NSPrintInfo.h
Sets the paper name to the specified value.
- (void)setPaperName:(NSString *)name
The name for the paper size. The string contains a value such as Letter or Legal. Paper names are implementation specific.
For consistency, this method may change either the paper size or the page orientation.
NSPrintInfo.h
Sets the width and height of the paper to the specified size.
- (void)setPaperSize:(NSSize)aSize
The new size of the paper, measured in points in the user coordinate space.
For consistency, this method may change either the paper name or the page orientation.
NSPrintInfo.h
Sets the printer object used for subsequent printing jobs.
- (void)setPrinter:(NSPrinter *)printer
The printer object.
This method iterates through the receiver's dictionary. If a feature in the dictionary is not supported by the new printer (as determined by a query to the PPD file), that feature is removed from the dictionary.
NSPrintInfo.h
Sets the right margin to the specified size.
- (void)setRightMargin:(CGFloat)margin
The new size for the right margin, measured in points in the user coordinate space.
NSPrintInfo.h
Sets the top margin to the specified size.
- (void)setTopMargin:(CGFloat)margin
The new size for the top margin, measured in points in the user coordinate space.
NSPrintInfo.h
Validates the attributes encapsulated by the receiver.
- (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.
NSPrintInfo.h
Sets whether the image is centered vertically.
- (void)setVerticallyCentered:(BOOL)flag
YES
if you want the image to be centered vertically; otherwise, NO
.
NSPrintInfo.h
Sets the vertical pagination to the specified mode.
- (void)setVerticalPagination:(NSPrintingPaginationMode)mode
One of the pagination modes described in “Constants.”
NSPrintInfo.h
Returns the top margin.
- (CGFloat)topMargin
The top margin, measured in points in the user coordinate space.
NSPrintInfo.h
Synchronizes the receiver’s page format information with information from its associated PMPageFormat
object.
- (void)updateFromPMPageFormat
You should use this method after making changes to the PMPageFormat
object obtained from the receiver. Each NSPrintInfo
object keeps track of the object returned from its PMPageFormat
method and obtains any updated information from the object directly. You only need to synchronize the objects once when you have made all of the desired changes.
NSPrintInfo.h
Synchronizes the receiver’s print settings information with information from its associated PMPrintSettings
object.
- (void)updateFromPMPrintSettings
You should use this method after making changes to the PMPrintSettings
object obtained from the receiver. Each NSPrintInfo
object keeps track of the object returned from its PMPrintSettings
method and obtains any updated information from the object directly. You only need to synchronize the objects once when you have made all of the desired changes.
NSPrintInfo.h
Returns the vertical pagination mode.
- (NSPrintingPaginationMode)verticalPagination
One of the pagination modes described in “Constants.”
NSPrintInfo.h
These constants specify dictionary keys to access print job attributes.
NSString *NSPrintPrinter; NSString *NSPrintCopies; NSString *NSPrintAllPages; NSString *NSPrintFirstPage; NSString *NSPrintLastPage; NSString *NSPrintMustCollate; NSString *NSPrintReversePageOrder; NSString *NSPrintJobDisposition; NSString *NSPrintSavePath; NSString *NSPrintPagesAcross; NSString *NSPrintPagesDown; NSString *NSPrintTime; NSString *NSPrintDetailedErrorReporting; NSString *NSPrintFaxNumber; NSString *NSPrintPrinterName; NSString *NSPrintHeaderAndFooter;
NSPrintPrinter
An NSPrinter
object—the printer to use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintCopies
An NSNumber
object containing an integer—the number of copies to spool.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintAllPages
An NSNumber
object containing a Boolean value—if YES
, includes all pages in output.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFirstPage
An NSNumber
object containing an integer value that specifies the first page in the print job.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintLastPage
An NSNumber
object containing an integer value that specifies the last page in the print job.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintMustCollate
An NSNumber
object containing a Boolean value—if YES
, collates output.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintReversePageOrder
An NSNumber
object containing a Boolean value—if YES
, prints first page last.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintJobDisposition
An NSString
object that specifies the job disposition.
NSPrintSpoolJob
, NSPrintPreviewJob
, NSPrintSaveJob
, or NSPrintCancelJob
. See setJobDisposition:
for details.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintSavePath
An NSString
object that specifies the pathname to save as a file if job disposition is NSPrintSaveJob
.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintPagesAcross
An NSNumber
object that specifies the number of logical pages to be tiled horizontally on a physical sheet of paper.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintPagesDown
An NSNumber
object that specifies the number of logical pages to be tiled vertically on a physical sheet of paper.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintTime
An NSDate
object that specifies the time at which printing should begin.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintDetailedErrorReporting
An NSNumber
object containing a Boolean value—if YES
, produce detailed reports when an error occurs.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxNumber
An NSString
object that specifies a fax number.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintPrinterName
An NSString
object that specifies the name of a printer.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintHeaderAndFooter
An NSNumber
object containing a Boolean value—if YES
, a standard header and footer are added outside the margins of each page.
Available in Mac OS X v10.4 and later.
Declared in NSPrintInfo.h
.
NSPrintInfo.h
These constants specify the different ways in which an image is divided into pages. They’re used by horizontalPagination
, setHorizontalPagination:
, verticalPagination
, and setVerticalPagination:
.
typedef enum { NSAutoPagination = 0, NSFitPagination = 1, NSClipPagination = 2 } NSPrintingPaginationMode;
NSAutoPagination
The image is divided into equal-sized rectangles and placed in one column of pages.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSFitPagination
The image is scaled to produce one column or one row of pages.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSClipPagination
The image is clipped to produce one column or row of pages.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintInfo.h
These constants specify page orientations.
typedef enum { NSPortraitOrientation = 0, NSLandscapeOrientation = 1 } NSPrintingOrientation;
NSPortraitOrientation
Orientation is portrait (page is taller than it is wide).
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSLandscapeOrientation
Orientation is landscape (page is wider than it is tall).
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
These constants are used by the methods orientation
and setOrientation:
.
NSPrintInfo.h
These constants specify valid values for the print job attribute NSPrintJobDisposition
.
NSString *NSPrintSpoolJob; NSString *NSPrintPreviewJob; NSString *NSPrintSaveJob; NSString *NSPrintCancelJob;
NSPrintSpoolJob
Normal print job.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintPreviewJob
Send to Preview application.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintSaveJob
Save to a file.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintCancelJob
Cancel print job.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
These constants are used by the jobDisposition
and setJobDisposition:
methods.
NSPrintInfo.h
These constants specify dictionary keys to access page format attributes.
NSString *NSPrintPaperName; NSString *NSPrintPaperSize; NSString *NSPrintOrientation; NSString *NSPrintScalingFactor;
NSPrintPaperName
An NSString
object containing the paper name.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintPaperSize
An NSSize
value specifying the height and width of paper in points.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintOrientation
An NSNumber
object containing an NSPrintingOrientation
.
NSPortraitOrientation
or NSLandscapeOrientation
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintScalingFactor
Scale factor percentage before pagination.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintInfo.h
These constants specify dictionary keys to access pagination attributes.
NSString *NSPrintBottomMargin; NSString *NSPrintHorizontalPagination; NSString *NSPrintHorizontallyCentered; NSString *NSPrintLeftMargin; NSString *NSPrintRightMargin; NSString *NSPrintTopMargin; NSString *NSPrintVerticalPagination; NSString *NSPrintVerticallyCentered;
NSPrintLeftMargin
NSNumber
, containing a floating-point value that specifies the left margin, in points.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintRightMargin
NSNumber
, containing a floating-point value that specifies the right margin, in points.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintTopMargin
NSNumber
, containing a floating-point value that specifies the top margin, in points.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintBottomMargin
NSNumber
, containing a floating-point value that specifies the bottom margin, in points.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintHorizontallyCentered
NSNumber
, containing a Boolean value that is YES
if pages are centered horizontally.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintVerticallyCentered
NSNumber
, containing a Boolean value that is YES
if pages are centered vertically.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintHorizontalPagination
NSNumber
, containing a NSPrintingPaginationMode
value.
NSAutoPagination
, NSFitPagination
, or NSClipPagination
. See setHorizontalPagination:
for details.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintVerticalPagination
NSNumber
, containing a NSPrintingPaginationMode
value.
NSAutoPagination
, NSFitPagination
, or NSClipPagination
. See setVerticalPagination:
for details.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintInfo.h
These keys refer to older printing properties that are no longer used. (Deprecated. Use the keys described in “Print job attributes” instead.)
NSString *NSPrintFormName; NSString *NSPrintJobFeatures; NSString *NSPrintManualFeed; NSString *NSPrintPagesPerSheet; NSString *NSPrintPaperFeed; NSString *NSPrintFaxReceiverNames; NSString *NSPrintFaxReceiverNumbers; NSString *NSPrintFaxSendTime; NSString *NSPrintFaxUseCoverSheet; NSString *NSPrintFaxCoverSheetName; NSString *NSPrintFaxReturnReceipt; NSString *NSPrintFaxHighResolution; NSString *NSPrintFaxTrimPageEnds; NSString *NSPrintFaxModem; NSString *NSPrintFaxJob;
NSPrintFormName
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintJobFeatures
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintManualFeed
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintPagesPerSheet
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintPaperFeed
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxReceiverNames
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxReceiverNumbers
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxSendTime
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxUseCoverSheet
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxCoverSheetName
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxReturnReceipt
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxHighResolution
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxTrimPageEnds
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxModem
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
NSPrintFaxJob
Deprecated. Do not use.
Available in Mac OS X v10.0 and later.
Declared in NSPrintInfo.h
.
© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-01-06)