(v13) Export styles for HqnContour
This page applies to Harlequin v13.1r0 and later; both Harlequin Core and Harlequin MultiRIP.
This section describes how to create an HqnContour “Style” to enable export of spot separations to additional formats.
Export to PostScript and to HP-GL2 are provided with HqnContour, but in many cases an additional or proprietary format is required.
HqnContour styles are defined in files written in PostScript and stored in the SW/Usr/CustomContour folder. That folder must contain no other files. The HPGL2 and PostScript files in that directory may be reviewed as example implementations but should not be changed.
When executed, each file in the folder must return a dictionary on the operand stack and nothing else. The file may define and use its own temporary dictionary (as the HPGL2 file does), but that dictionary must be closed before the end of the file; no changes to the dictionary stack should persist outside of this file.
The definition of new styles added to HqnContour in CustomContour files is assumed to have been written and fully tested by a Harlequin OEM, and not to be derived or constructed on the fly. Validation of new styles is therefore quite lightweight and is not guaranteed to catch all issues at the time the file is executed, or to provide detailed error reports about issues encountered at run time. We highly recommend use of tools such as the long error handler during development and early formal test.
The dictionary returned must contain the key /Styles, with a value which is itself a dictionary.
Each entry within the Styles dictionary defines one or more export style. We do not recommend defining multiple styles in a single file unless they are sufficiently closely related that they can then share static data or procedures.
Each key in the Styles dictionary defines the name by which this style is known, and therefore what the value of the Style key in an Intercepts object must be in a call to InitContour to use this style.
Each value within the Styles dictionary must also be a dictionary, containing the following entries:
Key | Value |
| (Required for v12 and earlier, optional from v12.0r1; dictionary). If additional configuration parameters are required for this style they should be defined within this dictionary. See Style Options below. |
| (string). This entry defines the default file extension to be used when creating output files following this style. Required if |
| (Optional, procedure). If this procedure is provided it will be executed as part of the call to InitContour. Use this for setting global state, if necessary. |
Comment | (Optional, procedure). The procedure is called when HqnContour wishes to write a comment to the output file. It must accept a mark and a sequence of objects on the operand stack that are to be written to the output file. All of these objects must be consumed by the procedure. See (v13) HqnContour file writing calls for more detail. If Comment is not defined, then no comments will be written out. |
| (Required, procedure). This procedure is called once at the first time a graphical element within a job triggers an export to this style. It’s also called at the start of each new output file if FilePerPage is true. No operands are provided, and the procedure must not leave items on the operand stack. |
| (Required, procedure). This procedure is called once at the start of every page in the incoming job that triggers an export through this style. No operands are provided, and the procedure must not leave items on the operand stack. |
| (Required, procedure). This procedure is called once at the end of every page in the incoming job that triggers an export through this style. No operands are provided, and the procedure must not leave items on the operand stack. |
| (Required, procedure). This procedure is called once immediately before each output file is closed. No operands are provided, and the procedure must not leave items on the operand stack. |
| (Required, procedure). This procedure is called once for every path to be exported. The path required has already been set as the current path in the graphics state. Procedures for moveto, lineto, curveto, and closepath are on the operand stack (see Operators, below). We strongly recommend that this procedure should therefore call pathforall and pass all work to those procedures, and may perform additional processing. The procedures on the operand stack when StyleExport is called are not the original procedures supplied in the Operators dictionary, but also include additional code from HqnContour itself. The OverCut, AccurateExtend, OffsetX, OffsetY, ExportResolution, and MaxDecFigs options are not applied if StyleExport does not call pathforall. If the StyleExport procedure does not call pathforall then it must pop the four procedures off the operand stack. |
Operators | (Required, dictionary). This dictionary must contain four procedures, with the keys moveto, lineto, curveto, and closepath. See PLRM3’s description of pathforall for more detail. These procedures should do whatever is required to export each segment of the path in turn. MaxDecFigs is applied to numbers before they are passed to the Operator procedures. All four of these procedures are required even if the StyleExport procedure does not call pathforall … but they may be empty. |
Style options
If additional options are required that are specific to a particular Style, they may be defined using the key StyleOptions in the Style definition. The value must be a dictionary, the keys of which are the options to be added. Please take care that any new options do not clash with existing HqnContour names; it can be useful to add the style name, or an abbreviated form of it, as a prefix on each name.
The sub-dictionaries within StyleOptions should contain the following keys:
| Required | (Required, boolean) True if this option must be included in all configurations using this style, false otherwise. |
| Validate | (Required, procedure) This procedure is called with the value from a configuration on top of the operand stack. It should validate that the value is appropriate and return true, if so. Otherwise it should return false. If false is returned, HqnContour triggers a configurationerror and halt the job, so it’s often useful to provide additional information in the Validate procedure explaining exactly what’s wrong. Alternatively, the Validate procedure can choose to trigger an error directly. |
| Default | (Required if Required is false) The default value to use if the value of the Required key is false and a configuration is submitted without including this option. |
Variables accessible to style procedures
When one of the procedures in a style dictionary is called, it may access all of the normal operators and variables accessible to a PostScript job. As an example, it may choose to report the current time and date by using daytime or localedaytime .
In addition, the following specialized variables are available. These must NOT be changed within the procedure, but treated as read-only.
Variable | Usage |
| All variables set with InitContour may be referenced by name. Thus, if your procedures need to know the export resolution requested, they might use ExportResolution. This includes all parameters added with StyleOptions. |
| (String) the version of the HqnContour procset in use. |
| (String)the value of the ID property within the Intercepts dictionary that was selected for the current call to this export style. If multiple entries in ContourNames output to the same OutputFile then the value of CurrentContour is accurate for each path in the StyleExport call. When read in other call-backs such as OpenJob it will represent the value for the first path being written to that output file. |
| (Name, either |
| The page of the job from which this contour is exported |
linewidth | (number or null) The stroke width in points to use for objects exported as strokes. Null unless WidthAction is |
dash | (Array or null) the dash pattern to use for objects exported as strokes. Null unless DashAction is |
| (Number or null) the dash offset to use for objects exported as strokes. Null unless DashAction is |
colorspace | (Array, name or null) the color space to use for exported objects. Null unless ColorAction is |
| (Array or null) array of color values to use for exported objects. The array contents must be extracted to the operand stack (for example, with aload) before calling setcolor. Null unless ColorAction is |
| (Array of two numbers) From Harlequin 12.1r0, the page size in default user units. This should be used in preference to simply reading PageSize from the page device because it is adjusted for Scaling and ExtraOrientation if |