W_INFO

Get information about the windowing system

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
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.

Discussion

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.

Note

You can optionally call the W_INFO subroutine as a function. See %W_INFO for a description of this function.

WI_ACTIVE

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

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

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

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

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

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

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

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:

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

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

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

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

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

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.

WIX_SDGET

Transfer the screen data to info. (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.

Important

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