TEXT

Syntax

1. text col|{numexpr}, row|{numexpr}, "text" | @name | $name | {expression} [,fontname] [,font fontcode|{expr} ] [,symset symset] [,size | size {sizeexpr}] [,bold] [,italic] [,underline] [,light] [,shade percent|{numexpr}] [,rotate angle] [,fixed | proportional | prop] [,color] [,rgb rrggbb] [,justification, cols|icols ncols|{numexpr} ,ccols endcol] [,wrap] [,fit] [,spacing spacing] [,weight w|weightname] [,style style|stylename]  [,nohpgl] [,link "url"|{urlexpr}] [,linkopt "urlopts"|{urloptexpr}]

2. text "text|!=text|~regexp|!~regexp[@left,top,right.bottom]", col|{numexpr}, row|{numexpr}, { "text" | @name | $name | {expression} } [,fontname] [,font fontcode | {expr}] [,symset symset] [,size | size {sizeexpr}] [,bold] [,italic] [,underline] [,light] [,shade percent|{numexpr}] [,rotate angle] [,fixed | proportional | prop] [,color] [,rgb rrggbb] [,justification] [,cols|icols ncols|{numexpr}, ccols endcol], [eraseoffset cols, erasecols cols] [,getoffset cols, getcols cols] [,wrap] [,fit] [,spacing spacing] [,weight w|weightname] [,style style|stylename] [,nohpgl] [,link "url"|{urlexpr}] [,linkopt "urlopts"|{urloptexpr}]

Description

The text indicated in quotes will be printed at the column and row indicated by col and row.  The column and row can be specified to 1/100 character.  The position specified becomes the baseline left edge for the first character. If used, numexpr is a Business Basic expression that generates a numeric value for the column, row, columns, or rows.

If text begins with "@", such as @company, then the substitution file is searched.  In the example above, if a line company=ABC Company was found, the text "ABC Company" is used.  The substitution file defaults to "subst", but may be specified on the command line with the "-s" option.

If text begins with "$", then the operating system environment is searched for the indicated variable and its value is used.  For example, $USER would use the value stored in the environment variable "USER".

If text should be a literal value that starts with @ or $, then use \@ or \$, respectively.

If braces surround text, then it is taken to be an expression to be evaluated after each page of input has been loaded and the prepage subroutine has been executed.  The expression can be any valid Business Basic statement that would appear on the right side of an assignment statement and produces a string data type result.  Some UnForm supplied functions and data can be useful, such as TEXT$[], which contains the text of the page in an array, and GET(col,row,length), a function that returns data from the TEXT$ array.  For example, {"Copy 2, generated on "+date(0)} would generate text similar to this: "Copy 2, generated on 03/31/99".  See the Programming Code Blocks chapter for more information about programming expressions.

If text contains line-feed characters (CHR(10) or $0A$), or the mnemonic character string "\n", then UnForm will break the text into multiple lines and space them according to the spacing value.  For example, if the point size is 12, and spacing is set to 1.5, then line spacing is set to 18 points.  The default spacing is calculated from the number of rows per page, so multi-line text data will match the vertical placement of single line text data.

If syntax 2 is used, then UnForm will search for occurrences of text or the regular expression regexpr.  In this case, col and row become 0-based offsets from each location where matches are found.  In addition, the erasecols cols and eraseoffset cols can be used to remove match text. The search for text or regexpr can be limited to a region on the page by adding a suffix in the format '@left,top,right,bottom'.  To use a literal "@" character in text or regexpr, it is necessary to specify "\@".

If the syntax "!=text" or "!~regexpr" is used, then the search is for positions NOT equal to the text or NOT matching the regular expression.  When using the NOT syntax, only one search is performed per line in the search region.

Font Names and Numbers

Fonts are identified by numbers, generally those assigned by HP for PCL5 output.  Internally, all font names are converted to font numbers, as UnForm's font architecture is based on PCL5 methods.  A name is mapped to a number in the [fonts] section of ufparam.txt.  For PCL5 output, this number is used to specify the font used for this text element.  For other output formats, the number is mapped to an appropriate font setting by using other sections of ufparam.txt:

•[psmap] maps numbers to Postscript built-in fonts, or to Type1 font file name in the "psfont" directory.

•[pdfmap] maps numbers to built-in PDF font names.

•[ttfont] maps numbers to TrueType font files, located by full path or in the ttfont directory.  Note UnForm will look in the psmap and pdfmap sections first for a given number, then look in ttfont.

There are three fonts that are universally available or readily mapped to a similar native font for all output formats.  Those names are Courier (the default), CGtimes, or Univers.  These fonts are standard on all PCL5 compatible printers and easily mapped to similar fonts in other environments, such as Times Roman and Helvetica in the Postscript and PDF worlds.

Alternately, a specific fontcode supported by your printer can be specified by its font number.  For example, if your printer supports Arial, specify "font 16602". If you supply a fontcode this way, there is no mapping of name to number, but the format-specific mapping still takes place in order to select a similar font appropriate for the output format.

Note if you need to customize ufparam.txt, you should first copy it to ufparam.txc and edit that file, to avoid losing edits when UnForm is updated.

Symbol Sets

symset can be any symbol set supported by your printer.  The default symbol set is "9J", using the Windows Latin 1 character set (similar to ISO-8859-1, but with some additional characters defined).  You can also specify symbol sets by name from the "ufparam.txt" file.  Only symbol set 9J is supported by the PDF and Postscript drivers.

To include non-printable characters, such as control codes or 8-bit characters from a specific symbol set, include the character's numeric (ASCII) value in angle brackets.  For example, to include a copyright symbol from the Desktop (7J) symbol set, use something like this:  "<165>2000 Synergetic Data Systems Inc.", or use an expression with the CHR(num) function or a hex literal, such as $80$ for character 128..

Point and Pitch Size

size is a numerical value that specifies the point size of a proportionally spaced font or the pitch size of a fixed font.  The values range from about 4 to 999.75 with a default of 12.  PCL printers generally round this value to the nearest or smallest ¼ point. Note that for proportional fonts, the larger the number, the larger the size printed. Fixed fonts, such as Courier, are the opposite.  If you specify the "fit" option, then the size value represents the largest acceptable size.  Size can be specified as an expression, if it is prefixed with the keyword "size".

Fit and Wrap Options

The "fit" option will scan text for line breaks and decrease the size value as necessary to ensure that all lines will fit in the number of specified ncols or through endcol.  The smallest point size that will be used is 4, and the largest pitch that will be used is 30.

The "wrap" option will scan text and insert line breaks as needed to ensure no line at the specified size will exceed the specified ncols.  If no spaces exist in word that exceeds the line width, UnForm will print the word in its entirety, exceeding the allocated space.

The "fit" and "wrap" options are mutually exclusive, and in either case, if no ncols or endcol value is specified with the "cols" option, then ncols defaults to the page width in columns minus column.

Attribute Styles

The attribute words "bold", "italic", "underline", and "light" will apply the indicated attribute(s) to the text.

Shading

percent indicates the percent gray to print the text, from 0 (white) to 100 (black).  The default is black.  Note that the gs command can be used to improve laser printer shading.

Rotation

The "rotate" option will cause the text to be rotated around the baseline left edge at the angle specified.  If the –nohpgl option is used while producing pcl laser output, then the angle must be 90, 180, or 270 degrees.  Any angle can be specified for other formats.

Fixed and Proportional Spacing

Specify "fixed" or "proportional" (or "prop") to override the default of fixed for Courier (or any fontcode below 4100), and proportional for all else.  For example, if a mono-spaced font, such as the MICR soft font, has a font code higher than 4100, then the "fixed" option is required in order to ensure the proper font is selected, rather than a default proportional font.  Proportional vs. fixed carries a very high priority when a printer chooses a font, and if the desired font is not specified with the correct spacing, a different font will be chosen by the printer.

Color

Color can be specified as "white", "cyan", "magenta", "yellow", "blue", "green", "red", or "black", or you can name an RGB value as a 6-character hex string with "rgb rrggbb", where rr is red (00-FF), gg is green (00-FF), and bb is blue (00-FF).

Justification

justification can be one of the following words:  "left", "center", "right", "decimal".  UnForm will remove leading and trailing spaces from the text and justify it within the column specification.  Decimal justification will use a "." character unless a "decimal=character" line is placed in the ufparam.txt file under the [defaults] section.

For justification, you must also specify ncols or endcol with the "cols", "icols", or "ccols" option, so that UnForm can determine the right edge of the justification region.

Weight and Style

Some laser printer fonts must be specified with given weight or style in order to be selected by the printer.  For example, the font Clarendon Condensed is only available if the condensed style is specified, by adding "style 4" or "condensed" to the font command.  Style and weight options and codes can be found in the ufparam.txt file.  Note that fonts are expressly designed for certain weights and styles, and simply specifying an unsupported value does not produce the desired result.  In fact, it may result in selection of a different font entirely.  Check your printer's documentation or control panel prints for supported fonts.

Get Text From Input Stream

If "getoffset" and "getcols" are specified in a syntax 2 command, then the value printed is taken from the data stream at the offset and length specified from each occurrence (any text value supplied is ignored).  Further, "eraseoffset" and "erasecols" can be used to remove any data stream text from the point of occurrence as well.

Barcode Note

The text command can be used to print a human-readable version of a barcode value, which can be useful in cases where the human readable value differs from the supplied value, such as UPC-E, or when a check digit value is needed.

Text in this syntax: "bcdsss|value" to print the human readable barcode value for symbology sss and barcode text value, "ck1sss|value" to print check digit 1, or "ck2sss|value" to print check digit 2.  See the barcode command for symbology values.

Special Symbol Fonts

There is a difference between PDF and laser output for special symbols.  In the laser printer environment, you need to select a symbol set and font that contains the special characters you want, but in the PDF environment, you need only select the font (font 4141 for Dingbat and 16686 for Symbol).  Once a symbol set or font is identified, use the appropriate decimal value of text to print the character you want. The easiest way to do this is with angle bracket notation in a literal, like "<182>", or with the CHR function in an expression, like {CHR(182)}.

On many LaserJet printers, the available symbol sets and fonts differ from those specified in UnForm's ufparam.txt file, and the only way to know for sure what is available is to do a font list print on the printer.  This should show you the proper symbol set and font number to use for your printer.

MICR Fonts

There are four standard MICR fonts available in all output formats.  To utilize these, specify a font name of micr, micrbold (or micrb10), micrlight (or micrl15), or micrnarrow (or micrn1), along with 'fixed, 8' to ensure proper sizing.  These fonts are default, bold, light, and narrow versions of the MICR fonts that are supplied with UnForm.  Use these MICR text commands lines in cases where the micr command can't be used, such as with deposit slips, unusual bank account numbers, or non-standard check sizes.

Postscript Type1 Fonts

All Postscript printers include a base set of fonts, including Courier, Times-Roman, and Helvetica.  The [psmap] section of ufparam.txt links font numbers to Postscript font names, and the most often used font numbers are mapped in the default ufparam.txt file.  The [psmap] section looks like this:

[psmap]                                                                    

# Maps pcl font numbers to postscript font names.  Each number is

# set to up to four font filenames for normal, bold, italic, and

# bold-italic fonts in order.  If a fontname.pfa or fontname.pfb

# file is present in the psfont directory, then it is downloaded when used.

# Such fonts must be Adobe Type1 fonts.

#

# psfont/<fontname>.afm files provide metrics.

4099=Courier,Courier-Bold,Courier-Oblique,Courier-BoldOblique

4101=Times-Roman,Times-Bold,Times-Italic,Times-BoldItalic

4102=Courier,Courier-Bold,Courier-Oblique,Courier-BoldOblique

4141=ZapfDingbats

In order to use custom Type1 fonts, follow these steps:

•Install the font’s .pfa or .pfb files, as well as the metric file (.afm) in the psfont directory.

•Assign a unique number to the fonts, using the same normal, bold, italic, and bold-italic sequence found in the standard font mapping, if the font provides these versions.

•Optionally map a font name to the number in the [fonts] section of ufparam.txt.

•Text or font commands can now specify the font by number (font n) or name.

TrueType Fonts and Unicode

TrueType fonts can be configured by assigning font numbers to font file names in the [ttmap] section of ufparam.txt, in a manner similar to the [psmap] section described above.  In the Windows environment, the system's Fonts directory is automatically searched as well as the ttfont directory under the UnForm server, so there is no need to define full paths to system fonts on Windows.

When using a TrueType font, text data must be in Unicode format, where each character is represented with two bytes rather than one.  Standard single-byte encodings therefore need to be converted to Unicode, by mapping the characters in the string to the proper double-byte characters in Unicode.  Most character sets use the same characters in the 0-127 character range, but vary in the 128-255 range.  Unicode can represent any of these characters with a specific 0-65535 value, allowing any character set to be represented in Unicode.  The tables for most PCL symbol sets as well as several common character sets are included with UnForm in its unicode directory, and UnForm provides internal and code block functions to perform mapping.  

Normally, UnForm will assume that the text data provided to the command is single-byte data, and it will internally map the text to a Unicode string based on the symbol set setting.  The default symbol set (9J) matches the ISO-8859-1 character set, so that is the default translation.

If you wish to specify Unicode directly, you can do so in a variety of ways.  You must add a "uc" or "unicode" option to the text command to indicate the text data is already in Unicode format.

•Use the touc(text$,charset$) function in an expression, which returns the Unicode version of text$, given that text$ is in the identified character set or symbol set.  For example, {touc("Total Sales","9J")}.

•Specify raw double-byte  sequences as hexadecimal in an expression, using $hex$ notation, such as {$00300039$}.

•Use the <xhex> syntax in literal text, such as "<x00300039>".

Turn Off HP/GL

In PCL output, some text

URL Links

The html5 driver supports the link and linkopt options, used to specify a URL hyperlink value, and HTML <a> tag options, respectively.

Examples:

text 10,2,"SOLD TO" prints the text SOLD TO at the indicated position.

text 120,3,$LOGNAME prints user's login name at column 120, line 3.

text 1.25,63.25,{"Printed on "+date(0)}, cgtimes, 6, italic would place a small (6 point), italic note about the date near the lower left corner of a page.

text "TOTAL:",-1,0,"Total:",cgtimes,12,bold,eraseoffset 0, erasecols 6 changes words TOTAL: to Total: in CGTimes, 12 point, after backing up 1 column from where TOTAL: is found.  It also erases the word TOTAL: to avoid overprinting.

text 67,21,"bcd125|00010000654",univers,12 will print the UPC-E human readable barcode value.

text 20,62,{terms$},cgtimes,10,cols 40,wrap,spacing 1 will print a paragraph of text contained in terms$ between column 20 and 59, in CGtimes 10 point text, word-wrapping as necessary, using a nominal line height matching the 10 point text.

text {pos("Item"=text$[20])},21,"Number",cgtimes,12 will print the word "Number" on line 21, in the same column where the word "Item" is found in line 20.

text 20.5,20,{mcut(10,20,12,40,"","y","y")},cgtimes,12,right will cut text from the data stream, at column 10, row 20, for 12 columns, 40 rows, retaining line breaks, and print it as a column of 40 rows at column 20.5, row 20.  The column will be printed in the font CGtimes, 12 point size, right justified.

text 1,60,{mcut(1,60,200,5,"","","")},univers,10,wrap,cols 60 will cut a large message block from the data stream, at column 1, row 60, for 200 columns, 5 rows, removing line breaks.  It will then print it at column 1, row 60, at 10 point size and word wrapping to make it fit within 60 columns.

text 10,1.5,"Sample Industrial",16,bold,helvetica,link "http://sample_indust.com", linkopt "target=_blank" will place a company title on the page and make it a hyperlink to a company website, to be opened in a new blank page, when producing HTML5 output.

Drivers: all.  PDF driver fonts map to Courier, Helvetica, or Times-Roman based on the [pdfmap] section if ufparam.txt, and support only symbol set 9J (ISO8859-1 with extensions). PS maps based on the [psmap] section in ufparam.txt.  Zebra fonts are limited in scalability, and the font codes are letters or numbers that identify internal font codes specified in the ZPL documentation.  Zebra shading is limited to 0% or 100%.  Zebra doesn't support colors or decimal justification, or wrap and fit options. Light and underline options are only supported by the pcl driver.