General windowing concepts

This topic includes the following sections:

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

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.

Important

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.

The non-interactive runtimes (dbs, dbssvc, and dbspriv) do not support the Synergy windowing API.

In Synergy .NET, the Unix-compatible (non-mouse) functionality of the Synergy windowing API for traditional Synergy is fully supported. You can set the SYN_RESIZE_SCALE environment variable to 1 to make the application window resizable and maximizable. For SDK-style projects, setting SYN_RESIZE_SCALE to 1 only works with Windows-specific versions of .NET (i.e., not .NET terminal applications).

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:

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:

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.

Scroll bars

On Windows, depending on the screen resolution being used, the number of rows and columns being displayed, the font used for the application window, and the setting of the MINIMIZE_LEADING environment variable, when an application starts up it may require more space than the screen affords.

If so, it will be limited to the available space, and a vertical or horizontal scroll bar will be displayed to allow the user to scroll to the unseen area of the application window. Rather than enlarging the application window to add the scroll bar, the scroll bar occupies part of the initial size of the application window, in order to avoid unpleasant resizing of the application window upon startup or whenever the scroll bars are removed.

Because of this, however, it is likely that the addition of one scroll bar (for instance, the vertical one) will result in the addition of the other (for instance, horizontal) scroll bar, so that the user can view the portion of the application which was just occluded by the first scroll bar. To eliminate the second scroll bar, the user can stretch the application window along that scroll bar’s axis until it disappears.

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.

Note

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_ITAL = Italic

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_ITAL = Skip italic.

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.

Note

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

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

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

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

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:

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

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:

Default User Colors

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:

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. These differences are described in the topics for the individual Synergy windowing API routines.

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:

Window definitions

The windowing system uses a series of definitions to interpret windowing code. These definitions reside in files named wxxxx.def, where xxxx 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: warea.def, wbrdr.def, wdisp.def, wflds.def, winfo.def, wmisc.def, wproc.def.

We also distribute a file named windows.def, which includes all of the Synergy windowing subroutine definitions. Every routine that uses windowing subroutines must .INCLUDE the windows.def file, so we recommend that you just use windows.def rather than the individual wxxxx.def files. 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:

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.