Extending media selection
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.
Media selection is the process of selecting a source of media for the printing process and selecting its destination after printing. (For example, specifying which paper tray and which output tray to use.) In PostScript-language terms, this means determining a number representing the source or destination, the number being the key of a dictionary in InputAttributes
or OutputAttributes
, which contains an abstract description of the source or destination.
The number is determined by the media matching process described in [RB2]. This is a complex algorithm, but in principle amounts to matching requests presented in the form of keys in the page device to attributes, represented as keys in the InputAttributes
and OutputAttributes
constituent dictionaries.
Some possible InputAttributes
keys are listed in [RB2]: PageSize
is always present (and treated as a somewhat special case; page sizes are discussed further in Page sizes and orientations); MediaWeight
, MediaColor
, and MediaType
may also be present. OutputAttributes
has no pre-defined keys. In both cases, however, additional keys can be used for matching as appropriate.
Consider a device that has a set of punch registers in different configurations. If each configuration is named, the appropriate one could be selected from a job by:
<< /PunchRegister (Press #3) >> setpagedevice
The page device could be set up in advance (say by a page feature in the GUI version) to offer the set of available punch registers in OutputAttributes
:
<<
/OutputAttributes <<
0 << /PunchRegister () >>
1 << /PunchRegister (Press #3) >>
...
5 << /PunchRegister (Press #5) >>
>>
>> setpagedevice
Provided /PunchRegister
has been made known as a media selection key as described below, this would select output attribute number 1 (in this example) and transmit this information to the %pagebuffer%
device, and in the GUI version on to the plugin, to allow the output device to do whatever is necessary to select that particular combination.
All new media selection keys are new page device keys too, so they must be added as extra page device keys as described in Adding custom page device keys. They must then be identified as media selection keys as well.
This is done by the key /ExtraMediaSelectionKeys
. Its value is a dictionary containing the keys required. The value of the keys is either the name /InputAttributes
or the name /OutputAttributes
according to whether the key contributes to the input or output media matching (the same key cannot be used for both).
For example, add /PunchRegister
as follows:
<<
/ExtraPageDeviceKeys <<
/PunchRegister ()
>>
/ExtraMediaSelectionKeys <<
/PunchRegister /OutputAttributes
>>
>> setpagedevice
Where the parameter is introduced in a plugin, this can be done automatically by marking the parameter with the SF_INPUTATTRIB
or SF_OUTPUTATTRIB
flag, as appropriate in the C data structure DICTSTRUCTION
.
The number of the dictionary selected for InputAttributes
is placed in the mediaSelect
field of the pageHeader
structure, and for OutputAttributes
in the outputAttributes
field (mediaSelect
is so named for historical reasons).
The file Sys/ExtraMediaSelectionKeys
is executed as the Harlequin RIP starts. It must leave on the operand stack key/value pairs (not a dictionary), where the keys are the names of the new media selection keys (which must also have been added in the file Sys/ExtraPageDeviceKeys
as described in Adding custom page device keys), and the values are either the name /InputAttributes
or the name /OutputAttributes
.