PrintInfo

PrintInfo

Inherits From: Object

Declared In: appkit/PrintInfo.h

Class Description

A PrintInfo object stores information that's used during printing. The Application object automatically creates a PrintInfo object that, by default, is used for all printing jobs (for that application). You can create any number of additional PrintInfo objects; however, only one can be "active" at a time, as set through Application's setPrintInfo: method. The currently active PrintInfo object is returned through Application's printInfo method.
Although you can set a PrintInfo's attributes through the methods it provides, this is usually the task of other objects, notably the PageLayout and PrintPanel objects. The View or Window that's being printed may also supercede some PrintInfo settings. In particular, a View or Window can supply the range of pages in the document and can provide its own pagination mechanism through the knowsPagesFirst:last: and getRect:forPage: methods (see the documentation of these methods in the View class for details).
If the printed View or Window doesn't supply a pagination, the PrintInfo's vertical and horizontal pagination constants are used to trigger built-in pagination mechanisms:

Pagination Constant Meaning

NX_AUTOPAGINATION The image is diced into equal-sized rectangles and placed in one column of pages.

NX_FITPAGINATION The image is scaled to produce one column (horizontal) or one row (vertical) of pages.

NX_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 (NX_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 PrintInfo's scaling factor (as set through setScalingFactor:) is independent of the scaling that's imposed by pagination and is applied after the document has been paginated.
The PrintInfo attributes that describe a size on a sheet of paper (the margins and the size of the paper rectangle) are in points, where 72 points equals one inch.
Page numbers (firstPage, lastPage, and so on) are as they appear in the document. For example, to print the first three pages of a document that contains pages numbered from 20 to 29, firstPage would be set to 20 and lastPage to 22.

Instance Variables

char *paperType;
NXRect paperRect;
NXCoord leftPageMargin;
NXCoord rightPageMargin;
NXCoord topPageMargin;
NXCoord bottomPageMargin;
float scalingFactor;
char pageOrder;
struct _pInfoFlags {
unsigned int orientation:1;
unsigned int horizCentered:1;
unsigned int vertCentered:1;
unsigned int allPages:1;
unsigned int horizPagination:2;
unsigned int vertPagination:2;
unsigned int printerIsOld:1;
unsigned int reversePageOrder:1;
} pInfoFlags;
int firstPage;
int lastPage;
int currentPage;
int copies;
char *outputFile;
DPSContext context;
short pagesPerSheet;
NXPrinter *printerObject;
id jobFeaturesTable;
const char *paperFeed;

paperType Type of paper.

paperRect Rectangle representing the paper's area.

leftPageMargin Size of the left margin in points.

rightPageMargin Size of the right margin in points.

topPageMargin Size of the top margin in points.

bottomPageMargin Size of the bottom margin in points.

scalingFactor Factor to scale image by.

pageOrder Order of pages in document.

pInfoFlags.orientation Landscape or portrait mode.

pInfoFlags.horizCentered True if the image is centered horizontally on the page.

pInfoFlags.vertCentered True if the image is centered vertically on the page.

pInfoFlags.allPages True if all the pages are to be printed.

pInfoFlags.horizPagination Horizontal pagination mode.

pInfoFlags.vertPagination Vertical pagination mode.

firstPage Page number of the first page to print.

lastPage Page number of the last page to print.

currentPage Page number of the page currently being printed.

copies Number of copies to print.

outputFile File to spool to.

context Spooling context.

pagesPerSheet The number of pages per sheet of paper.

printerObject The printer that the printing job will run on.

jobFeaturesTable Table of additional printing job attributes.

paperFeed Paper feed slot name.

Method Types

Initializing and freeing a PrintInfo instance

init

free

Defining the printing rectangle setMarginLeft:right:top:bottom:

getMarginLeft:right:top:bottom:
setOrientation:andAdjust:
orientation
setPaperRect:andAdjust:
paperRect
setPaperType:andAdjust:
paperType

Page range setFirstPage:

firstPage
setLastPage:
lastPage
setAllPages:
isAllPages
currentPage

Pagination and scaling setHorizPagination:

horizPagination
setVertPagination:
vertPagination
setScalingFactor:
scalingFactor

Positioning the image on the page

setHorizCentered:

isHorizCentered
setVertCentered:
isVertCentered
setPagesPerSheet:
pagesPerSheet

Print job attributes initializeJobDefaults

setJobFeature:toValue:
valueForJobFeature:
removeJobFeature:
jobFeatures
setPageOrder:
pageOrder
setReversePageOrder:
reversePageOrder
setCopies:
copies
setPaperFeed:
paperFeed

Specifying the printer + setDefaultPrinter:

+ getDefaultPrinter
setPrinter:
printer

Spooling setOutputFile:

outputFile
setContext:
context

Archiving read:

write:

Class Methods

getDefaultPrinter

(NXPrinter *)getDefaultPrinter

Returns an NXPrinter object that corresponds to the user's default printer, as declared in the defaults database. If the printer can't be found, nil is returned.
See also: + setDefaultPrinter:, setPrinter:, printer

setDefaultPrinter:

setDefaultPrinter:(NXPrinter *)printer

Sets the user's default printer by writing the name and host of printer to the defaults database. Unless a PrintInfo's printer is otherwise set (through setPrinter:) the default printer is used for printing.
See also: + getDefaultPrinter, setPrinter:, printer

Instance Methods

context

(DPSContext)context

Returns the Display PostScript context used for printing.

copies

(int)copies

Returns the number of copies that will be printed.

currentPage

(int)currentPage

Returns the page number of the page currently being printed. This method is valid only while printing or faxing.

firstPage

(int)firstPage

Returns the page number of the first page that will be printed, as set through setFirstPage:, or MININT if the value hasn't been explicitly set. If all pages are being printed, the first page value is ignored during printing. If the page order is reversed, this value gives the page number of the last page that will be printed.
See also: setFirstPage:, setAllPages:, setPageOrder:

free

free

Frees the PrintInfo object.

getMarginLeft:right:top:bottom:

getMarginLeft:(NXCoord *)leftMargin

right:(NXCoord *)rightMargin
top:(NXCoord *)topMargin
bottom:(NXCoord *)bottomMargin

Returns, by reference, the sizes of the four page margins measured in points.
See also: setMarginLeft:right:top:bottom:

horizPagination

(int)horizPagination

Returns a constant that represents the manner in which an image is distributed horizontally among pages. See the class description, above, for a description of the pagination constants.
See also: setHorizPagination:

init

init

Initializes the PrintInfo object after memory for it has been allocated through alloc or allocFromZone:. Returns self.

initializeJobDefaults

initializeJobDefaults

Called before each print job (specifically, before the Print panel is displayed), this method initializes the following PrintInfo attributes:

Attribute Value

First page MININT

Last page MAXINT

Copies 1

Page order First-to-last

Printer The user's default printer

Paper feed The default paper feed slot

isAllPages

(BOOL)isAllPages

Returns whether all pages will be printed. If NO, only those pages that fall within [firstPage, lastPage] will be printed.
See also: setAllPages:

isHorizCentered

(BOOL)isHorizCentered

Returns whether the image is centered horizontally on a page; if this returns NO, the image is flush against the left margin. If the image spills over more than one page horizontally, this value is ignored and the image is always set against the left margin.

isVertCentered

(BOOL)isVertCentered

Returns whether the image is centered vertically on a page; if this returns NO, the image is flush against the top margin. If the image spills over more than one page vertically, then this value is ignored and the image is always set against the top margin.
See also: setVertCentered:

jobFeatures

(const char **)jobFeatures

Returns a pointer to an array of pointers that contains the keys to the job features table, the hash table that contains additional printing-job attributes. You would use these keys as arguments to methods such as valueForJobFeature: and removeJobFeature:. It's the caller's responsibility to free the pointer to the array, but not the pointers in the array.
See also: setJobFeature:toValue:, valueForJobFeature:, removeJobFeature:

lastPage

(int)lastPage

Returns the page number of the last page that will be printed, as set through setLastPage:, or MAXINT if the value hasn't been explicitly set. If all pages are being printed, the last page value is ignored during printing. If the page order is reversed, this value gives the page number of the first page that will be printed.
See also: setLastPage:, setAllPages:, setReversePageOrder:

orientation

(char)orientation

Returns the page orientation as NX_PORTRAIT or NX_LANDSCAPE.
See also: setOrientation:andAdjust:, setPaperType:andAdjust:, setPaperRect:andAdjust:

outputFile

(const char *)outputFile

Returns the name of the file to which the generated PostScript code is sent. If this is NULL, the code is written to a temporary file.
See also: setOutputFile:

pageOrder

(char)pageOrder

Returns a constant that denotes the order in which pages are printed. See setPageOrder: for the page order constants.
See also: setPageOrder:

pagesPerSheet

(short)pagesPerSheet

Returns the number of pages per sheet of paper.

paperFeed

(const char *)paperFeed

Returns the name of the currently used paper feed slot.
See also: setPaperFeed:

paperRect

(const NXRect *)paperRect

Returns a pointer to a rectangle that gives the size of the paper, measured in points. Note that the rectangle is useful only for its size field; the origin of the paper is always (0.0, 0.0).

paperType

(const char *)paperType

Returns the paper type. If the type is unknown, an empty string is returned.

printer

(NXPrinter *)printer

Returns the NXPrinter that's used for printing.

read:

read:(NXTypedStream *)stream

Reads the PrintInfo from the typed stream stream.

removeJobFeature:

removeJobFeature:(const char *)key

Removes, from the job-features hash table, the element that corresponds to key.
See also: jobFeatures, setJobFeature:toValue:, valueForJobFeature:

reversePageOrder

(BOOL)reversePageOrder

Returns YES if the PrintInfo dictates that pages will be printed in reverse order (in other words, if the ordering established through setPageOrder: is reversed).
See also: setReversePageOrder:, setPageOrder:

scalingFactor

(float)scalingFactor

Returns the factor by which the image is scaled.

setAllPages:

setAllPages:(BOOL)flag

Sets whether all the pages of the document are to be printed (as opposed to a subset given by the firstPage and lastPage values).

setContext:

setContext:(DPSContext)aContext

Sets the Display PostScript context used for printing. This is normally done by the printing machinery in View.

setCopies:

setCopies:(int)anInt

Sets the number of copies that will be printed.

setFirstPage:

setFirstPage:(int)anInt

Sets the page number of the first page that will be printed.

setHorizCentered:

setHorizCentered:(BOOL)flag

Sets whether the image is centered horizontally on a page; if flag is NO, the image is flush against the left margin. If the image spills over more than one page horizontally, then flag is ignored and the image is always against the left margin.

setHorizPagination:

setHorizPagination:(int)mode

Sets the way in which a document is divided horizontally into pages. See the class description, above, for the pagination constants that you can use as the argument to this method.

setJobFeature:toValue:

setJobFeature:(const char *)feature toValue:(const char *)value

Sets the value of the given job feature. The feature is added to the job-features hash table if it isn't already present.

setLastPage:

setLastPage:(int)anInt

Sets the page number of the last page that will be printed.

setMarginLeft:right:top:bottom:

setMarginLeft:(NXCoord)leftMargin

right:(NXCoord)rightMargin
top:(NXCoord)topMargin
bottom:(NXCoord)bottomMargin

Sets the margins. All margins are in points.

setOrientation:andAdjust:

setOrientation:(char)mode andAdjust:(BOOL)flag

Sets the orientation or the page; mode should be either NX_PORTRAIT or NX_LANDSCAPE.
If flag is NO, then only the orientation is affected. If flag is YES, the paper rectangle value is updated to reflect the new orientation.

setOutputFile:

setOutputFile:(const char *)aString

Sets the name of the file to which the generated PostScript code is sent. If aString is NULL, the code is sent to a temporary file.

setPageOrder:

setPageOrder:(char)mode

Sets the order in which pages are printed as one of these constants:

NX_DESCENDINGORDER
NX_SPECIALORDER
NX_ASCENDINGORDER
NX_UNKNOWNORDER

See also: reversePageOrder, pageOrder

setPagesPerSheet:

setPagesPerSheet:(short)pageCount

Sets the number of pages of the document that are printed on a single sheet of paper. This number is rounded up to a power of two when used by the system.

setPaperFeed:

setPaperFeed:(const char *)paperFeedSlot

Sets the paper feed slot by name. If paperFeedSlot is NULL (or an empty string), any paper feed slot is acceptable; to choose the manual feed slot, set the name to "NXManual". Any other name that you use must appear in the PPD table (as documented in the NXPrinter class). Returns self.
See also: setPaperFeed:

setPaperRect:andAdjust:

setPaperRect:(const NXRect *)aRect andAdjust:(BOOL)flag

Sets the size of the paper, measured in points, that's to be used in printing. The origin of the rectangle is always set to (0,0)--the origin field of aRect is ignored.
If flag is NO, then only the paper rectangle is changed. If flag is YES, the orientation and paper type values are updated to reflect the new size.

setPaperType:andAdjust:

setPaperType:(const char *)type andAdjust:(BOOL)flag

Sets the name of the paper type.
If flag is NO, only the paper type is changed. If flag is YES, the paper rectangle and orientation values are updated to reflect the new type (given that type is a recognized paper type).

setPrinter:

setPrinter:(NXPrinter *)aPrinter

Sets the printer that's used in subsequent printing jobs.

setReversePageOrder:

setReversePageOrder:(BOOL)flag

Sets whether pages are printed in reverse order. This ordering is applied to the page order mode set through setPageOrder:. Returns self.
See also: reversePageOrder, setPageOrder:

setScalingFactor:

setScalingFactor:(float)aFloat

Sets the amount by which the document is scaled. Note that the scaling you set has no effect if the document does its own pagination through View's knowsPagesFirst:last: method.

setVertCentered:

setVertCentered:(BOOL)flag

Sets whether the default implementation of placePrintRect:offset: in the View class centers the image vertically on the page.

setVertPagination:

setVertPagination:(int)mode

Sets the way in which a document is divided vertically into pages. See the class description, above, for the pagination constants that you can use as the argument to this method.

valueForJobFeature:

(const char *)valueForJobFeature:(const char *)feature

Returns the value for the given printing feature, as stored in the job-features table.
See also: jobFeatures, setJobFeature:toValue:, removeJobFeature

vertPagination

(int)vertPagination

Returns a constant that represents the manner in which an image is distributed vertically among pages. See the class description, above, for a description of the pagination constants.
See also: setVertPagination:

write:

write:(NXTypedStream *)stream

Writes the PrintInfo to the typed stream stream.

	Pagination Constant	Meaning

	NX_AUTOPAGINATION	The image is diced into equal-sized rectangles and placed in one column of pages.

	NX_FITPAGINATION	The image is scaled to produce one column (horizontal) or one row (vertical) of pages.

	NX_CLIPPAGINATION	The image is clipped to produce one column or row of pages.

	paperType	Type of paper.

	paperRect	Rectangle representing the paper's area.

	leftPageMargin	Size of the left margin in points.

	rightPageMargin	Size of the right margin in points.

	topPageMargin	Size of the top margin in points.

	bottomPageMargin	Size of the bottom margin in points.

	scalingFactor	Factor to scale image by.

	pageOrder	Order of pages in document.

	pInfoFlags.orientation	Landscape or portrait mode.

	pInfoFlags.horizCentered	True if the image is centered horizontally on the page.

	pInfoFlags.vertCentered	True if the image is centered vertically on the page.

	pInfoFlags.allPages	True if all the pages are to be printed.

	pInfoFlags.horizPagination	Horizontal pagination mode.

	pInfoFlags.vertPagination	Vertical pagination mode.

	firstPage	Page number of the first page to print.

	lastPage	Page number of the last page to print.

	currentPage	Page number of the page currently being printed.

	copies	Number of copies to print.

	outputFile	File to spool to.

	context	Spooling context.

	pagesPerSheet	The number of pages per sheet of paper.

	printerObject	The printer that the printing job will run on.

	jobFeaturesTable	Table of additional printing job attributes.

	paperFeed	Paper feed slot name.

	Attribute	Value

	First page	MININT
	Last page	MAXINT
	Copies	1
	Page order	First-to-last
	Printer	The user's default printer
	Paper feed	The default paper feed slot