W_PROC

General window processing

xcall W_PROC(function, arguments[, function, arguments][, ...])

Arguments

function

One or more of the following functions:

WP_CHILD = Define a parent-child relationship.

WP_CPYBLK = Copy blocks of text and attribute data between windows.

WP_CREATE = Create a window.

WP_CURSOR = Turn the cursor on or off and set its position.

WP_DELETE = Delete a window.

WP_FIND = Search for a window with the specified name or number.

WP_MARGIN = Manipulate screen margins.

WP_MOVE = Move a window relative to the most recent placement.

WP_OPTION = Control hardware scrolling.

WP_OVERLAY = Overlay a window.

WP_PALET = Change color characteristics.

WP_PLACE = Place a window’s display area on the screen.

WP_POSITION = Set the application window’s position on the screen.

WP_REDRAW = Set a flag so the screen is redrawn on the next screen update.

WP_REMOVE = Remove a window from the screen.

WP_RESIZE = Resize a window or the screen.

WP_SIZE = Change the size of a Synergy window. (traditional Synergy only)

WP_STATE = Set the state for a window.

WP_TOFRONT = Bring a window to the front of the placement order without moving it.

arguments

(optional) Any arguments used by the specified function.

Discussion

W_PROC is the general window processing subroutine. See the individual subfunctions for details.

If you use ^VARARGARRAY, function is the last declared argument for this routine.

WP_CHILD

WP_CHILD, child_id, parent_id

WP_CHILD declares a parent-child relationship between two windows. When a window is the child of another window, its existence depends in every way upon the parent window:

The placement of the child window is relative to the screen placement position of the parent window (as opposed to being relative to the screen origin), which means that placement coordinates may be negative.
If a parent window is moved, all of its child windows move accordingly.
If a parent window is removed from the screen, all of its child windows are removed from the screen.
If a parent window is deleted, all of its child windows are deleted.
If a removed parent is placed, the child windows are physically placed if they had been explicitly (logically) placed before. Placing a child window when the parent is removed does not affect the screen.

To terminate a parent-child relationship, specify zero as the parent ID. When a parent-child relationship is terminated, the child window is removed from the screen.

When WP_CHILD is performed, the window is removed. You can make the window reappear at the previous placement coordinates using

xcall u_window(D_REMOVE, child, D_MOVE, child, 0, 0)

or, if not logged with UI Toolkit, using

xcall w_proc(WP_REMOVE, child, WP_MOVE, child, 0, 0)

WP_CPYBLK

WP_CPYBLK, from_id, to_id

WP_CPYBLK copies blocks of text and attribute data between windows relative to the processing areas. From_id is the ID of the window from which you want to copy text and attributes, and to_id is the ID of the window to which you want to copy this data. The text and attributes within the processing area of from_id are copied to the processing area of to_id. The data is copied left- and top-justified, with truncation and over non-attribute blanks.

When copying text and attributes between windows, the window data areas must be different. If from_id and to_id specify the same window ID, or if both IDs are for overlay windows with the same data, the windowing system ignores the copy request made by WP_CPYBLK.

WP_CREATE

WP_CREATE, id, name, height, width

WP_CREATE creates a window, identifying it with an ID and a name, and defines its size in rows and columns. After you’ve initialized the windowing system with W_INIT, the WP_CREATE function is the first one you need to use to make and display a window. The window is initially blank.

Id is a numeric field that is returned with the window’s ID. The system automatically assigns a number to the variable you specify. This way, the system keeps track of the actual number of the window. In other functions acting upon this window, you simply supply the argument named here.

Name is an alpha expression with a maximum of 15 characters that contains the window’s name. This argument is useful when you’re not sure of the window ID. For example, you might have a standard help window that you want to use in many programs. When you chain to a new program (within a bound program), you may not know the window ID, but you can use the name in the WP_FIND function to search for and identify the window you need. If a null string is specified for name, a unique window name is automatically generated in the form “_W_nnn”, where nnn is the ID of the window that is being created.

Height is a numeric expression that contains the number of rows deep the window will be. Width is a numeric expression that contains the number of columns wide the window will be. If this field contains a value of zero, for either height or width, the windowing system defaults to the screen height and width.

In the following example, we create a window whose ID is stored in window and whose name is stored in choice. (Notice that we initialize the field choice with the name “Choices,” but we don’t furnish the numeric ID for the window. The system automatically assigns a number ID to the field window.) The window we’ve created is 11 rows deep and 50 columns wide.

From now on, we can access this window with the ID window. If the ID is unknown by another routine, we can use the name in the WP_FIND function to determine if a “Choices” window exists.

.define WNDCHNL,        1
.define MAXWINS,        4
.include "WND:windows.def"
record
    window              ,i4
    choice              ,a7     ,"Choices"

proc
    open(WNDCHNL, o, "tt:")
    xcall flags(7004020, 1)
    xcall w_init(0, WNDCHNL, MAXWINS)
    xcall w_proc(WP_CREATE, window, choice, 11, 50)

WP_CURSOR

WP_CURSOR, option

WP_CURSOR sets the cursor for a window, captures the cursor to a window, or sets the cursor’s position following a call to W_UPDT or W_EXIT. When the windowing system is initialized, the cursor display is on and the position is row 1, column 1.

The WP_CURSOR position does not apply to terminal input. On terminal input, the cursor is positioned to wherever the input is requested on the screen.

Option is one of the following (discussed below): WPC_CAPTURE, WPC_LVCSR, WPC_OFF, WPC_ON, WPC_POS, WPC_SET.

WPC_CAPTURE

WP_CURSOR, WPC_CAPTURE, window_id

WPC_CAPTURE captures the cursor to a specified window, giving the window exclusive control of the cursor. Establishing capture to a window releases capture from any window that previously held the cursor.

Window_id is either the ID of a window or one of the following:

WID_CONTAINER	The container window for the Synergy application, including the border and caption.
WID_APP	The application window, excluding the border and caption.
WID_NONE	No window has capture of the cursor.

WPC_LVCSR

WP_CURSOR, WPC_LVCSR

This option leaves the cursor at the current position on a W_UPDT.

WPC_OFF

WP_CURSOR, WPC_OFF

The cursor is off. Valid for traditional Synergy only,

WPC_ON

WP_CURSOR, WPC_ON

The cursor is displayed. (Default)

WPC_POS

WP_CURSOR, WPC_POS,screen_row, screen_col

This option positions the cursor at the screen coordinates, not the window coordinates. Screen_row and screen_col are numeric expressions. WPC_POS turns off the WPC_LVCSR option.

WPC_SET

WP_CURSOR, WPC_SET, window_id, cursor

This option determines what the cursor looks like as it passes over the specified window.

Modal window calls such as U_MESSAGE, %U_MSGBOX, and U_ABORT force the cursor to revert to a normal arrow.

Window_id is either the ID of a Synergy window or one of the following:

WID_CONTAINER	The container window for the Synergy application, including the border and caption.
WID_APP	The application window, excluding the border and caption.

Cursor is one of the following identifiers:

WPCS_ARROW	Normal arrow cursor
WPCS_IBEAM	I-beam (text caret)
WPCS_WAIT	Wait cursor (hourglass)
WPCS_CROSS	Cross hair
WPCS_UPARROW	Vertical arrow
WPCS_SIZENWSE	Diagonal sizing arrows (\)
WPCS_SIZENESW	Diagonal sizing arrows (/)
WPCS_SIZEWE	Horizontal sizing arrows
WPCS_SIZENS	Vertical sizing arrows
WPCS_SIZEALL	Crossed sizing arrows (+)
WPCS_NO	Slashed circle
WPCS_APPSTARTING	Arrow with wait cursor
WPCS_HELP	“What’s this?” cursor
WPCS_HANDLE	An externally loaded cursor handle

The following macros are available in windows.def.

.define WP_HOURGLASS_ON
&       WP_CURSOR, WPC_CAPTURE, WID_CONTAINER
&       WP_CURSOR, WPC_SET, WID_CONTAINER, WPCS_WAIT

.define WP_HOURGLASS_OFF
&       WP_CURSOR, WPC_SET, WID_CONTAINER, WPCS_ARROW,
&       WP_CURSOR, WPC_CAPTURE, WID_NONE

These macros enable the following usage:

xcall w_proc(WP_HOURGLASS_ON)
.
.
.
xcall w_proc(WP_HOURGLASS_OFF)

Additionally, to determine what settings are currently in effect, use the WIF_CAPTURE and WIF_CURSOR codes of %W_INFO or the W_HOURGLASS_IS_ON macro. (See the %W_INFO Discussion for more information.)

In this example, we reposition the cursor so that it appears at the end of the displayed message, instead of at the upper-left corner of the screen.

wait,
    xcall w_proc(WP_CREATE, window, choice, 1, 15, WP_PLACE, window, 24, 32)
    xcall w_brdr(window, WB_OFF)
    xcall w_disp(window, WD_ATTR, ATTR_SET + ATTR_BLNK + ATTR_BOLD, 
  &       "Please wait...")


;Position cursor after the dots
    xcall w_proc(WP_CURSOR, WPC_POS, 24, 46)
    xcall w_updt
    return

WP_DELETE

WP_DELETE, id

WP_DELETE deletes the window with the specified ID, where id is a numeric expression. When the window is deleted, memory is released, and the window ID is no longer active.

WP_DELETE is not the same as WP_REMOVE. WP_REMOVE removes a window from the screen, but the window still exists, so it can be modified, placed again, and displayed. When a window is deleted, however, it is gone.

The example below deletes the window with the ID wndw_4.

xcall w_proc(WP_DELETE, wndw_4)

WP_FIND

WP_FIND, return_id, id_field

WP_FIND searches for a window with the name or number that you supply in id_field. If the window exists, return_id (which is a numeric variable) is loaded with the window’s ID so you can identify it in other functions. If the window doesn’t exist, return_id is loaded with a zero.

Id_field is either an alpha or numeric expression. If you are searching for a window by name, specify the name as alpha. If you know the actual window ID, specify it as numeric.

The following example code would appear at the beginning of a subroutine that was called from another program. We’ll assume we don’t know the ID of the menu window and use WP_FIND to determine the ID. Then we test the value of the return ID field (in this case, ret_id). If the value is zero, the window does not exist, and we can create a menu window. If the value is not zero, we know the window exists, and we can use the ret_id field as the window ID in other window functions.

subroutine menu
.include "WND:windows.def"
record
    win3                ,i4
    ret_id              ,i4
    menu                ,a*     ,"Menu"
proc
    xcall w_proc(WP_FIND, ret_id, menu)
    if (.not.ret_id) then
        xcall w_proc(WP_CREATE, win3, menu, 11, 50)
    else
        xcall w_proc(WP_PLACE, ret_id, 1, 1)

WP_MARGIN

WP_MARGIN, WPM_SET, top, bottom, left, right
WP_MARGIN, flag, id

WP_MARGIN sets the screen margins. This function has two forms. If the first argument is WPM_SET (which is defined in wproc.def), WP_MARGIN sets the screen margins, where top is the number rows for the top margin, bottom is the number of rows for the bottom margin, left is the number of columns for the left margin, and right is the number of columns for the right margin.

In the two-argument form of WP_MARGIN, flag is either WPM_ON or WPM_OFF (both defined in wproc.def). If you use this form, WP_MARGIN turns margin-sensitive screen placement on or off for the window specified by id. When margin-sensitive screen placement is turned on (WPM_ON), the specified window is placed relative to the current screen margins.

All screen margins are initially set to zero with margin-sensitive placement turned on.

If a window is placed and you change the screen margins or the margin-sensitive state of the window, the windowing system automatically shifts the placement of windows on the physical screen.

The following example changes the top screen margin to five rows, the bottom margin to one row, and the left and right margins to three columns each.

xcall w_proc(WP_MARGIN, WPM_SET, 5, 1, 3, 3)

Using this example, if you place a window at (1,1) and margin-sensitive placement is turned on, the window is physically placed at (6,4) on the screen.

WP_MOVE

WP_MOVE, id, row_change, column_change

WP_MOVE places the window’s display area relative to its most recent row and column position. If the window hasn’t been placed yet, the window’s default point of origin is row 1, column 1.

Id is a numeric expression that contains the window ID.

Row_change is a numeric expression that contains the number of rows you want to move the window up or down. A negative value moves the window up; a positive value moves the window down.

Column_change is a numeric expression that contains the number of columns you want to move the window left or right. A negative value moves the window to the left; a positive value moves the window to the right.

The position of the window is modified by WP_MOVE. If the window is not yet placed, WP_MOVE places the window at a new position at the top of the placement order. (See Window placement and occlusion for more information about window placement.) If the window is already placed, placement order is maintained and the window is shifted to the new position.

WP_MOVE adjusts the window position relative to the current position. WP_PLACE, however, sets the window position regardless of the current position.

The following example shifts a window around the screen, first moving it 50 columns to the right, and then moving it 6 rows down and 25 columns to the left. Notice that this program does not use WP_PLACE; WP_MOVE places the window first, and the row and column change is calculated with a default window origin of row 1, column 1.

.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", 10, 30)
    xcall w_area(wndw_1, WA_FILL, "1234567890")
    xcall w_brdr(wndw_1, WB_OFF)
    xcall w_proc(WP_MOVE, wndw_1, 0, 50)
    call pause
    xcall w_proc(WP_MOVE, wndw_1, 6, -25)
    call pause
    xcall w_exit
    stop
pause,
    xcall w_updt
    sleep 1
    return
end

If several windows are placed on the screen and you want to take the window at the bottom of the pile and place it on top, it’s easiest to remove the window first, and then move it with no row or column change. Since WP_MOVE actually places the window, you don’t need the WP_PLACE function; simply use WP_MOVE with no change of row or column position, and the window is placed on the top of the pile, in its original position. The example below illustrates this technique:

xcall w_proc(WP_REMOVE, window, WP_MOVE, window, 0, 0)

WP_OPTION

WP_OPTION, option

WP_OPTION controls hardware scrolling, which uses the capabilities of the terminal to do the scrolling. Option is one of the following:

WPO_JUMP	Emit VT100 escape sequences to set jump scroll.
WPO_SMOOTH	Emit VT100 escape sequences to set smooth scroll.
WPO_NOSCROLL	Explicitly turn off any scrolling region and hardware scrolling.
WPO_VSCROLL	Turn on vertical scrolling if possible, depending on the setting of TERM. See Hardware scrolling.
WPO_KEEPBRDR	Prevent window borders from being turned off because of the size of the window (Windows only).
WPO_HIDEBRDR	Restore the default border behavior after WPO_KEEPBRDR has been set.
WPO_COLORMAP	Set one of the following attribute color mapping options: WPOC_ON = Turn on attribute color mapping. WPOC_OFF = Turn off attribute color mapping. WPOC_ULINE = Turn on underline attribute color mapping.

With WPO_JUMP or WPO_SMOOTH on Unix or OpenVMS, if the terminal type is neither VT nor XTERM, no escape sequences are sent to the terminal.

When turned on, the attributes BOLD, UNDERLINE, REVERSE and their combinations are mapped to the default 16 color palettes as defined in Colors and the color palette. These colors can be set up using WNDC or using the WP_PALET function of W_PROC.

The protected attribute selects the alternate mappings 9–16. This is to map the fact that most color terminals provide a different color set for protected characters.

Mappings are as follows:

Attribute Mappings
Attribute combination	Palette
None	1
Bold	2
Underline	3
Bold Underline	4
Inverse	5
Inverse Bold	6
Inverse Underline	7
Inverse Underline Bold	8
Protected	The above palette mappings + 8

Blink uses the palette as defined above but also blinks the character (or uses italic on Windows). Color support with WD_COLOR is ignored when the WPO_COLORMAP mode is on. Protected attributes are ignored when in normal mode.

The color mapping is interpreted at runtime in the routine that decodes attributes. This routine is used only when screen updates occur. It does not affect individual windows, only the screen output.

If WNDC is not set, WPO_ COLORMAP is ignored. If WPO_COLORMAP is turned off, the protected attribute is ignored.

If a particular palette, which will be used by the attribute mapping, is not set, the mapping defaults to palette 1.

If WNDC is set on a monochrome terminal, the color sequences are still output. It is the terminal’s job to ignore sequences that it does not support (in fact, this is the ANSI standard for escape sequences).

The user will set WNDC and can then use WPO_COLORMAP as a toggle. Any screen update (rather than individual window) from that point on interprets the attributes as per the setting. If the whole screen is to be updated after changing WPO_COLORMAP, it is suggested that the W_PROC function WP_REDRAW be used.

When WPO_COLORMAP is on, WD_ANSI recognizes the protected mode escape sequences.

When using the protected attribute you should not turn off WPO_COLORMAP unless all windows have been removed. The protected attribute conflicts with the color settings when WPO_COLORMAP is off.

WP_OVERLAY

WP_OVERLAY, existing_window, id, name

WP_OVERLAY overlays an existing window. A window overlay is similar to a Synergy DBL record overlay: the data, window size, and data attributes of the new window are the same as the overlaid window. You can change all other window attributes (such as border, title, and placement).

Existing_window is a numeric or alpha expression that contains the ID or name of the original window.

Id is a numeric variable that contains the window ID of the new overlay window.

Name is an alpha expression that contains the name of the overlay window.

The following example program creates an overlay window, wndw_2, which overlays wndw_1. When we first overlay wndw_2, it contains the same data as wndw_1. When we fill wndw_2 with different data, the data changes in wndw_1 as well, because overlaid windows have the same window size, data, and data attributes as the window that overlays them. Notice that we can place wndw_2 separately from wndw_1; we can also alter other window attributes, such as border.

.define MAXWINS,        15
.define WNDCHNL,        1
.include "WND:windows.def"
record
    wndw_1              ,i4
    wndw_2              ,i4
proc
    open(WNDCHNL, o, "tt:")
    xcall w_init(0, WNDCHNL, MAXWINS)
    xcall w_proc(WP_CREATE, wndw_1, "window1", 8, 20)
    xcall w_area(wndw_1, WA_FILL, "1")
    xcall w_proc(WP_PLACE, wndw_1, 10, 5)
    call pause
    xcall w_proc(WP_OVERLAY, wndw_1, wndw_2, "window2", WP_PLACE, wndw_2, 15, 31)
    call pause
    xcall w_area(wndw_2, WA_FILL, "2")
    xcall w_exit
    stop
pause,
    xcall w_updt
    sleep 1
    return
end

WP_PALET

WP_PALET, color, background, foreground

WP_PALET changes the color characteristics of the color palette entry stored in the color argument.

Color is a numeric expression that contains a color palette number between 1 and 16. The colors that correspond to the palette numbers are system specific. See Colors and the color palette for more information. For WP_PALET support in SDK-style projects on Linux, the WNDC environment variable must be set in the environment.

Background is a three-digit numeric expression that contains the number of the new background color. Foreground is a three-digit numeric expression that contains the number of the new foreground color. The background and foreground numbers can be between 0 and 511 on Windows and between 0 and 255 on Unix and OpenVMS; the significance of the values is system specific. (On Windows, these values are Synergy DBL colors, which can be defaults set by the Synergy runtime or overrides set by the COLORn environment variables or previous calls to W_PROC. On Unix and OpenVMS, the way they are assigned varies.)

WP_PLACE

WP_PLACE, id, row, column

WP_PLACE places a window’s display area on the screen with the upper-left corner at the row and column designated by row and column. Id is a numeric expression that contains the ID of the window whose display area is to be placed. You must place a window on the screen before you can display it.

The position of the window is specified by WP_PLACE. If the window is not yet placed, WP_PLACE places the window at a new position at the top of the placement order. (See Window placement and occlusion for more information about window placement.) If the window is already placed, placement order is maintained and the window is shifted to the new position.

Placing a window that was previously hidden restores the window to its previous state, which by default is normal.

WPS_NORMAL	Restore the window to its normal state.
WPS_MAXIMIZED	Maximize the window.
WPS_MINIMIZED	Minimize the window.
WPS_HIDDEN	Hide the window.