General windowing concepts
This topic includes the following sections:
- Window IDs and names
- Window I/O
- Screen updates
- Window areas
- Window placement and occlusion
- Overlay windows
- Terminal I/O
- Attributes
- Colors and the color palette
- Windowing subroutines on Windows platforms
- Windowing API and UI Toolkit
- Window definitions
- Hardware scrolling
- User data sets
The Synergy windowing API enables you to add windows to your applications and manipulate their properties and attributes. UI Toolkit uses these low-level windowing routines as the foundation for its subroutines, which are more user-friendly. For more information about Toolkit, refer to the UI Toolkit Reference or ask your Synergex account executive.
The Synergy windowing API (and, therefore, UI Toolkit) uses the default terminal channel, which is opened automatically when the program starts. When an OPEN(chn, i, "TT:") or OPEN(chn, o, "TT:") is performed, that channel number is mapped to the default terminal channel. When the channel is closed, the mapping is removed. The default terminal channel is closed only when the program exits.
On OpenVMS, the default terminal channel opens SYS$INPUT and SYS$OUTPUT for input and output. When running a windowing API or Toolkit program from a command file, if you want to get input from the terminal device instead of the command file, add the line $ define/process sys$input sys$command before the command line where you run your windowing API or Toolkit program. |
Window IDs and names
Most of the window functions require a window ID argument that identifies the window you want to access. When you create a window, you must supply a numeric variable that will be loaded with the numeric window ID. The Synergy DBL system then assigns a numeric ID to each window and loads the value in the numeric variable, so you can easily access each window by its variable without having to keep track of the actual number assigned to it. Although a d4 or i2 ID variable is usually large enough to contain the assigned number, we recommend that you use an i4 variable for faster access. Window IDs can be as large as 1024 characters.
When you create a window, you must also supply a name for that window. For example, you might assign the name “Help” to a window that will contain help information or “Menu” to a window that will contain a menu. By assigning the window a generic name such as “Help” or “Menu,” you can later search for a window by its name with the WP_FIND function. The name and the WP_FIND function are especially helpful when you chain to a new program; you can determine if the window you need exists before you create a new one.
Window I/O
The windowing system is conceptually divided into two elements: a logical screen per window and the physical screen. When you modify a window or its contents, the changes affect its logical screen, which is simply a group of memory locations to store information about the windows. The change doesn’t affect the actual display, unless the window is visibly placed and you update the screen.
You can change information in a window without having the window displayed. But if you want to see these changes on the physical screen, you must first update the screen. In most situations, the windowing system’s implicit screen updating capabilities automatically update the screen when it is appropriate.
Screen updates
The screen is normally updated in these five ways:
- Explicitly with W_UPDT
- Explicitly with the WD_UPDT function of W_DISP
- Implicitly with W_EXIT
- Implicitly when the program accepts terminal input with the window I/O functions WD_READS, WD_ACCEPT, WD_GETS, and WF_INPUT. These functions automatically update the screen before they accept input.
- Implicitly when the WD_BELL function is used to sound the bell
The screen is also implicitly updated by the WA_INSERT and WA_SCROLL functions when hardware scrolling is in effect or WD_WRITES if a scroll is required.
A screen update simply copies the visible changes in the placed windows to the physical screen. Unless you request a screen redraw with the WP_REDRAW function, only the information that has changed is changed on the physical screen; information that was already displayed remains on the physical screen as long as the new information doesn’t occupy the same space.
Window areas
A window has three areas:
- The total window area, which is the size of the entire window and is specified by the WP_CREATE function
- The display area, which is the part of the window that is visible on the screen and is a subset of the total area
- The processing area, which is the part of the window that is modified by routines such as W_AREA and is also a subset of the total area
When you create a window, the default display area is as large as the total window area. The border is drawn around the display area, not inside it. You can change the size of the display area by using the WA_COPY function to copy the processing area’s parameters to the display area. You can also copy the total window area’s parameters to the display area to restore the original display area size.
On creation, the processing area, like the display area, is equal to the total window area. You can change the size of a processing area with three functions: the WA_SET function, which explicitly sets the size of the processing area; the WA_CHANGE function, which changes the size of the processing area relative to the current size; and the WA_COPY function, which can copy the parameters of the display area or the total window area to the processing area.
Window placement and occlusion
You can occlude, or overlap, windows with other windows by placing one window over all or part of another window. The last window placed on the screen is the highest in the placement order and occludes the portion of any previously placed window that it overlaps. When a window is occluded, the part that lies beneath the top window is obscured. When the top window is moved or removed, the obscured portion is visible again.
When you change the data in an occluded window, those changes that aren’t covered up are reflected after the next screen update. Changes to the occluded portion of the window are visible when the window is no longer occluded.
Overlay windows
You can overlay windows, which is similar to overlaying a Synergy DBL record. The data, window size, and data attributes of the new window are the same as the overlaid window. However, you can alter all of the other window attributes, such as border, title, and placement.
Terminal I/O
Once you initialize the windowing system, all terminal I/O must pass through the system if you want the system to recognize the data. In other words, you must use the window display subroutine, W_DISP, to receive information from the terminal and display it in a window. The one exception is the output of nonprinting characters and redirected output.
You can use the other Synergy DBL statements, such as DISPLAY, ACCEPT, and READS, for terminal I/O while the windowing system is running, but the windowing system won’t have access to any data obtained outside the system. We recommend that you avoid mixing window and nonwindow terminal I/O statements on the same interactive desktop surface.
On Windows, redirected input/output (stdin/stdout) can only be read or written using ACCEPT, READS, DISPLAY, and WRITES. WD_ACCEPT and WD_READS only retrieve and display input from the desktop window. We recommend that you not use dbr.exe for scheduled tasks and instead use dbs.exe for input and output with WRITES, DISPLAY, READS, and ACCEPT with redirected stdin and stdout. |
Attributes
Many of the windowing routines have a function that alters the display attributes of a window element, such as the border, title, text, or processing area. After the routine-specific function name (such as WD_ATTR or WB_ATTR), all of these functions use the same attribute specifications. An attribute specification has the following format:
...WX_ATTR, function + option [+ option ...]
function
One of the following functions:
ATTR_SET = Set attributes.
ATTR_CHNG = Change existing attributes.
ATTR_LOAD = Set listed attributes, ignore “skip” attributes, and clear the others.
ATTR_CLR = Clear attributes.
option
One of the following attributes. You can specify as many as you like, separated by plus signs.
ATTR_BOLD = Boldface
ATTR_BLNK = Blinking
ATTR_RVRS = Reverse video
ATTR_UNDR = Underline
ATTR_ALL = All of the above attributes
For ATTR_LOAD, option can also be one of the following skip attributes:
SKIP_BLNK = Skip blinking.
SKIP_BOLD = Skip boldface.
SKIP_RVRS = Skip reverse video.
SKIP_UNDR = Skip underline.
For example, to set reverse video in a window border, use W_BRDR with the WB_ATTR function, the ATTR_SET function, and the ATTR_RVRS option. Your statement should look something like this:
xcall w_brdr(wndw_1, WB_ATTR, ATTR_SET + ATTR_RVRS)
To display some text in boldface type, you might use the statement:
xcall w_disp(wndw_1, WD_ATTR, ATTR_LOAD + ATTR_BOLD, "Displayed in bold")
All input characters that are echoed have the current default display attributes (including color) of the window in which the input is occurring.
Because italic is the Windows implementation of blinking (and blinking is the UNIX and OpenVMS implementation of italic), ATTR_BLNK is synonymous with ATTR_ITAL, and SKIP_BLNK is synonymous with SKIP_ITAL. |
ATTR_SET turns on the attribute options that follow. You can set more than one attribute at a time. If you specify an attribute that’s already set, it remains set. Any attribute not specified remains unchanged. For example, the following causes displayed text to include the underline and reverse video attributes:
WD_ATTR, ATTR_SET + ATTR_RVRS + ATTR_UNDR
ATTR_CHNG toggles the attributes that are listed but has no effect on the attributes that aren’t listed. If the attribute is set, it is turned off; if it is not set, it is turned on. For example, if the text was previously displayed in boldface but now you want it to blink, use this function:
WD_ATTR, ATTR_CHNG + ATTR_BOLD + ATTR_BLNK
ATTR_LOAD sets the listed attributes, ignores any skip attributes, and clears or resets the attributes that aren’t listed. For example, if you aren’t sure what the current title attributes are, but you know you want them to be reverse video, you could use the following function to set ATTR_RVRS and clear all other attribute options:
WB_TATTR, ATTR_LOAD + ATTR_RVRS
The following example turns on reverse video, turns off boldface and blinking, and does nothing to the underline attribute.
WA_ATTR, ATTR_LOAD + ATTR_RVRS + SKIP_UNDR
ATTR_CLR turns off the attribute options that follow. You can clear more than one attribute at a time. If you specify an attribute that is already cleared, it remains cleared. Any attribute that is not specified remains unchanged. For example, to clear all border attributes, use this:
WB_ATTR, ATTR_CLR + ATTR_ALL
Colors and the color palette
To support color for the windowing subroutines, Synergy DBL uses a color palette and, on Windows, its own set of color definitions.
The color palette is made up of 16 pairs of color settings. These pairs are called color palette entries, are numbered 1 through 16, and include a foreground color setting (which is used for text) and a background color setting. Most windowing subroutines that set or retrieve colors accept only color palette entry numbers (1 through 16) as arguments. For example, to instruct W_FLDS to change the color of a field, you must pass a color palette entry number as the color argument to WF_COLOR. (W_FLDS, a WF_COLOR function, applies the background color for the palette entry to the field’s background, and it applies the foreground color to text that appears in the field.)
On Windows, the foreground and background settings for color palette entries correspond to Synergy color definitions, and the Synergy runtime loads a default color palette and default color definitions into memory when it starts. See Colors and the color palette on Windows for more information.
On UNIX and OpenVMS, your application will have color only if you create a color palette by setting the WNDC environment variable. See The color palette on UNIX and OpenVMS.
Note the following:
- UI Toolkit also uses the color palette and Synergy colors. For information on how UI Toolkit uses these and on UI Toolkit routines that can modify them, see Customizing the look of your application.
- The color palette and the Synergy color definitions cannot be used with the Synergy ActiveX API or the Synergy Windows Printing API. To specify colors for these, use RGB triplets.
Colors and the color palette on Windows
On Windows, a default color palette (with 16 default color palette entries) and a default set of Synergy color definitions (color 0 through color 511) are loaded into memory when the Synergy runtime starts. The default color palette contains the following entries:
Color palette entry number |
Foreground (text) color |
Background color |
---|---|---|
1 |
264 |
271 |
2 |
0 |
15 |
3 |
264 |
271 |
4 |
0 |
15 |
5 through 8 |
0 |
7 |
9 |
264 |
276 |
10 through 15 |
0 |
7 |
16 |
0 |
15 |
You can override the default color palette entries by using the PALETTE setting or the WP_PALET function for W_PROC.
The foreground and background settings for color palette entries correspond to Synergy color definitions, which are RGB triplets assigned to color numbers. There are three types of Synergy colors:
- User colors (color 0 through 255)
- System colors (color 256 through 285)
- Reserved colors (color 286 through 511)
User colors
Synergy colors 0 through 255 are user colors, which are colors you can change by using the COLORn setting or by using the Renditions option for Proto or Synergy UI Toolkit Control Panel (synctl), which uses the Toolkit routine U_EDITREND.
The following table lists the default user colors on Windows:
Color number |
Hexadecimal RGB value |
Decimal RGB value |
Name |
---|---|---|---|
0 |
0x00,0x00,0x00 |
0,0,0 |
Black |
1 |
0x00,0x00,0xFF |
0,0,255 |
Blue |
2 |
0x00,0xFF,0x00 |
0,255,0 |
Lime |
3 |
0x00,0xFF,0xFF |
0,255,255 |
Cyan |
4 |
0xFF,0x00,0x00 |
255,0,0 |
Red |
5 |
0xFF,0x00,0xFF |
255,0,255 |
Fuchsia |
6 |
0xFF,0xFF,0x00 |
255,255,0 |
Yellow |
7 |
0xFF,0xFF,0xFF |
255,255,255 |
White |
8 |
0x80,0x80,0x80 |
128,128,128 |
Gray |
9 |
0x00,0x00,0x80 |
0,0,128 |
Navy |
10 |
0x00,0x80,0x00 |
0,128,0 |
Green |
11 |
0x00,0x80,0x80 |
0,128,128 |
Teal |
12 |
0x80,0x00,0x00 |
128,0,0 |
Maroon |
13 |
0x80,0x00,0x80 |
128,0,128 |
Purple |
14 |
0x80,0x80,0x00 |
128,128,0 |
Olive |
15 |
0xC0,0xC0,0xC0 |
192,192,192 |
Silver |
16 through 255 |
0x00,0x00,0x00 |
0,0,0 |
Black |
System colors
Synergy colors 256 through 285 are system colors, which correspond to Windows system colors and can be changed only through Windows mechanisms (Windows Control Panel, for example). You cannot change these with the windowing API (or even with UI Toolkit routines). The following table lists the default system colors:
Color number |
Mnemonic |
Windows UI element |
---|---|---|
256 |
SYSCOLOR_SCROLLBAR |
Scroll bar, background |
257 |
SYSCOLOR_BACKGROUND |
Desktop (if no wallpaper) |
258 |
SYSCOLOR_ACTIVECAPTION |
Active Title Bar, background |
259 |
SYSCOLOR_INACTIVECAPTION |
Inactive Title Bar |
260 |
SYSCOLOR_MENU |
Menu |
261 |
SYSCOLOR_WINDOW |
Window, background |
262 |
SYSCOLOR_WINDOWFRAME |
Active Window Border and Inactive Window Border |
263 |
SYSCOLOR_MENUTEXT |
Menu, font settings |
264 |
SYSCOLOR_WINDOWTEXT |
Window, font settings |
265 |
SYSCOLOR_CAPTIONTEXT |
Active Title bar, font settings |
266 |
SYSCOLOR_ACTIVEBORDER |
Active Window Border |
267 |
SYSCOLOR_INACTIVEBORDER |
Inactive Window Border |
268 |
SYSCOLOR_APPWORKSPACE |
Desktop |
269 |
SYSCOLOR_HIGHLIGHT |
Selected Items, background |
270 |
SYSCOLOR_HIGHLIGHTTEXT |
Selected Items, font settings |
271 |
SYSCOLOR_3DFACE |
3D Objects, face color |
272 |
SYSCOLOR_3DSHADOW |
3D Objects, shadow |
273 |
SYSCOLOR_GRAYTEXT |
Menu, disabled settings |
274 |
SYSCOLOR_BTNTEXT |
3D Objects, font settings |
275 |
SYSCOLOR_INACTIVECAPTIONTEXT |
Inactive Title Bar, text |
276 |
SYSCOLOR_3DHIGHLIGHT |
3D Objects, highlight color |
277 |
SYSCOLOR_3DDARKSHADOW |
3D Objects, dark shadow |
278 |
SYSCOLOR_3DLIGHT |
3D Objects, light color |
279 |
SYSCOLOR_INFOTEXT |
Tool Tip, font settings |
280 |
SYSCOLOR_INFOBK |
Tool Tip, background color |
281 |
SYSCOLOR_HOTLIGHT |
Selected Items, background color |
282 |
SYSCOLOR_GRADIENTACTIVECAPTION |
Active Title Bar and Inactive Title Bar, Color2 (right-side color of gradient captions) |
283 |
SYSCOLOR_GRADIENTINACTIVECAPT |
Active Title Bar and Inactive Title Bar, Color (left-side color of gradient captions) |
284 |
SYSCOLOR_MENUHILIGHT |
Selected Items (highlight color for menus when shown flat) |
285 |
SYSCOLOR_MENUBAR |
Menu (color when shown flat) |
Reserved colors
Synergy colors 286 through 511 are reserved for future Windows system colors. These are all set to black (0,0,0) and cannot be changed. (As system colors are added to Windows in the future, Synergex will assign these colors to the new Windows system colors.)
The color palette on UNIX and OpenVMS
You can enable color on UNIX and OpenVMS by setting the WNDC environment variable. The assigned string defines the default color palette. The format of the command varies according to your operating system and shell. For example, on UNIX, the command looks like this:
WNDC=palette1, palette2, ..., palette16
You can override color palette entries set by WNDC with subsequent WNDC statements or by using the WP_PALET function for W_PROC.
On UNIX, if colors are not defined by the system’s termcap file, use the ANSICOLOR environment variable to instruct the runtime to use its own internal ANSI color sequences.
Windowing subroutines on Windows platforms
Some of the windowing subroutines may exhibit differences between character-based environments and graphical environments. Refer to "Synergy windowing API routines" in the “Windows Development” chapter of your Professional Series Portability Guide (PDF) for information about these differences.
We recommend that you use a fixed font when using the Synergy windowing API on Windows platforms. In Synergy .NET, the default font is Consolas, for better scaling.
Windowing API and UI Toolkit
Although most of the windowing subroutines work normally within a UI Toolkit environment, some behave differently. Because Toolkit manipulates the windowing subsystem extensively, some windowing subsystem parameters may be reported with unexpected values. For example, Toolkit may create additional windows, or additional fields in a window, thereby causing the metrics returned by W_INFO to be misleading. If a window is loaded with five fields, Toolkit will create between 10 and 15 fields: one for each data field, one for each prompt field, and possibly one for each format string that may be associated with the field. (Prior to Synergy/DE 7, the same window reported 5 to 15 fields, depending on the number of user-definable prompts and/or formats.)
Follow these guidelines when using the Synergy windowing API with UI Toolkit:
- The number of windows in the environment is not always equal to the number of windows loaded.
- The number of fields within a window is not always the number of fields in the script file created by the IB_ routines.
- Avoid directly manipulating a field for your own purposes. Toolkit assumes that it owns the field and may not recognize your changes.
- Avoid using a user data set name that starts with “DTK_”. These are reserved for use by Toolkit.
- Avoid using W_PROC to place, remove, or delete windows. Doing so will circumvent some of the Toolkit logic, therefore causing unexpected results.
- If you require access to particular data from Toolkit and the windowing subroutines are not reporting the “correct” value, contact Synergy/DE Developer Support.
- On Windows, when using proportional fonts, any change to color or attributes within the window text will cause justification to occur at the pixel coordinate of the logical (cell-based) column. This may produce a confusing display.
- Synergex reserves the right to use the windowing routines in the most appropriate way for Toolkit. Do not rely on information such as number of windows, number of fields, and current field number to remain constant. The internals of UI Toolkit are not published, and therefore, changes to the internals are not documented. This means that you will not get a “this may break your code” warning when something changes.
Window definitions
The windowing system uses a series of definitions to interpret windowing code. These definitions reside in files named wxxx.def, where xxx corresponds to the name of the windowing subroutine. For example, warea.def contains definitions particular to W_AREA, wbrdr.def contains definitions particular to W_BRDR, and so forth. These files are included with your Synergy DBL distribution.
We also distribute a file named windows.def, which includes all of the Synergy windowing subroutine definitions. We recommend that you .INCLUDE windows.def rather than the individual wxxx.def files.
Every routine that uses windowing subroutines must .INCLUDE the windows.def file. For example:
.include "WND:windows.def"
Hardware scrolling
Hardware scrolling, which uses terminal scrolling capabilities to move data on the screen, only occurs under the following conditions:
- The display area is the same as the processing area.
- The display area is the same as the width of the screen, with or without a border.
- The window is not occluded.
- You’re on a VT-style (VT100, VT200, and so forth), xterm, or other type of terminal with the appropriate termcap/terminfo information to set the scrolling region and scroll up or down (for example, with cs, sf, and sr entries). (UNIX only)
- The WA_INSERT or WA_SCROLL functions are used. (UNIX only)
On UNIX, vertical scrolling only requires the scrolling area to be a subset of the rows in the display area, as long as the whole display area is visible. We automatically turn on the scrolling capabilities by looking at the TERM environment variable when W_INIT is called. Vertical scrolling is automatically turned on when TERM equals one of the following values:
vt1xx
vt2xx
vt3xx
vt4xx
vt5xx
xterm
where xx represents any character(s) you want.
User data sets
The windowing system has a user data set facility. A user data set is a one-dimensional alpha array that is associated with a window and maintained within the window data area by the windowing system. You can completely control its parameters and contents.
To create, put data into, or get data from a user data set field, use the WF_USER, WF_UPUT, and WF_UGET functions in the W_FLDS subroutine. Use the WI_USER function to return information about a user data set.