.TEXT

Add text to a window or menu column

WSupported on Windows
USupported on Unix
VSupported on OpenVMS
NSupported in Synergy .NET
 
.TEXT name[, POSITION(row, column)][, MARGIN(left, right)] lines_of_text...

or 

.TEXT text[, justification]

Arguments

name

The name of the text (a maximum of 30 characters).

POSITION (row, column)

(optional) The position specification for the text, indicating the row and column at which the upper-left corner of the text is positioned. The position doesn’t have to be in the display area, but it must be within the window.

MARGIN (left, right)

(optional) The margin specification for the text, indicating the number of columns from the left margin and the right margin. Margins are the number of spaces from the left and right edge of the window. If left is less than or equal to column, this setting applies to all but the first line, whose indent in this case is controlled by the column argument for POSITION.

lines_of_text

One or more lines of text in general or input windows.

text

A text string in menu columns or selection windows.

justification

Designates how the column text is aligned within the entry-text area, as opposed to the entire width of the menu or selection column. Valid values are LEFT (default), RIGHT, CENTERED.

Discussion

The first form of the .TEXT command above is used to add text to a general or input window. Lines_of_text can contain data control commands that control the renditions of the text. See Data Control Commands and Text below.

When justified text is needed on the same line as an input field, make sure that the .FIELD command occurs after the .TEXT command.

The second form of the .TEXT command adds the contents of text to a column or selection window. This text is not a selection. The required width of this entry is two spaces longer than the length of text, and the text is loaded starting at the second character position (when left-justified). The width of the selection column is increased, if necessary, to accommodate the width of the entry.

If you don’t specify LEFT, RIGHT, or CENTERED, the text will be left-justified by default.

If you have a selection window defined by .SELECT that has more than one column but does not have corresponding text entries in the same row of each column, left and right movement within the window won’t be consistent. We therefore recommend that you make sure each column in a multi-column selection window contains its text entries in the same row.

.TEXT in a selection window definition (.SELECT) is ignored on Windows.

Note that .TEXT is optional (unless you use the script in Composer, which requires it). If you include a line of text that is not preceded by a .TEXT command, Script adds the text to the window, using margin and rendition settings that match the previous line of text processed by Script, and positioning the text to follow the previous line of text. If Script has not previously processed a line of text, Script uses the following settings: a position of 1,1; no margins; no attributes; and color 1.

Data Control Commands and Text

Data control commands affect the position and display of text within general and input windows.

The script compiler initially loads text into the window starting at window row 1, column 1, unless a data control command changes the position. Each time the script compiler loads text into the window, it updates the position. (The .FIELD command also will update the position.)

The maximum length of a text line in a script file is 255 characters. If there are too many text lines for the windows, all overflow lines are ignored. Tabs are converted into a space.

If a word starts with a backslash (\), it is considered a data control command. Data control commands can be anywhere on a text line, even embedded in text. A dash (–) after the backslash resets the command, but only commands that can be reset process the dash; all others ignore it. Data control commands are one character long, and any arguments must be enclosed in parentheses.

Rendition commands

You can turn five window renditions on and off in the script file:

The lines in the script file are processed sequentially, so any text after a rendition change is displayed with the new renditions until you change renditions again.

In each window definition, attributes are initially clear. Once set, they remain set until explicitly cleared.

The commands for setting and resetting the renditions are shown in the following table.

Rendition Commands

Command

Meaning

\b | \i

Blinking on (Unix and OpenVMS) or italic (Windows)

\-b | \-i

Blinking off (Unix and OpenVMS) or italic off (Windows)

\c (palette#)

Color palette number (default value is 1)

\h

Highlighting (bolding) on

\-h

Highlighting off

\r

Reverse video on

\-r

Reverse video off

\u

Underlining on

\-u

Underlining off

For example:

.window renditions, 20, 45
.place 3, 18
.title "Renditions"
.border rev
.text mytext, position(2,2), margin(2,2)
\bThis blinks.\-b\n
\hThis is bold.\-h\n
\rThis is in reverse video.\-r\n
\uThis is underlined.\-u\n
This isn't.\n
.trim
.end

Miscellaneous commands

The remaining data control commands are described below:

\j (option)

Justifies the text that follows over blanks within the margins. Justification doesn’t take effect until you have a new line or word wrap. If you’ve done a fill on the line, no justification will occur.

Option can be one of the following:

1 = left (default)

r = right

c = center

f = fill line (right- and left-justify text)

Lines are left-justified by default. The next new line is either the next line after a \n or the next line of overflow text.

When the f option is set, spacing between words on a line will be adjusted so the line fits exactly between the margins. Line filling is only done when an implicit new line (because of word wrap) occurs. An explicit new line (because of a \n) will not cause the previous line to be filled.

If the last specified renditions (such as \b, \h, \r) were specified on a previous line, the renditions will apply not only to the justified text, but to the entire line (except the margins). If you specify renditions on the same line as the justified text, the renditions will apply only to the justified text (blanks on either side of the text will receive any previously-specified renditions).

If you need to center text that’s enclosed in a box, draw the box at the end of the window definition.

For example:

.window justify, 10, 45
.title "Justifying"
.border rev
.text mytext, position(1,2), margin(2,2)
\n
\j(l)This text is left-justified.\n
\n
\j(r)This text is right-justified.\n
\n
This
text
\j(c)
is
centered.
\n
\n
\j(f)This text left- and right-justified.
.end

\n

Moves the window display position to the next line’s left margin. It also forces justification after a justify (\j) command.

For example:

.window newline, 20, 45
.place 3, 18
.title "New Lines"
.border rev
.text mytext, position(2,2), margin(2,2)
The \\n command moves the text display to the next line. If a script contains two new line 
commands in a row (\\n\\n), it will skip two lines.\n
\nLike that.\n\n
This command is sometimes necessary when you want to justify text with the \\j command. 
Justification occurs at the next new line, so you may need to use a \\n command after the 
text you want justified.
.trim
.end

\s and \-s

The \s command (default) adds a space to the end of a text line in the script file so that when words wrap across lines in the window, they are properly delimited by a space. This spacing occurs only if wrap mode is active and the last word on the line in the script file is not already followed by a space.

The \-s command resets this feature.

For example:

.window spacing, 3,10
.title "Spacing"
.border rev
.text mytext
word
wrap
\-s
word
wrap
.end

This script first uses the default settings of \s and \w (see description of \w below), which means that the first line of the resulting window is as follows:

word wrap

When we turn off the default spacing, however, “wrap” will still be displayed on the same line as “word” because of the automatic word wrap, but the space will not be inserted automatically. The second line of text in the resulting window is therefore:

wordwrap

\w and \-w

The \w command (default) turns word wrap on. If a word overflows the current display line, the entire word is moved to the left margin on the next line, and trailing blanks on the previous line are trimmed. If the text overflows the last line of the window, it is ignored. If wrap is not set, any overflow at the end of a line is ignored.

The \-w command turns word wrap off.

For example:

.window wrap, 20, 25
.title "Wrap"
.border rev
.text mytext, margin(2,2)
\n\n
Wrap mode is the default in the script compiler, which makes it easy to load different 
blocks of text into the same window. You may, however, want to turn off the wrap mode with \\-w.
\-w
\n\n
Now wrap mode\n
is turned off.\n
If text goes past\n
the window's edge,\n
it simply will not appear.
.end

Special characters

\.

Puts a single period in the text. This command is especially useful if you want to have a leading period in a line of text. This command is unnecessary if the period is within or at the end of text.

\\

Places a backslash into the text. (See the example under \; below.)

\;

Treats the text line as a comment. The end of the text line is the end of the comment. The comment line must be within a window definition and on its own line.

For example:

.window comments, 20, 45
.place 3, 18
.title "Comments"
.border rev
.text mytext, position(2, 2), margin(2, 2)
When you are developing with UI Toolkit, you may find it useful or necessary to include 
comments within scripts that you do not want to display. To do this, begin a comment with \\;. 
\n\n
\;For example, this sentence will not be displayed.
\;To continue a comment on another line, you must begin the
\;next line with another \\;.
.trim
.end

Comment lines can exist outside of a text definition if preceded by a semicolon (;). See Comments and blank lines for more information.

Examples

This example displays text at row 2 and column 2 of a general or input window—2 spaces in front of the left and right margins.

.text mytext, position (2,2), margin (2,2)
This is some text in my window.
And here is some more text.

The following example adds the text “System Manager Functions” to the menu column. This text is aligned with the left side of the column entries.

.text "System Manager Functions"