(v13) Adding custom page device keys

This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.

A custom page device key is usually added to control some feature of an output device from the PostScript language.

For example, most printers do not support duplex (double-sided printing). Therefore the Duplex key is not present in the supplied page device dictionary; if your printer does support it, add the standard key Duplex. Alternatively, your printer might support a feature for which there is no standard key; add one of your own. For example, some laser imagesetters allow operation using a double-facet prism. If single- or double-facet operation is selectable, you might have a key DoubleFacet that controls from the PostScript language whether it is used or not.

Another example: Consider a “printer” that is actually a fax machine. You might then want a key /PhoneNumber to tell the fax what number to dial. Ideally you would want the phone number to be specified by the application originating the PostScript-language job. One way to do this is to adopt a convention for the document so that its name contains the phone number: you could analyze the name by parsing the comments at the top of the job (see (v13) Comment parsing ) and generate an appropriate call to setpagedevice. Alternatively you could provide a set of encapsulated PostScript-language files containing the appropriate code for setting the phone number, which users could import into their documents.

You can add and remove keys dynamically; when used in conjunction with a plugin, some of this mechanism is automatic (see below).

The RIP has a page device key called /ExtraPageDeviceKeys. Its value is a dictionary containing keys to be added and their default values. Like InputAttributes, Policies , and so on, the effect is cumulative: a second set of extra keys adds to the first rather than replacing it. However, because it is part of the page device, it is subject to gsave and grestore in the usual way.

For example, you could add the key /PhoneNumber as follows:

            <<
            /ExtraPageDeviceKeys <<
            /PhoneNumber () % default: empty string
            >>
            >> setpagedevice

A later call to setpagedevice can then make use of it:

<< /PhoneNumber (+44 ) >> setpagedevice

Any keys introduced by ExtraPageDeviceKeys are automatically passed on to the %pagebuffer% device just before each page is output, using the setdevparams operator. Implementing setdevparams means that only numbers, names, strings and Booleans are acceptable as extra page device keys added in this way.

In the GUI version, the PostScript-language part of this process is largely automatic. Extra page device keys are nearly always specified in a plugin. This allows the parameter to be set from the PostScript language, or set by a dialog (which is, in fact, an editor for the PostScript-language fragment which sets the parameter); the value to be transmitted from the GUI version’s implementation of the %pagebuffer% device to the plugin at the time the page is output. In this case, the extra key is added automatically; when a device is selected in the Page Setup dialog, PostScript-language code is generated for an ExtraPageDeviceKeys dictionary containing all the keys given by the plugin in response to the D_GETSTIOTEMPL selector. The values for these keys are determined by the defaults provided in response to the D_GETSTIODATA selector, or as subsequently modified by the user in the Configure Device dialog. The PostScript generated is stored in the file Config/Page Setup. The Configure Device dialog does not need for all the parameters to be available: if they are not, they are only modifiable from the PostScript language. The purpose of this section is to show how extra page device keys are handled in PostScript, the plugin programming details are given in [HQPLUGIN], chapter 4. The page device can only be extended when the Harlequin RIP is started; it is not possible to pass the values directly through to a plugin. This means that the method is most appropriate to core-RIP implementations. (However, in GUI versions, in single modes you can write the values to a file that the plugin can then read, or in simple combinations, to use media selection and OutputAttributes: see below).

New keys are added in a file Sys/ExtraPageDeviceKeys which is executed as the Harlequin RIP starts up. After the file is executed the stack should contain a set of alternating key/value pairs (note: not a dictionary). Typically, this means the required keys and default values are placed in the file verbatim, though since the file is being executed it is possible to use expressions there too. The contents of the Sys/ExtraPageDeviceKeys file in version 3.2 are analogous to the contents of the ExtraPageDeviceKeys dictionary in version 3.3. The file method is still available in version 3.3 in addition to the dynamic method.

Keys added using the Sys/ExtraPageDeviceKeys file are not automatically passed on to the %pagebuffer% device, unlike those added dynamically in version 3.3. However, the page device key PageBufferSetup is a hook that you can use to process parameters in whatever way is required, including passing them on to the %pagebuffer% device. See (v13) PageBufferSetup procedures for details.

If the static mechanism introduces a new key that already exists in the current page device, then the new value replaces its current value. This provides a method for defaults for built-in keys to be replaced on start-up without the side-effects of executing setpagedevice.

If the dynamic mechanism introduces a new key that already exists in the current page device, then its value is ignored.