Get information about the windowing system
|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
xcall W_INFO(function[, arguments])
Arguments
function
One of the following functions:
WI_ACTIVE = Return the IDs of the active windows.
WI_AREAS = Return area information for a window.
WI_ATTRS = Return a window’s attributes.
WI_BCHR = Return the border-drawing character for a window.
WI_NAME = Retrieve the name of a window.
WI_PALET = Return the foreground/background and character color codes for the current palette entries.
WI_PLACED = Return the number of placed windows and their window IDs.
WI_SYSTEM = Return general information about the windowing system.
WI_TITLE = Return title information for a window.
WI_USER = Return the parameters of a user data set.
WI_VPLACE = Return virtual placement list.
WI_WINDOW = Return general information about a window.
WI_XFR = Transfer the current processing area’s attributes and data to or from a variable.
arguments
(optional) Any arguments used by the specified function.
W_INFO enables you to obtain various types of information about the windowing system. In the sections below, we describe the type and size of the fields you must create to receive the information, and we supply a typical record definition for the return value arguments.
The return value arguments must be numeric, which means you can’t access the array by naming the record as the argument. (Records are alpha.) Instead, supply the name of the first array element as the argument in the W_INFO function. (The function descriptions include examples of data areas in which to store returned information.)
If you use ^VARARGARRAY, function is the last declared argument for this routine.
|
You can optionally call the W_INFO subroutine as a function. See %W_INFO for a description of this function. |
WI_ACTIVE, return_values
WI_ACTIVE returns the IDs of the active windows, where return_values is the first element of a numeric array to be loaded with the number of active windows and the window IDs in numerical order. The size of each array element must be large enough to contain the maximum window ID, and the number of array elements should be one greater than the maximum number of windows specified in the W_INIT statement.
The example below indicates the entire array in the WI_ACTIVE function by naming the first element of the array (in this case, numwins).
.include "WND:windows.def"
.define WNDCHNL, 1
.define MAXWINS, 10
record
numwins ,i4
ids ,MAXWINS i4
proc
xcall w_init(0, WNDCHNL, MAXWINS)
.
.
.
xcall w_info(WI_ACTIVE, numwins)
WI_AREAS, id, return_values
WI_AREAS returns area information for the window specified by id. Return_values is an 8d3 array loaded with the following information: window row, window column, number of rows, and number of columns in the window’s current display area, followed by the window row, window column, number of rows, and number of columns in the current processing area.
For example,
record
retvals ,8d3
disp_orig_row ,d3 @alpha
disp_orig_col ,d3 @alpha + 3
disp_num_row ,d3 @alpha + 6
disp_num_col ,d3 @alpha + 9
area_orig_row ,d3 @alpha + 12
area_orig_col ,d3 @alpha + 15
area_num_row ,d3 @alpha + 18
area_num_col ,d3 @alpha + 21
.
.
.
xcall w_info(WI_AREAS, wndid, retvals)
WI_ATTRS, id, return_values
WI_ATTRS returns the specified window’s attributes. Return_values is a 6d4 array loaded with the following information: the window attribute code, the window palette number, the border attribute code, the border palette number, the title attribute code, and the title palette number. An attribute code is a four-digit number, with each digit representing an attribute. If you want to save a window and restore its attributes later, you can use ATTR_LOAD + wnd_attr (the variable into which you have stored the attribute code).
For example,
record
wndid ,i4
retvals ,6d4
wnd_attr ,d4 @retvals
wnd_pal ,d4 @retvals + 4
brd_attr ,d4 @retvals + 8
brd_pal ,d4 @retvals + 12
ttl_attr ,d4 @retvals + 16
ttl_pal ,d4 @retvals + 20
.
.
.
xcall w_info(WI_ATTRS, wndid, retvals)
WI_BCHR, id, return_values
WI_BCHR returns the border drawing characters for the specified window. Return_values is a 6d3 array loaded with the following information: the display codes for the horizontal line, vertical line, upper-left corner, upper-right corner, lower-left corner, and lower-right corner.
For example,
record
wndid ,i4
border ,6d3
hline_chr ,d3 @border
vline_chr ,d3 @border + 3
ulc_chr ,d3 @border + 6
urc_chr ,d3 @border + 9
llc_chr ,d3 @border + 12
lrc_chr ,d3 @border + 15
.
.
.
xcall w_info(WI_BCHR, wndid, retvals)
WI_NAME, id, name
WI_NAME retrieves the name of a window specified by id. You can also get the name of a window using the WI_WINDOW subfunction; however, this subfunction also returns 11 other pieces of information in a numeric array. WI_NAME simplifies the process of retrieving just the name.
For example,
xcall w_info(WI_NAME, wndid, name)
WI_PALET, return_values
WI_PALET returns the background and character color codes for the current palette entries. Return_values is a 32d3 array loaded with the system-dependent background and character colors for each of the 16 palette entries. The first 16 elements are loaded with the background color codes for the 16 palette entries, and the last 16 elements are loaded with the character color codes. See Colors and the color palette for more information about color.
For example,
record
retvals 32d3
background ,16d3 @paletcodes
characters ,16d3 @paletcodes + 48
.
.
.
xcall w_info(WI_PALET, retvals)
WI_PLACED, return_values
WI_PLACED returns the number of placed windows and their window IDs, in placement order. Return_values is a numeric array loaded first with the number of placed windows and then with the window IDs in placement order. The size of each array element must be large enough to contain the maximum window ID, and the number of array elements should be one greater than the maximum number of windows specified in the W_INIT statement.
The example below indicates the entire array in the WI_PLACED function by naming the first element of the array (in this case, numwins).
.include "WND:windows.def"
.define WNDCHNL, 1
.define MAXWINS, 10
record
numwins ,i4
ids ,MAXWINS i4
proc
xcall w_init(0, WNDCHNL, MAXWINS)
.
.
.
xcall w_info(WI_PLACED, numwins)
WI_SYSTEM, arg_1, arg_2, return_values
WI_SYSTEM returns general information about the windowing system.
Both arg_1 and arg_2 are d5 fields that return the value of the W_INIT subroutine’s first argument. (In a previous version, these fields returned information about the windowing system’s memory pool. However, the windowing subroutines no longer require a window memory pool.)
Return_values is an 8d3 array loaded with the following information:
- Maximum number of windows
- Maximum number of screen rows
- Maximum number of screen columns
- Current number of screen rows
- Current number of screen columns
- Current screen row
- Current screen column
- Terminal channel
For example,
record
arg_1 ,d5
arg_2 ,d5
retvals ,8d3
maxwins ,d3 @retvals
maxrows ,d3 @retvals + 3
maxcols ,d3 @retvals + 6
curr_rows ,d3 @retvals + 9
curr_cols ,d3 @retvals + 12
updt_row ,d3 @retvals + 15
updt_col ,d3 @retvals + 18
ttchn ,d3 @retvals + 21
.
.
.
xcall w_info(WI_SYSTEM, arg_1, arg_2, retvals)
WI_TITLE, id, title, return_values
WI_TITLE returns title information for the window specified by id. Return_values is a 2d3 array loaded with the following information: a code signifying which border contains the title and a code signifying the position of the title within that border. If you want to save a window and restore the title information later, you can use the variables in which the codes are stored to restore the title with the same border and position.
For example,
record
wndid ,i4
title ,a50
retvals ,2d3
border ,d3 @retvals
pos ,d3 @retvals + 3
.
.
.
xcall w_info(WI_TITLE, wndid, title, retvals)
WI_USER, id, array
WI_USER returns the parameters of the current user data set, where id is the ID of the window to reference and array is the first element of a decimal array that is to receive the parameters. The first element of array is loaded with the number of entries, the second element is loaded with the length of each entry, and the third element receives the current field of the user data set. If no user data set is defined, all values are zero. (To establish the current user data set, use the WF_USERID function of W_FLDS, or the WIF_USERID function of %W_INFO.)
WI_VPLACE, return_values
WI_VPLACE returns the number of virtually placed windows and their window IDs. If a window is virtually placed, it means that it is physically placed if its parent window is also physically placed, and the converse. Windows without parents do not distinguish between virtual and physical placement; the two are identical.
While WI_PLACED returns the IDs of all windows (whether children of another window or not), that are physically visible on the screen, WI_VPLACE returns the IDs of all windows that are logically placed. This includes the list returned by WI_PLACED, as well as child windows that have been placed but have a parent (or ancestor) that is not placed.
WI_WINDOW, id, name, return_values
WI_WINDOW returns general information for the specified window. Name is returned with the window’s name, which can be up to 15 alpha characters long. Return_values is an 11d4 array loaded with the following information: the window’s number of rows, number of columns, placement row, placement column, status flags, overlay window ID, title length, number of fields in its field set, current field number in the field set, current row, and current column.
The status flags are represented by a d4 value, with 1 signifying true and 0 signifying false. The rightmost digit is 1 if the window is currently placed, the next digit is 1 if its border is currently on, and the next digit is 1 if a title is being displayed.
On Windows, the leftmost digit is always 0. On Unix and OpenVMS, the leftmost digit is 1 if the window is currently occluded by another window.
The overlay window ID is zero if the window is not an overlay window; otherwise it is the lowest numerical window ID that this window overlays.
For example,
record
wndid ,i4
name ,a15
retvals ,11d4
numrows ,d4 @retvals
numcols ,d4 @retvals + 4
placerow ,d4 @retvals + 8
placecol ,d4 @retvals + 12
flags ,d4 @retvals + 16
overid ,d4 @retvals + 20
titlelgth ,d4 @retvals + 24
numflds ,d4 @retvals + 28
curr_fld ,d4 @retvals + 32
curr_row ,d4 @retvals + 36
curr_col ,d4 @retvals + 40
.
.
.
xcall w_info(WI_WINDOW, wndid, name, retvals)
WI_XFR, id, option, info
WI_XFR transfers the current processing area’s attributes or data to or from a variable, where id is the ID of the window whose processing area should be transferred and option is one of the following:
|
WIX_AGET |
Transfer the area’s attributes to info. |
|
WIX_DGET |
Transfer the area’s data to info. |
|
WIX_APUT |
Transfer the attributes from info to the current area. |
|
WIX_DPUT |
Transfer the data from info to the current area. |
|
WIX_SAGET |
Transfer the screen attributes to info. (.NET, Unix, and OpenVMS only) |
|
WIX_SDGET |
Transfer the screen data to info. (.NET, Unix, and OpenVMS only) |
For WIX_APUT and WIX_DPUT, the destination processing area must have the same dimensions as the source processing area. For WIX_SAGET and WIX_SDGET, the id argument is unused, but it is still required.
WIX_SDGET does not work on Windows. The data for each Synergy window is kept only within that window, and no global screen map is maintained.
Info is the alpha variable to which window information is saved and from which windows are restored. Info must be large enough to hold the contents of the current processing area; for each option, the length of the variable should equal the number of rows multiplied by the number of columns.
With the WI_XFR function, a program could save a processing area’s character attributes and data to disk. Later, a different program could read the information into a processing area with the same dimensions as the original processing area.
|
If you are using UI Toolkit, always set the processing area (using XCALL W_AREA) before you invoke any WI_XFR options, because a Toolkit routine may modify the processing area. |
In the following example, we use WIX_AGET and WIX_DGET to save the contents of a processing area before filling the processing area with dots. Then we use WIX_APUT and WIX_DPUT to restore the original data and attributes to the processing area.
.define MAXWINS, 15
.define WNDCHNL, 1
.include "WND:windows.def"
record
wndw_1 ,i4
attr ,a238
data ,a238
proc
open(WNDCHNL, o, "tt:")
xcall w_init(0, WNDCHNL, MAXWINS)
xcall w_proc(WP_CREATE, wndw_1, "window1", 11, 50)
xcall w_area(wndw_1, WA_FILL, "1234567890")
xcall w_proc(WP_PLACE, wndw_1, 12, 15)
xcall w_area(wndw_1, WA_SET, 3, 9, 7, 34, WA_BOX,
& WA_CHANGE, 1, 1, -2, -2, WA_FILL, "x")
call pause
xcall w_area(wndw_1, WA_SET, 3, 9, 7, 34)
xcall w_info(WI_XFR, wndw_1, WIX_AGET, attr)
xcall w_info(WI_XFR, wndw_1, WIX_DGET, data)
xcall w_area(wndw_1, WA_COPY, WAC_WTOP, WA_FILL, ".")
call pause
xcall w_area(wndw_1, WA_SET, 3, 9, 7, 34)
xcall w_info(WI_XFR, wndw_1, WIX_APUT, attr)
xcall w_info(WI_XFR, wndw_1, WIX_DPUT, data)
call pause
xcall w_exit
stop
pause,
xcall w_updt
sleep 1
return
end
