Writing GDI Print Directives
Updated September 2024
Here are some rules and guidelines for dealing with A-Shell's GDI print directives.
| • | To embed GDI print directives in your print file, they must begin in column one with // (two forward slashes) followed by the name of the directive and its parameters. |
| • | A comma must immediately follow the directive, and commas must separate all parameters, with no intervening spaces. |
| • | String arguments may be quoted with quote marks "like this" to make sure punctuation characters within the string itself—especially embedded commas—are not confused with the syntax of the directive. However, quoting is optional for the last parameter. This applies mainly to the various //TEXTxxx directives. |
| • | The maximum length of a directive is 16K. (This applies mainly to the //TEXTxxx directives.) |
| • | In the case of //TEXTxxx directives, where the last parameter is the text to output, you may end the text with a backslash to indicate that the next line is to be concatenated to it, assuming the next line does not start with a forward slash. This might be useful to avoid very long lines in your source text. To include a literal backslash as the last character of a text argument, either append a space to it or quote the entire text argument. |
| • | Embedded GDI directives are only processed if PASSTHROUGH=OFF. |
| • | Comments, which are ignored for printing purposes, are indicated by beginning a line with "//;", two slashes followed by a semicolon, starting in column 1. This is useful for documenting your other GDI print directives which might otherwise be less than obvious when examining the file in a text editor. Note that comments may not appear elsewhere, like on the end of the line after an exclamation point as in ASB. |
| • | To change font or issue some other GDI print directive in the middle of a line of output, append a backslash to the end of the first part(s) of the line to hold the position so that the next line of output starts where the previous one left off. See the example in the next section for further clarification. Note that this only works for plain text, not for text output via //TEXTxxx directives, which do not affect the 'cursor' position in any case. If you want to change font in the middle of a string of text output by a //TEXTxxx directive, you'll have to split it into two //TEXTxxx directives, separated by the font change directive. |
| • | Some printer/printing characteristics, such as paper orientation (landscape or portrait), can be changed only with printer initialization file commands and not with GDI commands. |
| • | While most GDI printing operations can be performed by embedding GDI Print Directives into the print file, there are some printer init commands that may affect or work in conjunction with GDI Print Directives. Specifically, the commands XOFFSET, YOFFSET, XORIGIN, YORIGIN control the "fine" positioning of the print on the paper. |
| • | Also note that the printer init parameters PITCH, LPP, CPP, FONT, FONTHEIGHT and FONTWIDTH may affect the way plain text is rendered, even when it is found in a print file otherwise full of GDI print directives. |
| • | Neither the GDI directives nor their associated parameters are case sensitive. |
Sample GDI Printfile
This example of a GDI printfile illustrates a few important things such as comments, embedded GDI directives, and the use of the backslash line terminator to allow a change of font in the middle of a line.
//; This is an example of a printfile using embedded GDI directives.
//; Any line starting with //; is a comment and is ignored during printing
//; Set units to 1/100 of an inch
//SETMAPMODE,LOENGLISH
//; Establish font (otherwise we'll get the default or one set by printer init
//SETFONT,120,Times New Roman,0,16
Lines like this are printed using the current font,
and advance down the page in the normal way.
//TEXTOUT,25,45,"Text can also be output with //TEXTOUT at specific positions"
//RECTANGLE,40,75,240,100,1
//TEXTCENTER,40,75,240,100,"This text is in a shaded box"
//;TEXTxxx does not move internal cursor, but MOVETO does
//MOVETO,0,110
//;Lines ending in backslash leave cursor in position at end of line
This line changes to \
//SETFONT,120,Times New Roman,0,16,0,3
Underlined Italic \
//SETFONT,120,Times New Roman,0,16,0,0
in the middle of the line.
The above sample would print as shown below. Note the use of the backslash to break the last line into parts so that the font could be changed in the middle of the line.
History
2024 September, A-Shell 7.0.1762: Add support for special handling of trailing backslash in //TEXTxxx directives. Previously it was only recognized as a special character in plain text outside of GDI directives.
