< Previous PageNext Page > Hide TOC

Accessing Printer Information

An NSPrinter object gives you access to the capabilities of a particular printer as described in the printer’s PostScript Printer Description (PPD) file. NSPrinter provides read-only access to the printer’s features; you cannot configure a printer’s settings.

Contents:

Creating a Printer
Retrieving Printer Attributes

Creating a Printer

You can create an NSPrinter object by specifying either the printer’s name or its type. The user creates the list of printers recognized by NSPrinter using the Print Center application. The NSPrinter class methods printerNames and printerTypes return the names and types of these printers. You then create an NSPrinter object with printerWithName: or printerWithType:. If multiple printers have the same type, printerWithType: returns the NSPrinter object for the first printer that matches.

The following example creates an NSPrinter object for a printer named “My LaserWriter”.

/* Create an NSPrinter object from a printer name. */

NSPrinter *printer = [NSPrinter printerWithName:@"My LaserWriter"];

Retrieving Printer Attributes

A printer normally has associated with it a PPD file that describes the capabilities of the printer. An NSPrinter object reads the PPD file that corresponds to the printer’s type and stores the data it finds there in named tables. NSPrinter defines five key-value tables to store PPD information. The tables are identified by the names given below:

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

• stringForKey:inTable: returns the value for the first occurrence of a given key in the given table.

• stringListForKey:inTable: returns an array of values, one for each occurrence of the key.

For both methods, the first argument is an NSString 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 NSStrings, even if the value wasn't a quoted string in the PPD file.

The two methods described above are sufficient for retrieving any value from any table. NSPrinter provides a number of other methods, such as booleanForKey:inTable: and intForKey:inTable:, which retrieve single values and coerce them, if possible, into particular data types.

To check the integrity of a table, use the isKey:inTable: 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).

The following sections describe the contents of each table. To understand how NSPrinter parses the PPD file and constructs its tables, 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.

You can also see Using PostScript Printer Description Files, found on the Printing page of the Core Technologies section of the Mac OS X developer documentation. It contains important information if you want to install and use PPD files in Mac OS X. It details the differences between PPD support in Mac OS X and earlier versions of the Mac OS, provides information about localizing PPD files, shows how to specify that certain features should be grouped in the interface, describes where PPD files need to be installed, and tells what you need to do if you provide a printing dialog extension for your PostScript printer.

Retrieving Values from the PPD Table

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: "Apple Laserwriter Pro 810"

*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

Keys for the PPD table are strings that name a main keyword or main keyword/option keyword pairing. In both cases, you exclude the main keyword asterisk. The following example invokes stringForKey:inTable: to retrieve the value for an un-optioned main keyword:

/* Sets sValue to FALSE. */

NSString *sValue = [printer stringForKey:@"3dDevice" inTable:@"PPD"];

To retrieve the value for a main keyword/option keyword pair, pass the keyword formatted as “mainKeyword/optionKeyword”:

/* Sets sValue to "0.3". */

NSString *sValue = [printer stringForKey:@"PaperDensity/A4" inTable:@"PPD"];

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:

/* Sets sValue to an empty string. */

NSString *sValue = [printer stringForKey:@"PaperDensity" inTable:@"PPD"];

/* Sets sValue to "ProcessBlack". */

NSString *sValue = [printer stringForKey:@"InkName" inTable:@"PPD"];

To retrieve the values for all occurrences of a main keyword, use the stringListForKey:inTable: method giving the main keyword only:

/* Sets sList to an array containing "ProcessBlack", "CustomColor", etc. */

NSArray *sList = [printer stringListForKey:@"InkName" inTable:@"PPD"];

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

/* Sets sList to an array containing "Letter", "Legal", "A4", etc. */

NSArray *sList = [printer stringListForKey:@"PaperDensity" inTable:@"PPD"];

Retrieving Values from the Option and Argument Translation Tables

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”.

A key for a translation table is similar to a key for 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. For example:

/* Sets sValue to "300 dpi". */

NSString *sValue = [printer stringForKey:@"Resolution/300dpi"

    inTable:@"PPDOptionTranslation"];

As with the PPD table, use stringListForKey:inTable: to request an array of all occurrences of a main keyword:

/* Sets sList to an array containing "Process Black", "Custom Color", etc. */

NSArray *sList = [printer stringListForKey:@"InkName"

    inTable:@"PPDArgumentTranslation"];

Retrieving Values from the Order Dependency Table

NSPrinter treats entries that have an *OrderDependency main keyword specially. Such entries take the following forms (the bracketed element is optional):

*OrderDependency: real section *mainKeyword [optionKeyword]

Below is an example of an *OrderDependency entry:

*OrderDependency: 10 AnySetup *Resolution

These entries are stored in the PPDOrderDependency table. To retrieve a value from this table, always use stringListForKey:inTable:. 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. The method returns an NSArray of two NSStrings that correspond to the real and section values for the entry. For example:

/* Sets sList to an array containing "10" and "AnySetup". */

NSArray *sList = [printer stringListForKey:@"Resolution"

    inTable:@"PPDOrderDependency"]

Retrieving Values from the UIConstraints Table

NSPrinter treats entries that have a *UIConstraint main keyword specially. Such entries take the following form (the bracketed elements are optional):

*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 *UIConstraint entries:

*UIConstraint: *Option3 None *PageSize Legal

*UIConstraint: *Option3 None *PageRegion Legal

These entries are stored in the PPDUIConstraints table. Retrieving a value from the PPDUIConstraints table is similar to retrieving a value from the PPDOrderDependency table: always use stringListForKey:inTable:. The key corresponds to mainKeyword1/optionKeyword1.

The NSArray returned by stringListForKey:inTable: contains 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. For example:

/* Sets sList to an array containing:

    "PageSize", "Legal", "PageRegion", and "Legal" */

NSArray *sList = [printer stringListForKey:@"Option3/None"

    inTable:@"PPDUIConstraints"]

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).

< Previous PageNext Page > Hide TOC