Control window display and input functions
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall W_DISP(id, function, arguments[, function, arguments][, ...])
Arguments
id
A variable that contains the window ID. (n)
function
One or more of the following functions:
alpha_expression = Print the specified text to the window.
WD_ACCEPT = Receive a character from the terminal.
WD_ANSI = Treat next argument as a string with embedded escape sequences.
WD_ATTR = Modify attributes for the display area.
WD_BELL = Update the screen and ring the terminal bell.
WD_CLEAR = Clear the window to blanks.
WD_CLR = Perform clear processing similar to $SCR_CLR.
WD_COLOR = Set the current display color.
WD_FIELD = Send a field to the window.
WD_GETS = Get input from the terminal.
WD_HERASE = Erase horizontal lines.
WD_HLINE = Draw a horizontal line.
WD_MOVE = Change the current window position relatively.
WD_POS = Change the current window position absolutely.
WD_READS = Read data from the terminal into the window.
WD_REPEAT = Set the repeat count for the next WD_FIELD function.
WD_UPDT = Update the physical screen.
WD_VERASE = Erase vertical lines.
WD_VLINE = Draw a vertical line.
WD_WAIT = Wait the specified time for input.
WD_WRITES = Display next argument at current position.
arguments
(optional) Any arguments used by the specified function.
Discussion
W_DISP controls window display and input functions.
If the window is placed and visible, W_DISP functions do not change the screen display until the screen is updated with a WD_READS, WD_GETS, WD_ACCEPT, WD_BELL, WD_UPDT, or WF_INPUT function or until you call W_UPDT. (The screen is also updated by WA_INSERT or WA_SCROLL when hardware scrolling is in effect.)
The ACCHR subroutine affects the windowing system for terminating input.
If you use ^VARARGARRAY, function is the last declared argument for this routine.
If you have a telnet terminal connection, see $ERR_IOFAIL for more information.
W_DISP does not work with redirected input and output on Windows.
alpha_expression
alpha_expression
This function displays the specified text to the window at the current window position (unless a different position is specified). The current column position is altered by the length of the alpha field until the field reaches the window’s boundary. In other words, if you display the five-character message “Hello” starting at position (1,1), the current window position changes to (1,6) after “Hello” is displayed.
Any text that exceeds the window’s boundaries is ignored. The text has the current display attributes for the window, which you can alter with the WD_ATTR function. (See WD_ATTR for more information.)
The example below positions the first character at row 4, column 2 within the display area and displays a message beginning at that position.
xcall w_disp(wndw_1, WD_POS, 4, 2, "Welcome to Synergy DBL!")
WD_ACCEPT, field
WD_ACCEPT receives a character from the terminal without an input terminator and stores it in an alpha or numeric field.
This function is similar to the Synergy DBL ACCEPT statement. The flags set with the FLAGS subroutine have the same effect on the WD_ACCEPT function as they do on the ACCEPT statement. However, the windowing system sets runtime option flags #4 and #10 for input, and it does not reset them after the input has been completed.
Another difference is that when using WD_ACCEPT, you can’t trap errors with an end-of-file label or an I/O error list. To trap errors, use an ONERROR statement before the call to W_DISP. Like WD_GETS, WD_READS, and WD_BELL, this function automatically updates the screen.
On Unix, WD_ACCEPT maps a line feed character to a carriage return and line feed when input is redirected. Most input files on Unix are composed of lines containing characters followed by a line feed. To properly handle this lack of a carriage return, one is added when WD_ACCEPT encounters a line feed.
The example below displays a list of choices and stores the user’s response in a field called select. It also traps for an EOF error.
onerror ($ERR_EOF)eof xcall w_disp(wndw_1, WD_POS, 2, 2, "1. View all records", & WD_POS, 4, 2, "2. Select record by name", & WD_POS, 6, 2, "3. Select record by company", & WD_POS, 8, 2, "Choice?", WD_ACCEPT, select) offerror
WD_ANSI
WD_ANSI causes the next argument to be treated as a string that contains embedded escape sequences. It can be used to convert VT escape sequences to ANSI for Windows support. WD_ANSI only works on the next alpha argument in your code, so if you have multiple alpha arguments with escape sequences in them, you will need to put a WD_ANSI in front of each.
The following sequences are currently supported (where n is a number):
|
<esc>[n;nf |
Position cursor. |
|
<esc>[n;nH |
Position cursor. |
|
<esc>[1 |
Set protect attribute. |
|
<esc>[2 |
Clear protect attribute. |
|
<esc>[nm |
Set/clear attributes (n is optional and defaults to 0). |
|
<esc>[J |
Clear to end of screen. |
|
<esc>[0J |
Clear to end of screen. |
|
<esc>[1J |
Clear to beginning of screen. |
|
<esc>[2J |
Clear screen. |
|
<esc>[K |
Clear to end of line. |
|
<esc>[0K |
Clear to end of line. |
|
<esc>[1K |
Clear to beginning of line |
|
<esc>[2K |
Clear line. |
|
<esc>[nA |
Move cursor up n rows (n is optional and defaults to 1). |
|
<esc>[nB |
Move cursor down n rows (n is optional and defaults to 1). |
|
<esc>[nC |
Cursor left n characters (n is optional and defaults to 1). |
|
<esc>[nD |
Move cursor right n characters (n is optional and defaults to 1). |
|
^N |
Interpret lowercase characters as graphics. |
|
^O |
Do not interpret lowercase characters as graphics. |
|
^I |
Move cursor right to next tab stop (every eight characters). |
|
CR |
Move cursor to LHS of screen. |
|
LF |
Move cursor down one line. |
|
BS |
Move cursor left one character. |
|
BELL |
Sound the terminal bell. |
|
NULL |
Character ignored. |
WD_ATTR, attributes
WD_ATTR sets and alters attributes for subsequent display. See Attributes for information on standard window attributes.
The example below sets the reverse video attribute.
xcall w_disp(wndw_1, WD_ATTR, ATTR_SET + ATTR_RVRS, "Displayed in reverse video")
WD_BELL
WD_BELL updates the screen just like WD_UPDT and then issues a bell character (0x07) to the terminal. The bell character is external to the window being referenced.
On Windows, the computer issues a beep; it does not send a ^G to the screen.
|
Use WD_BELL for a system-independent method of ringing the terminal bell. |
WD_CLEAR
WD_CLEAR clears the window to blanks with the current display attributes. After the window is cleared, the current position in the window returns to row 1, column 1.
In the example below, if an ONERROR statement traps the eof label, we clear the window’s display area with WD_CLEAR and display the “End of File” message.
eof, xcall w_disp(wndw_1, WD_CLEAR, WD_POS, 5, 2, "End of File")
WD_CLR, option
WD_CLR performs clear processing with the current display attributes. Option defines the type of clearing that is to occur, and all of the clear options reference the current position within the window, without modifying that position. Option can be one of the following options:
|
WDC_WND |
Clear the entire window. |
|
WDC_BOW |
Clear from the beginning of the window to the current position. |
|
WDC_EOW |
Clear from the current position to the end of the window. |
|
WDC_LIN |
Clear the entire line that contains the current position. |
|
WDC_BOL |
Clear from the beginning of the line to the current position. |
|
WDC_EOL |
Clear from the current position to the end of the line. |
WD_COLOR, color
WD_COLOR sets the current display color to color, which is a numeric expression that contains a palette number between 1 and 16. See Colors and the color palette for more information about color. For WD_COLOR support in SDK-style projects on Linux, the WNDC environment variable must be set in the environment.
WD_FIELD, expression
WD_FIELD displays a field of text to the window, where expression is the text to be displayed. If expression is alpha, its result is displayed, and the text has the current display attributes for the window. If expression is numeric, its value is converted to the corresponding ASCII character (according to the Synergy DBL ASCII character set), and that character is displayed.
This function updates the current column position by the length of the field until the column position reaches the window’s boundary. Any text that exceeds the window’s boundaries is ignored.
You can display the same field for a specified number of repetitions by using the WD_REPEAT function. (See WD_REPEAT.)
In the example below, we use three display expressions (abc, xyz, and hello) whose lengths are defined by the length of the strings displayed in the fields. The WD_REPEAT function sets the repeat count for the WD_FIELD’s text immediately after it, which in this case is xyz. When we display hello, it is only displayed once.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 8, 40)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 11, 21)
xcall w_disp(wndw_1, WD_FIELD, "abc", WD_UPDT)
xcall w_disp(wndw_1, WD_REPEAT, 3, WD_FIELD, "xyz", WD_UPDT)
xcall w_disp(wndw_1, WD_FIELD, "hello", WD_UPDT)
xcall w_exit
stop
end
WD_GETS, alpha_field
WD_GETS obtains input from the terminal at the current window position. Alpha_field is the field in which to store the input, and it defines the maximum size of the input field. The window area receiving the data must be visible on the screen, or else you’ll receive a window error #11, “Input field not completely visible.” Like WD_ACCEPT, WD_READS, and WD_BELL, this function automatically updates the screen.
As you enter characters, the echoed characters overwrite any existing characters displayed in the field. If you delete characters during input, the original characters and display attributes are restored.
The WD_GETS function is similar to the standard Synergy DBL GETS statement. The flags set with the FLAGS subroutine have the same effect on the WD_GETS function as they do on the GETS statement. However, the windowing system sets runtime option flags #4 and #10 for input, and it does not reset them after the input has been completed.
Another difference is that when using WD_GETS, you can’t trap errors with an I/O error list or end-of-file label. To trap errors, use the ONERROR and OFFERROR statements.
In Synergy .NET, when doing a WD_GETS from a terminal with no echo, no echo is implemented as the PasswordChar input feature of the WinForms control, so the cursor moves on each character entered, even though the character is not displayed.
On Windows, WD_GETS has the same functionality as WD_READS.
The example below positions the display to the upper-left corner of the processing area with the WA_CORNER function, then moves the display down 2 rows and over 4 columns before requesting input. To obtain the input, this program uses WD_GETS and stores the response in an a5 field.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
a5_fld ,a5
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 51)
xcall w_proc(WP_PLACE, wndw_1, 12, 12)
xcall w_area(wndw_1, WA_CORNER, WAC_ULC)
xcall w_disp(wndw_1, WD_MOVE, 2, 4, "Input: ", WD_GETS, a5_fld)
xcall w_exit
stop
end
WD_HERASE, row, column, length
WD_HERASE erases horizontal lines. Row, column, and length are numeric expressions, where row and column designate the point at which WD_HERASE should begin erasing, and length designates the number of columns that should be erased. WD_HERASE removes the crossing vertex character from any vertical lines that are “uncrossed.” It ignores any nonline characters within the range of the erasure and doesn’t modify display attributes. The current window position is not affected.
WD_HLINE, row, column, length
WD_HLINE draws a horizontal line. Row, column, and length are numeric expressions, where row and column mark the starting point of the line, and length indicates how many columns wide the line is. Horizontal lines are drawn from left to right. The current window position is not affected. Intersected vertical line characters are changed to tees or crosses as appropriate.
In the example below, we use WD_HLINE to draw two horizontal lines: the first one starts at row 3, column 3 and is 36 columns wide, and the second starts at row 6, column 3 and is also 36 columns wide. Then we draw two vertical lines with WD_VLINE: the first starts at row 3 column 16 and is 5 rows long, and the second starts at row 3 column 34 and is 4 rows long.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 8, 40, WP_PLACE, wndw_1, 14, 21)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_HLINE, 3, 3, 36, WD_HLINE, 6, 3, 36)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_VLINE, 3, 16, 5)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_VLINE, 3, 34, 4)
xcall w_updt
sleep 1
xcall w_proc(WP_REMOVE, wndw_1)
xcall w_exit
stop
end
WD_MOVE, row_change, column_change
WD_MOVE changes the current window input position by adding the value of row_change and column_change to the current row and column values. Row_change and column_change are numeric expressions, where row_change is the number of rows the input position should move and column_change is the number of columns the input position should move. The resulting row and column position must be within the window. If the position is not within the window, the system automatically shifts the position to the values closest to the ones you specified. For example, if you are at row 1, column 1 in a window of 11 rows by 50 columns and you specify a row change of 5 and a column change of 50, the position changes to (6,50).
If you want to move the input position up or to the left, use a negative value for row_change or column_change, respectively.
In the following routine, we use WD_MOVE to alter the display position by moving it first to the right 23 columns, then down 6 rows and 12 columns to the left, and finally 40 columns to the left.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 7, 40)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 11, 21)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, "top left")
xcall w_disp(wndw_1, WD_MOVE, 0, 23, "top right")
xcall w_disp(wndw_1, WD_MOVE, 6, -12, "bottom right")
xcall w_disp(wndw_1, WD_MOVE, 0, -40, "bottom left")
xcall w_exit
stop
end
WD_POS, row, column
WD_POS changes the current window input position. Row and column are numeric expressions that indicate where the window input position should be placed. The specified row and column must be within the window. If the position is not within the window, the system automatically shifts the position to the values closest to the ones you specified. For example, if you create a window of 11 rows by 50 columns and specify a position of row 5, column 60, the position is changed to (5,50).
If you specify a row or column value of 0, the current value for that argument is used.
The following example is similar to the WD_MOVE example, except that the WD_POS function requires you to specify the absolute values of the row and column positions, not the relative values.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 7, 40)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 11, 21)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_POS, 7, 1, "bottom left")
xcall w_disp(wndw_1, WD_POS, 1, 32, "top right")
xcall w_exit
stop
end
WD_READS, alpha_field
WD_READS reads data from the terminal into the window at the current window position. Alpha_field is the field in which to store the input, and it defines the maximum size of the input field. The window area receiving the data must be visible on the screen, or else you’ll receive a window error #11, “Input field not completely visible.” Termination and activation characters are not echoed, but nonprinting characters echo as a period (.).
When a character is deleted during WD_READS processing, the character that was originally at the window position prior to the input is restored, along with its display attributes. (In such a situation, the paint character is meaningless, and it is ignored during deletions.)
Like WD_ACCEPT, WD_GETS, and WD_BELL, the WD_READS function automatically updates the screen.
The WD_READS function is similar to the Synergy DBL READS statement. The flags set with the FLAGS subroutine have the same effect on the WD_READS function as they do on the READS statement. However, the windowing system sets runtime option flags #4 and #10 for input, and it does not reset them after the input has been completed. Another difference is that with WD_READS, you can’t trap errors with an end-of-file label or an I/O error list. To trap errors, you must include an ONERROR statement before calling W_DISP.
A limitation of WD_READS on Windows is that it does not terminate input when the field is full. The text from the area of the window where the cursor is placed, for the length of the input field, is loaded into the edit control as an initial value. You must press Enter after input is complete (even if you set runtime option flag #9) to accept that value. WD_READS will also terminate on EOF or any extended key press (function key or up and down arrow keys), although they also leave characters in the buffer. (Tip: You may want to use TTSTS or WD_ACCEPT to clear the buffer before accepting any more input.) Left and right arrow keys are processed by the edit control to move within the field, rather than being returned to the caller. The %RDTRM and %RTERM routines also elicit the terminate character.
WD_READS has the same functionality as WD_GETS on Windows.
In Synergy .NET, when doing a WD_READS from a terminal with no echo, no echo is implemented as the PasswordChar input feature of the WinForms control, so the cursor moves on each character entered, even though the character is not displayed.
On Unix and OpenVMS, any text in the area of the window occupied by the input area continues to be displayed until the user types over it, but it is not returned in alpha_field. The contents of alpha_field only reflect what the user typed.
The example below positions the display to the upper-left corner with the WA_CORNER function, then moves the display down 2 rows and over 4 columns before requesting input. To obtain the input, this program uses WD_READS and stores the response in a5_fld.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
a5_fld ,a5
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 51)
xcall w_proc(WP_PLACE, wndw_1, 12, 12)
xcall w_area(wndw_1, WA_CORNER, WAC_ULC)
xcall w_disp(wndw_1, WD_MOVE, 2, 4, "Input: ", WD_READS, a5_fld)
xcall w_exit
stop
end
WD_REPEAT, count
WD_REPEAT sets the repeat count for the next WD_FIELD function. The field supplied in the next WD_FIELD function is output the number of times specified in count.
The WD_REPEAT function works only for the next WD_FIELD function; you must specify a count for each WD_FIELD function that has a repeating field.
In the following routine, we use three display expressions: abc, xyz, and hello. The WD_REPEAT function sets the repeat count for the display field defined immediately after it, in this case, xyz. When we display hello, it is only displayed once.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 8, 40)
xcall w_area(wndw_1, WA_FILL, ".")
xcall w_proc(WP_PLACE, wndw_1, 11, 21)
xcall w_disp(wndw_1, WD_FIELD, "abc")
xcall w_disp(wndw_1, WD_REPEAT, 3, WD_FIELD, "xyz")
xcall w_disp(wndw_1, WD_FIELD, "hello")
xcall w_exit
stop
end
WD_UPDT
WD_UPDT updates the physical screen just like the W_UPDT subroutine. It eliminates additional subroutine overhead by eliminating the need to call W_UPDT. Specify WD_UPDT as the last argument in your W_DISP argument list.
The following example displays the message “top right” beginning at row 1, column 32 within the window and updates the screen.
xcall w_disp(wndw_1, WD_POS, 1, 32, "top right", WD_UPDT)
WD_VERASE, row, column, length
WD_VERASE erases vertical lines. Row, column, and length are numeric expressions, where row and column are the point at which WD_VERASE should begin erasing, and length is the number of rows that should be erased. WD_VERASE removes the crossing vertex character from any horizontal lines that are “uncrossed.” It ignores any nonline characters within the range of the erasure and doesn’t modify display attributes. The current window position is not affected.
WD_VLINE, row, column, length
WD_VLINE draws a vertical line. Row, column, and length are numeric expressions, where row and column mark the starting point of the line, and length indicates how many rows deep the line is. Vertical lines are drawn from top to bottom. The current window position is not affected. Intersected horizontal line characters are changed to tees or crosses as appropriate.
In the example below, we use WD_HLINE to draw two horizontal lines: the first one starts at row 3, column 3, and is 36 columns wide, and the second starts at row 6, column 3, and is also 36 columns wide. Then we draw two vertical lines with WD_VLINE: the first starts at row 3, column 16 and is 5 rows long, and the second starts at row 3, column 34 and is 4 rows long.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
proc
open (WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 8, 40, WP_PLACE, wndw_1, 14, 21)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_HLINE, 3, 3, 36, WD_HLINE, 6, 3, 36)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_VLINE, 3, 16, 5)
xcall w_updt
sleep 1
xcall w_disp(wndw_1, WD_VLINE, 3, 34, 4)
xcall w_updt
sleep 1
xcall w_exit
stop
end
WD_WAIT, wait_time
WD_WAIT specifies a time-out value for input before generating a “Terminal input operation timeout” ($ERR_TIMOUT) error. Wait_time can be the number of seconds to wait or one of the following:
|
Q_NOWAIT or 0 |
Don’t wait if I/O processing can’t be completed. |
|
Q_WAIT or -1 |
Wait until I/O processing is completed. |
The Q_ identifiers are defined by the compiler.
You should specify the WD_WAIT function before you specify your WD_READS, WD_GETS, or WD_ACCEPT function.
In the example below, Synergy DBL waits five seconds for input before generating an error.
xcall w_disp(wndw_1, WD_WAIT, 5, WD_READS, rec)
WD_WRITES, field
WD_WRITES displays the next argument at the current position and wraps, if necessary. The position in the window is left at column 1 of the next row in the processing area. If the bottom of the processing area is encountered, the screen scrolls up. The field argument is an alpha expression.
