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.

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.

Examples

The example below indicates the entire array in the WI_ACTIVE function by naming the first element of the array (in this case, numwins).

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.

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).

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.

Examples

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.

WI_PLACEDreturns 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.

Examples

The example below indicates the entire array in the WI_PLACED function by naming the first element of the array (in this case, numwins).

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.)

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.

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.

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.

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.

Examples

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.