|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall T_PUTTXT(window_id, [text], [array_size][, option, ...])
Arguments
window_id
The ID of the text window to access. (n)
text
(optional) The text to load. (a)
array_size
(optional) The number of lines to load. (n)
option
(optional) One or more of the following: (n)
Start new line before first line output.
Start new paragraph before first line output.
Keep interline spacing for a window.
Remove interline spacing for a window.
Set trailing blank strip mode.
Turn off strip mode.
Set wrap mode.
Turn off wrap mode.
Set WRITES mode.
Turn off WRITES mode.
Make specified modes permanent.
Discussion
When T_PUTTXT loads text, it structures the text according to the structure of the text window. It automatically breaks lines when necessary and wraps the text if wrap is set. Thus, loading can be independent of the form of the text being loaded. For example, if you load 2,000 characters of straight text (with no line breaks), T_PUTTXT will break the text into lines and you might end up with 40 lines of text (depending on the margins of your window). To change the text’s appearance, you simply change the configuration of the window (such as margins and renditions) rather than re-creating the text itself.
You cannot use T_PUTTXT to load text into a window that has not been set up with T_SETUP. In other words, the window specified by window_id must be a text window, as opposed to an input window or a window created with the Synergy DBL W_PROC subroutine.
Text is either an alpha variable or the first element of an alpha array. If array_size is present and non-zero, text is considered to be the first element of an array whose size is equal to or greater than array_size. If array_size is omitted or has a value of zero, text is considered to be a single alpha field. There is no limit on the size of text. Note that text is optional; you can use T_PUTTXT to set permanent options for future text “puts” without loading any text at this time.
As with the T_SETUP subroutine, every option is processed before the text is output. Separate multiple options with commas. You can specify up to 10 options. If a particular mode is not specified, the current default (as set by T_SETUP or a previous T_PUTTXT) will be used.
If D_PERM is not present, the modes will only be in effect for the duration of this subroutine. If D_PERM is present, any modes specified in this subroutine will become the new defaults. The T_SETUP subroutine can also modify the defaults.
If D_NEWLN or D_PARA are not present, the text will be output beginning at the current window position.
When entering T_EDIT or T_VIEW on Windows, D_KEEPLEADING prevents Toolkit from removing the interline spacing for a window. With T_EDIT, this may cause more rows of text to become visible than the display area of the window would dictate. In addition, D_NOKEEPLEADING restores default behavior: Toolkit removes interline spacing for a window, which makes the window vertically shorter. Note that D_KEEPLEADING and D_NOKEEPLEADING are ignored on Windows if D_PERM is not passed. These options are always ignored on Unix and OpenVMS.
When strip mode is in effect, the trailing blanks are stripped from each element of text before the items are loaded into a text window. If wrap mode is also in effect, a single trailing blank is implicitly added to each stripped line.
In wrap mode, each line is considered to be one or more items that are separated by one or more blanks. Text is output until an item crosses the right margin. At this point, the item that would have crossed the margin is placed on the next line, and loading continues.
In WRITES mode, each line of output is displayed as if the Synergy DBL WRITES statement had been used; at the end of each line, the current position within the window automatically moves to the left margin of the next line in the text window.
If specified modifiers conflict, the last one to be processed will be in effect.
Examples
The following example loads 10 lines from newtext to the window, one line of text per window line.
xcall t_puttxt(wndid, newtext, 10, D_WRITES)
The next example loads the 15 elements of newtext into the window, stripping trailing blanks and wrapping to the next line on overflow. (This means the text will wrap, as described above.)
xcall t_puttxt(wndid, newtext, 15, D_STRIP, D_WRAP)
