Updated June 2014; see History

Syntax One

//TEXTRECTANGLE, left, top, right, bottom

bla bla bla bla bla bla bla bling

bla bla bla bla bla bla

//TEXTRECTANGLE

TEXTRECTANGLE is similar to the TEXTINDENT command, both in what it is used for and also in the fact that it consists of a starting and ending command (the ending command has no arguments), with any number of lines of text in between the two.

TEXTRECTANGLE formats the text to fit within the rectangular coordinates provided, applying word wrap to the lines as needed. Note that any existing CRLF line terminators will be respected; in the example above, the word "bling" will mark the end of a line, no matter how the rest of it formats.

If the text does not all fit in the rectangle, the last word will be printed with an ellipsis (...) following it. See MX_GDICALC for information on calculating in advance how much text will fit.

TEXTRECTANGLE supports rotated multi-line text, with autowrap. Support is limited; it doesn't clip to the rectangle if there are too many lines to fit.

TEXTRECTANGLE also supports embedded entity references. In earlier versions of A-Shell, these were only processed by TEXTOUT and for raw text.

Some text rotation options are also supported; see History, below.

See MMOGDI in EXLIB:[908,37] for an example.

Syntax Two

//TEXTRECTANGLE, left, top, right, bottom, flags, text

This variation (identified by the six parameters) is both simpler to use than the traditional multi-part TEXTRECTANGLE sequence, and offers some additional features such as multi-line horizontal and vertical centering.

flags may be any sensible combination of the following:

As with other GDI printer directives, the flags can be specified as a decimal value, hex value, or using the symbol names.

text may be any string of up to 16384 characters. It may include "^M" symbol(s) to indicate hard CRLF(s).

History

2014 June, A-Shell 1387:  Single-line TEXTRECTANGLE now supports character wrap in the 90, 180, -90 and -180 rotations. Previously only word wrap was supported and if any lines were too long, the output was way out of position.

2013 December, A-Shell 1370:  An unmatched leading quote is now treated as a literal character. Previously it was stripped.

2012 November, A-Shell 6.0.1263:  TEXTRECTANGLE now supports rotated multi-line text, with autowrap; that support is limited, it doesn't clip to the rectangle if there are too many lines to fit. TEXTRECTANGLE also supports embedded entity references; previously these were only processed by TEXTOUT and for raw text.

2012 October, A-Shell 6.0.1261:

•   TEXTRECTANGLE (syntax one, with multiple lines) now adds an ellipsis "..." to the right of the last line in the case where the last visible line is not truncated, but there are additional lines of text (with hard line breaks) that did not fit into the box.

•   New SETOPTION flag "TEXTRECT-CONSERVATIVE-VERT" improves vertical spacing control.

•   New SETOPTION flag "TEXTRECT-NOWRAP" disables wrap within TEXTRECTANGLE. This may be useful in situations where you have multiple lines of text that already have hard line breaks and 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.

2011 October, A-Shell 5.1.1235:  TEXTRECTANGLE now supports limited rotation options (TRF_SINGLELINE with 90, -90, or 180 degree rotation only). Note that the rectangle itself is not rotated, nor is the interpretation of the alignment options (TRF_LEFT, TRF_TOP, etc. remain relative to the rectangle in the standard orientation of the page. Only the text is rotated. See the sample GDI text file textrectr.txt in SOSLIB:[908,37] for examples.

2011 August, A-Shell 5.1.1230:  Added Syntax Two

2007 April, A-Shell 4.9.986:  Increased the maximum paragraph length supported by the TEXTRECTANGLE command to 16K from 2K. This is considerably longer than can fit on a page, which is the effective limit for what a single TEXTRECTANGLE can handle anyway. Larger paragraphs can still be analyzed by MX_GDICALC, it would inevitably break them up into rectangles (or entire pages) that were individually less than 16K (unless perhaps you used 2 point type in an effort to cram 16K of unreadable text on a page).

An error message box will be displayed if any single line of the printfile exceeds the 16K limit.

Note that neither MX_GDICALC nor TEXTRECTANGLE support the line continuation character (\) so unless you want to insert your own line breaks, the entire paragraph has to be output as a single line (with the only CRLF being at the end).

2005 May, A-Shell 4.9.986:  Routine added to A-Shell