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

Table of Contents

NSPrinter


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


Class Description


An NSPrinter object describes a printer's capabilities, such as whether the printer can print in color and whether it provides a particular font. An NSPrinter object represents either a particular make or type of printer, or an actual printer available to the computer. You use NSPrinter to get information about printers, not modify printer attributes or control a printing job.

There are two ways to create an NSPrinter:

Once you have an NSPrinter, there's only one thing you can do with it: retrieve information regarding the type of printer or regarding the actual printer the object represents.

When you create an NSPrinter object, the object reads the file that corresponds to the type of printer, a model name, you specified and stores the data it finds there in named tables. Printer types are described in files written in the PostScript Printer Description (PPD) format. Any piece of information in the PPD tables can be retrieved through the methods stringForKeyInTable and stringListForKeyInTable, as explained later. Commonly needed items, such as whether a printer supports color or the size of the page on which it prints, are available through more direct methods (methods such as isColor and pageSizeForPaper).


Note: To understand what the NSPrinter tables contain, you need to be acquainted with the PPD file format. This is described in PostScript Printer Description File Format Specification, version 4.0, available from Adobe Systems Incorporated. The rest of this class description assumes a familiarity with the concepts and terminology presented in the Adobe manual. A brief summary of the PPD format is given below; PPD terms defined in the Adobe manual are shown in italic.


PPD Format


A PPD file statement, or entry, associates a value with a main keyword:

*mainKeyword: value

The asterisk is literal; it indicates the beginning of a new entry.

For example:

*ModelName: "MMimeo Machine"
*3dDevice: False

A main keyword can be qualified by an option keyword:

*mainKeyword optionKeyword: value

For example:

*PaperDensity Letter: "0.1"
*PaperDensity Legal: "0.2"
*PaperDensity A4: "0.3"
*PaperDensity B5: "0.4"

In addition, any number of entries may have the same main keyword with no option keyword yet give different values:

*InkName: ProcessBlack/Process Black
*InkName: CustomColor/Custom Color
*InkName: ProcessCyan/Process Cyan
*InkName: ProcessMagenta/Process Magenta
*InkName: ProcessYellow/Process Yellow

Option keywords and values can sport translation strings. A translation string is a textual description, appropriate for display in a user interface, of the option or value. An option or value is separated from its translation string by a slash:

*Resolution 300dpi/300 dpi: " ... "
*InkName: ProcessBlack/Process Black

In the first example, the 300dpi option would be presented in a user interface as "300 dpi." In the second example, the translation string for the ProcessBlack value is set to "Process Black".

NSPrinter treats entries that have an *OrderDependency or *UIConstraint main keyword specially. Such entries take the following forms (the bracketed elements are optional):

*OrderDependency: real section mainKeyword [optionKeyword] 
*UIConstraint: mainKeyword1 [optionKeyword1] mainKeyword2 [optionKeyword2]

There may be more than one UIConstraint entry with the same mainKeyword1 or mainKeyword1/optionKeyword1 value. Below are some examples of *OrderDependency and *UIConstraint entries:

*OrderDependency: 10 AnySetup *Resolution
*UIConstraint: *Option3 None *PageSize Legal
*UIConstraint: *Option3 None *PageRegion Legal

Explaining these entries is beyond the scope of this documentation; however, it's important to note their forms in order to understand how they're represented in the NSPrinter tables.


NSPrinter Tables


NSPrinter defines five key-value tables to store PPD information. The tables are identified by the names given below:


Name Contents
PPD General information about a printer type. This table contains the values for all entries in a PPD file except those with the *OrderDependency and *UIConstraint main keywords. The values in this table don't include the translation strings.
PPDOptionTranslation Option keyword translation strings.
PPDArgumentTranslation Value translation strings.
PPDOrderDependency *OrderDependency values.
PPDUIConstraints *UIConstraint values.

There are two principle methods for retrieving data from the NSPrinter tables:

For both methods, the first argument is an String that names a key-which part of a PPD file entry the key corresponds to depends on the table (as explained in the following sections). The second argument names the table that you want to search. The values that are returned by these methods, whether singular or in an array, are always Strings, even if the value wasn't a quoted string in the PPD file.

The NSPrinter tables store data as ASCII text, thus the two methods described above are sufficient for retrieving any value from any table. NSPrinter provides a number of other methods, such as booleanForKeyInTable and intForKeyInTable, that retrieve single values and coerce them, if possible, into particular data types. The coercion doesn't affect the data that's stored in the table (it remains in ASCII format).

To check the integrity of a table, use the isKeyInTable and statusForTable methods. The former returns a boolean that indicates whether the given key is valid for the given table; the latter returns an error code that describes the general state of a table (in particular, whether it actually exists).


Retrieving Values from the PPD Table


Keys for the PPD table are strings that name a main keyword or main keyword/option keyword pairing (formatted as "mainKeyword/optionKeyword"). In both cases, you exclude the main keyword asterisk.

To retrieve the value for a main keyword/option keyword pair, pass the keywords formatted as "mainKeyword/optionKeyword".

stringForKeyInTable can determine if a main keyword has options. If you pass a main keyword (only) as the first argument to the method, and if that keyword has options in the PPD file, the method returns an empty string. If it doesn't have options, it returns the value of the first occurrence of the main keyword.

To retrieve the values for all occurrences of a main keyword, use the stringListForKeyInTable method giving the main keyword only.

In addition, stringListForKeyInTable can be used to retrieve all the options for a main keyword (given that the main keyword has options).


Retrieving Values from the Option and Argument Translation Tables


A key to a translation table is similar to a key to the PPD table: It's a main keyword or main/option keyword pair (again excluding the asterisk). However, the values that are returned from the translation tables are the translation strings for the option or argument (value) portions of the PPD file entry.

As with the PPD table, use stringListForKeyInTable to request an array of all occurrences of a main keyword.


Retrieving Values from the Order Dependency Table


As mentioned earlier, an order dependency entry takes this form:

*OrderDependency: real section mainKeyword [optionKeyword] 

These entries are stored in the PPDOrderDependency table. To retrieve a value from this table, always use stringListForKeyInTable. The value passed as the key is, again, a main keyword or main keyword/option keyword pair; however, these values correspond to the mainKeyword and optionKeyword parts of an order dependency entry's value. As with the other tables, the main keyword's asterisk is excluded. The method returns an NSArray of two Strings that correspond to the real and section values for the entry.


Retrieving Values from the UIConstraints Table


Retrieving a value from the PPDUIConstraints table is similar to retrieving a value from the PPDOrderDependency table: always use stringListForKeyInTable and the key corresponds to elements in the entry's value. Given the following form (as described earlier), the key corresponds to mainKeyword1/optionKeyword1:

*UIConstraint: mainKeyword1 [optionKeyword1] mainKeyword2 [optionKeyword2]

The NSArray returned by stringListForKeyInTablecontains the mainKeyword2 and optionKeyword2 values (with the keywords stored as separate elements in the NSArray) for every *UIConstraints entry that has the given mainKeyword1/optionKeyword1 value.

Note that the main keywords that are returned in the NSArray don't have asterisks. Also, the NSArray that's returned always alternates main and option keywords. If a particular main keyword doesn't have an option associated with it, the string for the option will be empty (but the entry in the NSArray for the option will exist).




Constants


These constants specify a table's status. They're used by statusForTable.


Mode Meaning
PrinterTableOK Description forthcoming.
PrinterTableNotFound Description forthcoming.
PrinterTableError Description forthcoming.



Method Types


Constructors
NSPrinter
Creating an NSPrinter
printerWithName
printerWithType
Getting general printer information
printerNames
printerTypes
Getting attributes
domain
host
name
note
type
Getting specific information
acceptsBinary
imageRectForPaper
pageSizeForPaper
isColor
isFontAvailable
isOutputStackInReverseOrder
languageLevel
Querying the tables
isKeyInTable
stringForKeyInTable
stringListForKeyInTable
booleanForKeyInTable
floatForKeyInTable
intForKeyInTable
rectForKeyInTable
sizeForKeyInTable
statusForTable
deviceDescription


Constructors



NSPrinter

public NSPrinter()

Description forthcoming.


Static Methods



printerNames

public static NSArray printerNames()

Returns an array of recognized printer names.

See Also: printerTypes, name



printerTypes

public static NSArray printerTypes()

Returns an array of recognized model names.

See Also: printerNames, type



printerWithName

public static NSPrinter printerWithName(String name)

Returns an NSPrinter that represents an actual printer with the given name. Returns null if the specified printer is not available.

public static NSPrinter printerWithName( String name, String domain, boolean includeUnavailable)

Returns an NSPrinter that represents an actual printer with the given name and domain. If domain is null, the first printer (matching name) found on any host or domain is used. Returns null if the specified printer is not available and includeUnavailable is false. If includeUnavailable is true, the availability of the printer is ignored.

See Also: printerWithType, printerNames, domain, name



printerWithType

public static NSPrinter printerWithType(String type)

Returns an NSPrinter with the given printer type.

See Also: printerWithName:, printerTypes, type




Instance Methods



acceptsBinary

public boolean acceptsBinary()

Returns true if the printer accepts binary PostScript, otherwise false.

booleanForKeyInTable

public boolean booleanForKeyInTable( String key, String table)

Returns a boolean value associated with key in table. Also returns false if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



deviceDescription

public NSDictionary deviceDescription()

Returns a dictionary of keys and values describing the device. See NSGraphics "Constants" (page 647) for possible keys.

domain

public String domain()

Returns the name of the domain in which the printer resides. Returns null if the receiver doesn't represent an actual printer.

See Also: printerWithName:domain:includeUnavailable:



floatForKeyInTable

public float floatForKeyInTable( String key, String table)

Returns a floating-point value associated with key in table. Returns 0.0 if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



host

public String host()

Returns the name of the printer's host computer.

imageRectForPaper

public NSRect imageRectForPaper(String paperName)

Returns the printing rectangle for the paper paperName. Possible values for paperName are contained in the printer's PPD file. Typical values are Letter and Legal.

See Also: pageSizeForPaper



intForKeyInTable

public int intForKeyInTable( String key, String table)

Returns an integer value associated with key in table. Returns 0 if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



isColor

public boolean isColor()

Returns true if the printer can print color, false otherwise.

isFontAvailable

public boolean isFontAvailable(String faceName)

Returns true if font faceName is available to the receiver, false otherwise.

isKeyInTable

public boolean isKeyInTable( String key, String table)

Returns true if key is in table, false otherwise.

isOutputStackInReverseOrder

public boolean isOutputStackInReverseOrder()

Returns true if the printer outputs pages in reverse page order, false otherwise.

languageLevel

public int languageLevel()

Returns the PostScript Language Level recognized by the printer.

name

public String name()

Returns the printer's name.

See Also: printerNames, printerWithName:



note

public String note()

Returns the note associated with the printer.

pageSizeForPaper

public NSSize pageSizeForPaper(String paperName)

Returns the size of the page for the paper type paperName. Possible values for paperName are contained in the printer's PPD file. Typical values are Letter and Legal.

See Also: imageRectForPaper



rectForKeyInTable

public NSRect rectForKeyInTable( String key, String table)

Returns the rectangle associated with key in table. Returns NSRect.ZeroRect if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



sizeForKeyInTable

public NSSize sizeForKeyInTable( String key, String table)

Returns the size associated with key in table. The returned width and height are 0.0 if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



statusForTable

public int statusForTable(String table)

Returns the status of table. The following are possible return values:

stringForKeyInTable

public String stringForKeyInTable( String key, String table)

Returns the first occurrence of a value associated with key in table. If key is a main keyword only, and if that keyword has options in the PPD file, this method returns an empty string. Use stringListForKeyInTable to retrieve the values for all occurrences of a main keyword. Returns null if key is not in table.

See Also: isKeyInTable, booleanForKeyInTable, floatForKeyInTable, intForKeyInTable, rectForKeyInTable, sizeForKeyInTable



stringListForKeyInTable

public NSArray stringListForKeyInTable( String key, String table)

Returns an array of strings, one for each occurrence, associated with key in table. Returns null if key is not in table.

See Also: isKeyInTable, stringForKeyInTable



type

public String type()

Returns the name of the printer's type.

See Also: printerTypes




Table of Contents