Updated April 2020; see History
//SETOPTION, option {,boolean}
SETOPTION selectively enables various options affecting GDI printing.
Parameters
embedded-entity-references
enables the interpretation of the symbol entities via their UNICODE values. The default is to treat them as plain text, thus eliminating the remote chance that a semi-random string of data/text will be misinterpreted as containing embedded symbol entities.
fontsize-char
determines method of calculating font size: true for character size, false for cell size. See further discussion in Fontsize-Char topic.
ignore-escape-errors
causes A-Shell to ignore errors occurring during the processing of the ESCAPE directive. Normally, when such errors occur, the GDI directive itself is printed to the target device, to make it easier to spot the fact that the directive contained an error. But in the case of ESCAPE, if you redirect the output to a device incompatible with the one for which the ESCAPE sequence was intended, an error may be "normal", hence you wouldn't want it to appear in the output. For example, if you use ESCAPE to embed some special PCL command into a document, but then send it to a PDF generator instead, you would probably want the fact that the PDF driver didn't support the ESCAPE to be ignored.
no-auto-page-breaks
Turns off automatic page break logic. This is handy in single-page GDI files that contain a mixture of drawing commands and many lines of plain text. The same effect has previously been achievable by inserting a MOVETO directive anywhere on the page, but this is more self-documenting. Note that as with all other SETOPTION attributes, the initial setting is FALSE, while the default {,boolean} parameter is TRUE. So typically the directive is only used to enable the attribute (making the {,boolean} unnecessary to specify).
no-auto-margins
When specified, this option disables the automatic 1/4" margin adjustment applied by the SETFONT directive when calculating the character width from a negative width parameter—i.e. from the number of characters to fit in the width of the page. This automatic adjustment was added years ago in conjunction with the APEX auto-margin adjustement, on the theory that even if the printer doesn't report a physical margin, at some point you may want to print to paper, where the margin would most likely need to be applied. So it seems better to be calculate the font width so as to be compatible with physical printing.
There are situations however where this doesn't make sense and in fact causes problems. One would be when using SETFONT with a negative width parameter to come up with an appropriate font size to match up to a form generated from an image scaled to the page. In that case, you probably want the width basis used for the font calculation to be the same as used for the image scaling, i.e. without any automatic margin offsets.
textrect-conservative-vert
Normal TEXTRECTANGLE logic (syntax one) is such that it will start a new line of text as long as the starting point is above the bottom of the rectangle. But in the typical alignment, the starting point is at the upper left corner of the text cell, allowing the last line of text to straddle the bottom of the rectangle. Developers may have previously (before textrect-conservative-vert was available) worked around this problem by drawing the border of the RECTANGLE below the specified bottom of the TEXTRECTANGLE.
This parameter, textrect-conservative-vert, provides a cleaner approach, assuming you don't want to switch all your text alignment to use TA_BOTTOM. It effectively moves the threshold point (used to decide whether another line will fit in the rectangle) up by the current vertical line spacing. This way, you can use the same coordinates for the TEXTRECTANGLE as for the RECTANGLE.
textrect-nowrap
This parameter allows you to disable wrap within TEXTRECTANGLE (syntax one). It may be useful in situations where you have multiple lines of text that already have hard line breaks and you would prefer to truncate the lines that are too long rather than cause a wrap and end up losing some of the text at the bottom. Note that this effect has long been available with TEXTRECTANGLE syntax two, simply by omitting the TRF_WORDBREAK option.
UTF8
When specified, the remainder of the file is considered to be in UTF8 encoding, which is compatible with 7 bit ASCII characters (0-127), but interprets bytes with the 8th bit set as a lead-in to a multi-byte sequence supporting the entire range of UNICODE code points. When printing files which start with the special 3 byte sequence EF EB BF, UTF8 mode is activated automatically. This is a semi-standard protocol for identifying UTF8-encoded text files, favored by Microsoft.
Example
//SETOPTION,EMBEDDED-ENTITY-REFERENCES
Symbol: Ω Code: \
//SETOPTION,EMBEDDED-ENTITY-REFERENCES,0
Ω
Comments
The booleans (default = TRUE) can be:
FALSE: FALSE, F, 0, N, OFF
TRUE: TRUE, T, 1, Y, ON (or anything else)
Since the options are all initialized to FALSE at the start of each print request, you must specify the enable the options of interest at the start of each print file. But since the default Boolean switch is TRUE, you generally don't need to specify that argument, except when you need to turn an option back off again, after having first enabled it earlier in same file.
Note: All parts of this directive are case insensitive.
History
2020 April, A-Shell 6.5.1678: Add no-auto-margins
2018 November, A-Shell 6.5.1651: Add fontsize-char
2012 November, A-Shell 6.0.1365: Add UTF8
2012 October, A-Shell 6.0.1261: Add textrect-conservative-vert and textrect-nowrap
2012 August, A-Shell 6.0.1154: Add no-auto-page-breaks parameter
2012 June, A-Shell 6.0.1152: SETOPTION added to A-Shell
