WIN ( GET )

Collect Thoroughbred Basic Window Data

This string function returns the text, attribute, and/or color strings for the current Thoroughbred Basic Window or some portion of the Thoroughbred Basic Window.

Syntax

WIN ( GET [delim-1][delim-2] )

delim-1: determines the extent of the GET:

not specified = text, attribute, and color strings
ATTR = attribute string only
COLOR = color string only
TEXT = text string only

delim-2: determines how much of the extent specified by delim-1 is to be retrieved:

blank = complete string for full Thoroughbred Basic Window CHAR = only those character positions specified (see below) ROW = only the row specified (see below)

Remarks

This function is generally available starting with release level 8.1.

The options available for delim-1 are:

delim-1: Description
not specified: Indicates that the returned string contains substrings for text, attributes, as well as color based on the byte format for the full screen as shown below.
ATTR: Indicates that the returned string contains only the attribute string; there are no format bytes on the front, and the string length is based on the delim-2 specifier.
COLOR: Indicates that the returned string contains only the color string; there are no format bytes on the front, and the string length is based on the delim-2 specifier.
TEXT: Indicates that the returned string contains the actual text characters; there are no format bytes on the front, and the string length is based on the delim-2 specifier.

The available options for delim-2 are (all column and row specifiers are zero-based):

delim-2: Description
blank: Indicates that delim-1 references the entire Thoroughbred Basic Window, starting at position 0,0 (upper left corner), progressing across each row, left to right, with the last character being the lower right corner of the Thoroughbred Basic Window.
CHAR,: col1, row1, length Indicates that delim-1 references a specific string of characters starting at position col1, row1, progressing across each row, left to right, for a total number of characters specified by length. For delim-2 of CHAR, all 3 parameters ( col1, row1, length) must be specified.

Special values of col1/row1 are:

-1 current col/row Special values of length are:

-1 from, and including, the specified cursor position through the end of the Thoroughbred Basic Window

-2 from position 0,0 (upper left corner) to, and including, the specified cursor position

-3 from, and including, the specified cursor position through the end of that row

-4 from the first character in the specified row through, and including, the specified cursor position

ROW, row1: Indicates that delim-1 references the specific row number given in row1. For delim-2 of ROW, parameter row1 must be specified. Special values of row1 are:

-1 the row containing the current cursor position

-2 the top row

-3 the bottom row

If you use this function but Thoroughbred Basic Windows is not enabled, an ERR=70 results. For information on how to enable Thoroughbred Basic Windows, please refer to the information on TCONFIG files and IPL files in the chapter on System Files in the Thoroughbred Basic Customization and Tuning Guide.

The returned string is identical in format to the string used by the WINDOW PUT directive to restore an entire Thoroughbred Basic Window or portion, optionally including attributes and color, to a specific text.

The format of the returned string when delim-1 is not specified is:

Byte(s): Description
1 - 2: Binary number of Thoroughbred Basic Window maps to follow.
3 - 4: Binary number of bytes per Thoroughbred Basic Window map (does not include leading 2-byte map type).
5 - n: Map type and contents:

First 2 bytes: binary map type.

0 = text map
1 = attribute map
2 = color map

Third byte and beyond: map characters, row by row, for length specified in bytes 3 - 4 of full string.

5 + 2 +
(value of 3 - 4) The next map.

The attribute map contains one byte for every byte of text. Each bit in the attribute byte signifies a different characteristic for the byte of text. Considering the rightmost bit to be bit 0, their meanings are:

bit 0 = 0 when background, 1 when foreground
bit 1 = 0 when normal video, 1 when reverse video
bit 2 = 0 when underline off, 1 when underline on
bit 3 = 0 when steady, 1 when blink
bit 4 = not used
bit 5 = 0 when graphics mode off, 1 when graphics mode on
bits 6-7 = not used

Examples

LET CURRENT_WINDOW$ = WIN ( GET )

If CURRENT_WINDOW$ contained a 30-byte string of $00 02 00 0B 00 00 48 45 4C 4C 4F 20 57 4F 52 4C 44 00 01 00 00 00 00 00 00 00 00 00 00 00$ (the spacing is for clarity), it represents an 11-byte Thoroughbred Basic Window containing “HELLO WORLD” with each character in background mode.

LET THIS_ROW_COLOR$ = WIN ( GET COLOR ROW, -1 )

returns a string, equal to the length of one row in the current Thoroughbred Basic Window, containing the color bytes for the row in which the current cursor resides.

LET THIS_WINDOW_ATTR$ = WIN ( GET ATTR )

returns the attribute string for this entire Thoroughbred Basic Window.

LET THIS_COMPLETE_ROW$ = WIN ( GET ROW, -1 )

returns text, attribute, and color strings, formatted, for the row containing the cursor.

WIN ( GET )

Syntax

Remarks

Examples

See also