This is NSPrinter.rtf in view mode; [Download] [Up]
paperh18648 margl-907 margr0 margt0 margb0 fi0 ri0 ql sb0 f1 fs24 Copyright f3 'e3f1 1994 by NeXT Computer, Inc. All Rights Reserved.
s4 li100 fi0 ri1007 ql f0 b fs36 fs100
fs36 NSPrinter
pard s11 li2872 fi-2771 ri1007 ql tx2872 f1 b0 fs28 fs48
fs28 f0 b fs24 Inherits From:tab b0 fs28 f1 NSObject
fs20
fs28 s6 f0 b fs24 Conforms To:tab b0 fs28 f1 NSCoding, NSCopying
fi0 NSObject (NSObject)
fs20
fs28 s7 fi-2771 f0 b fs24 Declared In:tab b0 fs28 f1 AppKit/NSPrinter.h
fs20
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs28 fs20
fs28 Class Description
fs14
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs2
fs28 An NSPrinter object describes a printer'27s 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.
fs16
fs28 There are two ways to create an NSPrinter:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab To create an abstract object that provides information about a type of printer rather than an object that represents an actual printer device, use the b printerWithType:b0 class method, passing a printer type (an NSString) as the argument. The b printerTypesb0 class method provides a list of the printer types recognized by the computer. Printer types are described in files written in PostScript Printer Description (PPD) format. The location of these files is platform dependent.
fs16
fs28 'b7tab To create or find an NSPrinter that corresponds to an actual printer device, use the b printerWithName:b0 class method, passing the name of a printer. The way you find out what the available printer names are depends on the platforms you are using.
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 Once you have an NSPrinter, there'27s only one thing you can do with it: Retrieve information regarding the type of printer or regarding the actual printer the object represents. You can'27t change the information in an NSPrinter, nor can you use an NSPrinter to initiate or control a printing job.
fs16
fs28 When you create an NSPrinter object, the object reads the file that corresponds to the type of printer 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 b stringForKey:inTable:b0 and b stringListForKey:inTable:b0 , as explained later. Commonly needed items, such as whether a printer is color or the size of the page on which it prints, are available through more direct methods (methods such as b isColorb0 and b pageSizeForPaper:b0 ).
fs16
fs28 pard s12 li477 fi0 ri1007 ql f0 b fs24 Note: b0 fs28 f1 To understand what the NSPrinter tables contain, you need to be acquainted with the PPD file format. This is described in i PostScript Printer Description File Format Specification, version 4.0i0 , 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.
fs14
fs28 s15 f0 b fs24 fs6
fs24 PPD Format
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 A PPD file statement, or i entryi0 , associates a i valuei0 with a i main keywordi0 :
fs16
fs28 pard s2 li1231 fi0 ri1007 ql tx2872 tx3250 tx3642 *i mainKeywordi0 :b b0 i value
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 i0 The asterisk is literal; it indicates the beginning of a new entry.
fs16
fs28 For example:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 *ModelName: "MMimeo Machine"
*3dDevice: False
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 A main keyword can be qualified by an i option keywordi0 :
fs16
fs28 pard s2 li1231 fi0 ri1007 ql tx2872 tx3250 tx3642 *i mainKeyword optionKeywordi0 :b b0 i value
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 i0 For example:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 *PaperDensity Letter: "0.1"
*PaperDensity Legal: "0.2"
*PaperDensity A4: "0.3"
*PaperDensity B5: "0.4"
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 In addition, any number of entries may have the same main keyword with no option keyword yet give different values:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 *InkName: ProcessBlack/Process Black
*InkName: CustomColor/Custom Color
*InkName: ProcessCyan/Process Cyan
*InkName: ProcessMagenta/Process Magenta
*InkName: ProcessYellow/Process Yellow
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 Option keywords and values can sport i translation stringsi0 . 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:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 *Resolution 300dpi/300 dpi: " i ...i0 "
fi0 *InkName: ProcessBlack/Process Black
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 In the first example, the b 300dpib0 option would be presented in a user interface as 'aa300 dpi.'ba The second example assigns the string 'aaProcess Black'ba as the translation string for the b ProcessBlackb0 value.
fs16
fs28 NSPrinter treats entries that have an b *OrderDependencyb0 or b *UIConstraintb0 main keyword specially. Such entries take the following forms (the bracketed elements are optional):
fs16
fs28 pard s2 li1231 fi0 ri1007 ql tx2872 tx3250 tx3642 *OrderDependency: i real section mainKeyword i0 [i optionKeywordi0 ]i
fi0 i0 *UIConstraint:i mainKeyword1 i0 [i optionKeyword1i0 ]i mainKeyword2 i0 [i optionKeyword2i0 ]
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 There may be more than one UIConstraint entry with the same i mainKeyword1i0 or i mainKeyword1/optionKeyword1i0 value. Below are some examples of *b OrderDependency b0 and b *UIConstraint b0 entries:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 *OrderDependency: 10 AnySetup *Resolution
fi0 *UIConstraint: *Option3 None *PageSize Legal
fi0 *UIConstraint: *Option3 None *PageRegion Legal
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 Explaining these entries is beyond the scope of this documentation; however, it'27s important to note their forms in order to understand how they'27re represented in the NSPrinter tables.
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 NSPrinter Tables
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 NSPrinter defines five key-value tables to store PPD information. The tables are identified by the names given below:
fs16
fs28 pard s19 li854 fi0 ri1007 ql tx4509 tx10180 f0 b fs24 Nametab Contents
fs6
fs24 pard s18 li4509 fi-3655 ri1007 ql tx4509 tx10432 f1 b0 fs28 fs10
fs28 fi-3655 PPDtab General information about a printer type. This table contains the values for all entries in a PPD filei i0 except those with the b *OrderDependencyb0 and b *UIConstraintb0 main keywords. The values in this table don'27t include the translation strings.
fs16
fs28 fi-3655 fi-3655 PPDOptionTranslationtab Option keyword translation strings.
fs16
fs28 fi-3655 fi-3655 PPDArgumentTranslationtab Value translation strings.
fs16
fs28 fi-3655 fi-3655 PPDOrderDependencytab b *OrderDependencyb0 values.
fs16
fs28 fi-3655 fi-3655 PPDUIConstraintstab b *UIConstraintb0 values.
fs16
fs28 fi-3655 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 There are two principle methods for retrieving data from the NSPrinter tables:
fs16
fs28 pard s3 li1231 fi-376 ri1007 ql tx1231 tx2872 tx3250 'b7tab b stringForKey:inTable:b0 returns the value for the first occurrence of a given key in the given table.
fs16
fs28 'b7tab b stringListForKey:inTable:b0 returns an array of values, one for each occurrence of the key.
fs16
fs28 pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 For both methods, the first argument is an NSString that names a key'd0which 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 look in. The values that are returned by these methods, whether singular or in an array, are always NSStrings, even if the value wasn'27t a quoted string in the PPD file.
fs16
fs28 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 b booleanForKey:inTable: b0 and b intForKey:inTable:b0 ,b b0 that retrieve single values and coerce them, if possible, into particular data types. The coercion doesn'27t affect the data that'27s stored in the table (it remains in ASCII format).
fs16
fs28 To check the integrity of a table, use the b isKey:forTable:b0 and b statusForTable:b0 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).
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Retrieving Values from the PPD Table
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Keys for the PPD table are strings that name a main keyword or main keyword/option keyword pairing (formatted as 'aai mainKeywordi0 /i optionKeywordi0 'ba). In both cases, you exclude the main keyword asterisk. The following example creates an NSPrinter and invokes b stringForKey:inTable:b0 to retrieve the value for an un-optioned main keyword:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 /* Create an NSPrinter object for a printer type. */
fi0 NSPrinter *prType = [NSPrinter
fi0 printerWithType:@"My_Mimeo_Machine"]
fi0
fi0 NSString *sValue = [prType stringForKey:@"3dDevice" inTable:@"PPD"];
fi0 /* sValue is "False". */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 To retrieve the value for a main keyword/option keyword pair, pass the keywords formatted as 'aai mainKeywordi0 /i optionKeywordi0 'ba:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSString *sValue = [prType stringForKey:@"PaperDensity/A4"
fi0 inTable:@"PPD"];
fi0 /* sValue is "0.3". */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 b stringForKey:inTable:b0 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 the empty string. If it doesn'27t have options, it returns the value of the first occurrence of the main keyword:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSString *sValue = [prType stringForKey:@"PaperDensity" inTable:@"PPD"];
fi0 /* sValue is empty string*/
fi0
fi0 NSString *sValue = [prType stringForKey:@"InkName" inTable:@"PPD"];
fi0 /* sValue is "ProcessBlack" */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 To retrieve the values for all occurrences of an un-optioned main keyword, use the b stringListForKey:inTable:b0 method:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSArray *sList = [prType stringListForKey:@"InkName" inTable:@"PPD"];
fi0 /* [slist objectAtIndex:0] is "ProcessBlack",
fi0 [slist objectAtIndex:1] is "CustomColor",
fi0 [slist objectAtIndex:2] is "ProcessCyan", and so on. */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 In addition, b stringListForKey:inTable:b0 can be used to retrieve all the options for a main keyword (given that the main keyword has options):
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSArray *sList = [prType stringListForKey:@"PaperDensity"
fi0 inTable:@"PPD"];
fi0 /* [slist objectAtIndex:0] is "Letter",
fi0 [slist objectAtIndex:1] is "Legal",
fi0 [slist objectAtIndex:2] is "A4", and so on. */
s15 li477 fi0 f0 b fs24 fs20
fs24 Retrieving Values from the Option and Argument Translation Tables
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 A key to a translation table is like that to the PPD table: It'27s 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:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSString *sValue = [prType stringForKey:@"Resolution/300dpi"
fi0 inTable:@"PPDOptionTranslation"];
fi0 /* sValue is "300 dpi". */
fi0
fi0 NSArray *sList = [prType stringListForKey:@"InkName"
fi0 inTable:@"PPDArgumentTranslation"];
fi0 /* [slist objectAtIndex:0] is "Process Black",
fi0 [slist objectAtIndex:1] is "Custom Color",
fi0 [slist objectAtIndex:2] is "Process Cyan", and so on. */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 As with the PPD table, requesting an NSArray of NSStrings for an un-optioned main keyword returns the keyword'27s options (if it has any).
fs16
fs28 pard s15 li477 fi0 ri1007 ql f0 b fs24 fs4
fs24 Retrieving Values from the Order Dependency Table
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 As mentioned earlier, an order dependency entry takes this form:
fs16
fs28 tab *OrderDependency: i real section mainKeyword i0 [i optionKeywordi0 ]i
fs16
fs28 i0 These entries are stored in the PPDOrderDependency table. To retrieve a value from this table, always use b stringListForKey:inTable:b0 . The value passed as the key is, again, a main keyword or main keyword/option keyword pair; however, these values correspond to the i mainKeywordi0 and i optionKeywordi0 parts of an order dependency entry'27s value. As with the other tables, the main keyword'27s asterisk is excluded. The method returns an NSArray of two NSStrings that correspond to the i reali0 and i sectioni0 values for the entry. For example:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSArray *sList = [prType stringListForKey:@"Resolution"
fi0 inTable:@"PPDOrderDependency"]
fi0 /* [slist objectAtIndex:0] = "10", [slist objectAtIndex:1] = "AnySetup" */
s15 li477 fi0 f0 b fs24 fs20
fs24 Retrieving Values from the UIConstraints Table
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 b0 fs28 fs16
fs28 Retrieving a value from the PPDUIConstraints table is similar to retrieving a value from the PPDOrderDependency table: always use b stringListForKey:inTable:b0 and the key corresponds to elements in the entry'27s value. Given the following form (as described earlier), the key corresponds to i mainKeyword1i0 /i optionKeyword1i0 :
fs16
fs28 tab *UIConstraint:i mainKeyword1 i0 [i optionKeyword1i0 ]i mainKeyword2 i0 [i optionKeyword2i0 ]
fs16
fs28 The NSArray that'27s returned by b stringListForKey:inTable:b0 contains thei mainKeyword2i0 and i optionKeyword2i0 values (with the keywords stored as separate elements in the NSArray) for every b *UIConstraintsb0 entry that has the given i mainKeyword1i0 /i optionKeyword1i0 value. For example:
fs16
fs28 pard s5 li1231 fi0 ri1007 ql f2 fs20 NSArray *sList = [prType stringListForKey:@"Option3/None"
fi0 inTable:@"PPDUIConstraints"]
fi0 /* [slist objectAtIndex:0] = "PageSize", [slist objectAtIndex:1] = "Legal",
fi0 [slist objectAtIndex:2] = "PageRegion", [slist objectAtIndex:3] = "Legal" */
pard s1 li477 fi0 ri1007 ql tx2494 tx2872 tx3250 f1 fs28 fs16
fs28 Note that the main keywords that are returned in the NSArray don'27t have asterisks. Also, the NSArray that'27s returned always alternates main and option keywords. If a particular main keyword doesn'27t have an option associated with it, the string for the option will be empty (but the entry in the NSArray for the option i willi0 exist).
fs16
fs28 pard s16 li100 fi0 ri1007 ql f0 b fs24
fs28 Finding an NSPrinter
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 + (NSPrinter *)b printerWithName:b0 (NSString *)i namei0 tab Returns the NSPrinter with the given name.
fi-6552 fs16
fs28 fi-6552 + (NSPrinter *)b printerWithType:b0 (NSString *)i typei0 tab Returns an NSPrinter object for the given printer type.
fi-6552 fs16
fs28 fi-6552 + (NSArray *)b printerTypesb0 tab Returns the recognized printer types.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Printer Attributes
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (NSString *)b hostb0 tab Returns the name of the printer'27s host computer.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b nameb0 tab Returns the printer'27s name.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b noteb0 tab Returns the note associated with the printer.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b typeb0 tab Returns the name of the printer'27s type.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Retrieving Specific Information
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b acceptsBinaryb0 tab Returns YES if the printer accepts binary PostScript.
fi-6552 fs16
fs28 fi-6552 {f3 -} (NSRect)b imageRectForPaper:b0 (NSString *)i paperName
s9 li7030 fi-6553 fi-5796 i0 tab Returns the printing rectangle for the named paper type. Possible values for i paperNamei0 are contained in the printer'27s PPD file. Typical values are Letter and Legal.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSSize)b pageSizeForPaper:b0 (NSString *)i paperName
s9 li7030 fi-6553 fi-5796 i0 tab Returns the size of the page for the named paper type.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isColorb0 tab Returns whether the printer can print color.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isFontAvailable:b0 (NSString *)i fontNamei0 tab Returns whether the named font is available to the printer.
fi-6552 fs16
fs28 fi-6552 {f3 -} (int)b languageLevelb0 tab Returns the PostScript Language Level recognized by the printer.
fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isOutputStackInReverseOrderb0 tab Returns whether the printer outputs pages in reverse page order.
pard s16 li100 fi0 ri1007 ql f0 b fs48
fs28 Querying the NSPrinter Tables
fs14
fs28 pard s8 li7029 fi-6552 ri1007 ql tx6652 tx7030 f1 b0 fs2
fs28 fi-6552 {f3 -} (BOOL)b booleanForKey:b0 (NSString *)i keyi0 tab Returns a boolean value associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSDictionary *)b deviceDescriptionb0 tab Returns a dictionary of keys and values describing the device. See NSGraphics.h for possible keys.
fi-6552 fs16
fs28 fi-6552 {f3 -} (float)b floatForKey:b0 (NSString *)i keyi0 tab Returns a floating-point value associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i table
s8 li7029 fi-5794 fi-6552 i0 fs16
fs28 fi-6552 {f3 -} (int)b intForKey:b0 (NSString *)i keyi0 tab Returns an integer value associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i table
s8 li7029 fi-5794 fi-6552 i0 fs16
fs28 fi-6552 {f3 -} (NSRect)b rectForKey:b0 (NSString *)i keyi0 tab Returns rectangle associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSSize)b sizeForKey:b0 (NSString *)i keyi0 tab Returns the size associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSString *)b stringForKey:b0 (NSString *)i keyi0 tab Returns a string associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSArray *)b stringListForKey:b0 (NSString *)i keyi0 tab Returns an array of strings associated with i keyi0 in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (NSPrinterTableStatus)b statusForTable:b0 (NSString *)i tablei0 tab
s9 li7030 fi-6553 fi-5796 tab Returns the status (NSPrinterTableOK, NSPrinterTableNotFound, NSPrinterTableError) of the given table.
s8 li7029 fi-5794 fi-6552 fs16
fs28 fi-6552 {f3 -} (BOOL)b isKey:b0 (NSString *)i keyi0 tab Returns whether i keyi0 is a key in i tablei0 .
s9 li7030 fi-6553 fi-5796 b inTable:b0 (NSString *)i tablei0 tab
}These are the contents of the former NiCE NeXT User Group NeXTSTEP/OpenStep software archive, currently hosted by Netfuture.ch.