Developer Documentation
PATH  Mac OS X Documentation > Application Kit Reference: Java

Table of Contents

NSPrintInfo


Inherits from:
NSObject
Package:
com.apple.yellow.application


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
AutoPagination The image is diced into equal-sized rectangles and placed in one column of pages.
FitPagination The image is scaled to produce one column or one row of pages.
ClipPagination 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 (FitPagination), 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
PrintPaperName String The paper name.
PrintPaperSize NSSize Height and width of paper in points.
PrintMustCollate boolean If true, collates output.
PrintFormName String Form name such as "Letter" or "Letter Small".
PrintOrientation int PortraitOrientation or LandscapeOrientation
PrintLeftMargin float The left margin in points.
PrintRightmargin float The right margin in points.
PrintTopMargin float The top margin in points.
PrintBottomMargin float The bottom margin in points.
PrintHorizontallyCentered boolean If true, pages are centered horizontally.
PrintVerticallyCentered boolean If true, pages are centered vertically.
PrintHorizontalPagination int AutoPagination, FitPagination, or ClipPagination. See setHorizontalPagination for details.
PrintVerticalPagination int AutoPagination, FitPagination, or ClipPagination. See setVerticalPagination for details.
PrintScalingFactor float Scale factor before pagination.
PrintAllPages boolean If true, includes all pages in output.
PrintReversePageOrder boolean If true, prints last page first.
PrintFirstPage int The first page in the print job.
PrintLastPage int The last page in the print job.
PrintCopies int Number of copies to spool.
PrintPagesPerSheet 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.
PrintJobFeatures NSMutableDictionary Features from the NSPrinter object where keys are the feature name and values are the settings. For example, the key PrintPaperFeed might have the value *InputSlot/Upper. See the NSPrinter class description.
PrintPaperFeed String The printer slot. For example, InputSlot/Upper or PrintManualFeed.
PrintPrinter NSPrinter The printer to use.
PrintJobDisposition String PrintSpoolJob, PrintFaxJob, PrintPreviewJob, PrintSaveJob, or PrintCancelJob. See setJobDisposition for details.
PrintSavePath String Pathname to save as a file if job disposition is PrintSaveJob.
PrintFaxReceiverNames NSArray Array of Strings containing receiver names for a fax job.
PrintFaxReceiverNumbers NSArray Array of Strings containing the receiver phone numbers for a fax job.
PrintFaxSendTime NSDate When to send the fax.
PrintFaxUseCoverSheet boolean If true, send cover sheet.
PrintFaxCoverSheetName String The filename containing the cover sheet.
PrintFaxReturnReceipt boolean If true, sends confirmation email when fax is sent.
PrintFaxHighResolution boolean If true, sends fax at high resolution.
PrintFaxTrimPageEnds boolean If true, trims page ends, otherwise sends complete pages.
PrintFaxModem NSPrinter The fax modem to use.




Constants


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


Pagination Constant Meaning
AutoPagination The image is diced into equal-sized rectangles and placed in one column of pages.
FitPagination The image is scaled to produce one column or one row of pages.
ClipPagination 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
PortraitOrientation Description forthcoming.
LandscapeOrientation Description forthcoming.



Method Types


Constructors
NSPrintInfo
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


Constructors



NSPrintInfo

public NSPrintInfo()

Description forthcoming.

public NSPrintInfo(NSDictionary aDictionary)

Creates a newly allocated NSPrintInfo object by assigning it the parameters specified in aDictionary. 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




Static Methods



defaultPrinter

public static NSPrinter defaultPrinter()

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

See Also: setDefaultPrinter



setDefaultPrinter

public static 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

public static 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 null.

See Also: sharedPrintInfo



sharedPrintInfo

public static NSPrintInfo sharedPrintInfo()

Returns the shared NSPrintInfo object.

See Also: setSharedPrintInfo



sizeForPaperName

public static NSSize sizeForPaperName(String 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

public float bottomMargin()

Returns the height of the bottom margin in points.

See Also: setBottomMargin



dictionary

public 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

public int horizontalPagination()

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

See Also: setVerticalPagination, verticalPagination



isHorizontallyCentered

public boolean isHorizontallyCentered()

Returns true if the image is centered horizontally, false otherwise.

See Also: isVerticallyCentered, setHorizontallyCentered



isVerticallyCentered

public boolean isVerticallyCentered()

Returns true if the image is centered vertically, false otherwise.

See Also: isHorizontallyCentered, setVerticallyCentered



jobDisposition

public String jobDisposition()

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

leftMargin

public float leftMargin()

Returns the width of the left margin in points.

See Also: setLeftMargin



orientation

public int orientation()

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

paperName

public String paperName()

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

See Also: setPaperName



paperSize

public NSSize paperSize()

Returns the size of the paper in points.

See Also: setPaperSize



printer

public NSPrinter printer()

Returns the NSPrinter to be used for printing.

See Also: setPrinter



rightMargin

public float rightMargin()

Returns the width of the right margin in points.

See Also: setRightMargin



setBottomMargin

public void setBottomMargin(float margin)

Sets the bottom margin to margin specified in points.

See Also: bottomMargin



setHorizontalPagination

public void setHorizontalPagination(int mode)

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

See Also: horizontalPagination, setVerticalPagination, verticalPagination



setHorizontallyCentered

public void setHorizontallyCentered(boolean flag)

If flag is true the image will be centered horizontally.

See Also: isHorizontallyCentered, isVerticallyCentered, setVerticallyCentered



setJobDisposition

public void setJobDisposition(String disposition)

Sets the action specified for the job to disposition. disposition can be one of:
Disposition Meaning
PrintSpoolJob Normal print job.
PrintFaxJob Fax job.
PrintPreviewJob Send to Preview application.
PrintSaveJob Save to a file.
PrintCancelJob Cancel print job.

See Also: jobDisposition



setLeftMargin

public void setLeftMargin(float margin)

Sets the left margin to margin specified in points.

See Also: leftMargin



setOrientation

public void setOrientation(int orientation)

Sets the page orientation to orientation where orientation is either PortraitOrientation or LandscapeOrientation. 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, orientation



setPaperName

public void setPaperName(String 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, paperName



setPaperSize

public 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, paperSize



setPrinter

public 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

public void setRightMargin(float margin)

Sets the right margin to margin specified in points.

See Also: rightMargin



setTopMargin

public void setTopMargin(float margin)

Sets the top margin to margin specified in points.

See Also: topMargin



setUpPrintOperationDefaultValues

public 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

public void setVerticalPagination(int mode)

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

See Also: horizontalPagination, setHorizontalPagination, verticalPagination



setVerticallyCentered

public void setVerticallyCentered(boolean flag)

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

See Also: isHorizontallyCentered, isVerticallyCentered, setHorizontallyCentered



topMargin

public float topMargin()

Returns the top margin in points.

See Also: setTopMargin



verticalPagination

public int verticalPagination()

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

See Also: horizontalPagination, setHorizontalPagination




Table of Contents