Customizing the look of your application

This topic includes the following sections:

• The color palette and Synergy colors
• Renditions and rendition schemes

 

The color palette is a set of color settings used to specify colors for renditions (which are described below). On Windows, these settings are RGB triplets assigned to color numbers. On UNIX and OpenVMS, they are system-specific color numbers (or color codes for WNDC). See The color palette and Synergy colors below.

Renditions are combinations of colors and attributes for UI elements. Attributes are boldface, blinking (which is italic on Windows), reverse video, and underscore. You can set Toolkit renditions for types of UI elements, and in many cases, you can set renditions for a specific UI element. See Renditions and rendition schemes below.

Rendition schemes are sets of Toolkit renditions that you can modify, create, save, and restore. You can create, change, and delete rendition schemes, and you can save them to and load them from a rendition file. See Rendition schemes and Toolkit renditions for types of UI elements below.

The color palette and Synergy colors

The color palette consists of 16 pairs of color settings called color palette entries, which are used to specify colors for renditions. Color palette entries are numbered 1 through 16 and consist of a foreground setting (used for text) and a background setting. On UNIX and OpenVMS, the foreground and background settings correspond to system-specific color numbers (or color codes for WNDC). On Windows, they are RGB triplets assigned to color numbers.

There are three types of Synergy colors:

• User colors (color 0 through color 255), which are colors you can change by using U_EDITREND, U_MODREND, U_REND, the COLORn setting, or the Renditions option for Proto or Synergy UI Toolkit Control Panel (which both call U_EDITREND). See Redefining user colors (Windows) below.
• System colors (color 256 through color 285), which correspond to Windows system colors and are controlled by Windows.
• Reserved colors (color 286 through color 511), which are reserved for future Windows system colors. These are set to black (0,0,0) and cannot be changed.

On Windows, the Synergy runtime loads default Synergy colors and a default color palette when it starts. On UNIX and OpenVMS, there is no default color palette; you must define the initial color palette with the WNDC environment variable.

The color palette and Synergy color definitions, which are also used by the Synergy windowing subroutines, are more fully described in Colors and the color palette. The sections below list methods you can use with Toolkit applications to change or define the color palette and to change user colors.

Defining and modifying the color palette

You can override one or more of the color palette entries by doing one of the following:

• (Windows only) Use the PALETTE setting in synergy.ini or synuser.ini.
• Use U_EDITREND or the Renditions option for Proto or Synergy UI Toolkit Control Panel (synctl). Both use U_EDITREND. See Using the Palette Entry window (Windows) below.
• Use the WP_PALET function for W_PROC.
• (UNIX and OpenVMS only) Use the WNDC environment variable to define color palette entries.

Redefining user colors (Windows)

You can redefine Synergy color 0 through Synergy color 255, which are user colors, by doing one of the following:

• Use the D_SETCOLOR operation for the %U_WINCOLOR function.
• Use the COLORn setting in the synergy.ini or synuser.ini file. And use the %U_SAVELOG function to save a COLORn setting.
• Use U_EDITREND or the Renditions option for Proto or Synergy UI Toolkit Control Panel (both use U_EDITREND). See Using the Palette Entry window (Windows).

Renditions and rendition schemes

Renditions are combinations of colors and attributes (boldface, blinking, reverse video, and underscore) for UI elements, which make up the visible part of an application (backgrounds, scroll bars, borders, titles, etc.). You can set renditions for a specific UI element in some cases (e.g., for a particular field on a particular window), and you can set renditions for some types of elements. For example, Input Field Display is a set of color and attribute settings that apply to input fields. For a list of these renditions, see the Renditions table below.

You can set renditions with the following. Note that these are listed in order of precedence: settings in input methods override field-level settings, and so forth. (For more information, see Renditions for specific UI elements and Rendition schemes and Toolkit renditions for types of UI elements below.)

• Input methods (%IDISPLAY_METHOD or %IEDITFMT_METHOD) or published properties for ActiveX Toolkit lists.
• Field-level settings. These are set with .FIELD, IB_FIELD, I_FLDMOD, or U_HELPREND.
• U_REND, U_START, U_MODREND, or U_EDITREND. These set renditions for types of UI elements.
• Other script settings (.FILL, .TEXT, .BORDER, and so forth).

You can also use the Synergy windowing routines, such as W_DISP, to set colors and attributes, and these changes generally have precedence for screen updates that occur immediately after they are set. But note that settings made with windowing routines can later be overridden by calls to Toolkit routines.

Note the following:

• On Windows, most renditions are controlled by Windows and cannot be set by Toolkit applications.
• When a Toolkit application starts, the U_START subroutine sets default Toolkit renditions for types of UI elements as listed in the table below. Renditions set by U_START override most renditions specified in window scripts except for those marked as “No” in the “Override script?” column. (Note that the U_INITREND routine enables you to reset Toolkit renditions to these initial settings.)
• You can instruct Toolkit to override field-level rendition settings for the active input field with the Input Field Processing renditions during I_INPUT and I_INPFLD processing. See E_STATE for information.

Renditions
Toolkit rendition U_REND argument	U_START initialization			Affected platforms
	Override script?	Attributes	Palette
D_RND_DLG Dialog Box Body	Yes	N/A	1	All
D_RND_DLG_BDR Dialog Box Border	Yes	N/A	1	UNIX, OpenVMS
D_RND_FTR Screen Footer	Yes	Bold	5	UNIX, OpenVMS
D_RND_HDR Screen Headera	Yes	Bold	5	All
D_RND_HLP_BCK Help Window Body	No	N/A	N/A	All
D_RND_HLP_BRDR Help Window Border	No	N/A	N/A	UNIX, OpenVMS
D_RND_HLP_TTL Help Window Title	No	N/A	N/A	UNIX, OpenVMS
D_RND_INF Information Line	Yes	Reverse	6	UNIX, OpenVMS
D_RND_INP_BCK Input Window Backgroundb (includes prompts and other non-field text)	No	N/A	N/A	All
D_RND_INP_BDR Input Window Border	No	N/A	N/A	UNIX, OpenVMS
D_RND_INP_CLR Cleared Input Field (for non-active cleared input fields)	Yes	N/A	3	All
D_RND_INP_DSA Disabled Input Fieldc	Yes	N/A	3	UNIX, OpenVMS
D_RND_INP_DSP Input Field Display (for non-active read/write input fields)	Yes	Bold	3	All
D_RND_INP_PRC Input Field Processing d (for active input read/write input field)	Yes	Reverse	3	UNIX, OpenVMS
D_RND_INP_ROD Read-Only Input Field Displayc (for non-active read-only input fields)	Yes	Normal	3	UNIX, OpenVMS
D_RND_INP_ROP Read-Only Input Field Processingc (for active input field if it is read-only)	Yes	Reverse	3	UNIX, OpenVMS
D_RND_INP_TTL Input Window Title	No	N/A	N/A	UNIX, OpenVMS
D_RND_LST_DSA Disabled List	Yes	N/A	7	UNIX, OpenVMS
D_RND_LST_DSA_S Disabled Selected Item	Yes	Reverse	7	UNIX, OpenVMS
D_RND_LST_ENA Enabled List	Yes	Bold	7	UNIX, OpenVMS
D_RND_LST_ENA_B Enabled List Border	Yes	Bold	7	UNIX, OpenVMS
D_RND_LST_ENA_T Enabled List Title	Yes	Bold	7	UNIX, OpenVMS
D_RND_LST_FTR Enabled List Footere	Yes	Reverse	7	All
D_RND_LST_HDR Enabled List Headere	Yes	Reverse	7	All
D_RND_LST_SEL Selected Item in List	Yes	Bold, reverse	7	UNIX, OpenVMS
D_RND_MNU_DSA Disabled Menu Entry	Yes	Reverse	2	UNIX, OpenVMS
D_RND_MNU_ENA Enabled Menu Entry	Yes	Bold, reverse	2	UNIX, OpenVMS
D_RND_MNU_EQS Menu Entry Quick-Select	Yes	Bold, reverse, underline	10	UNIX, OpenVMS
D_RND_MNU_HQS Menu Header Quick-Select	Yes	Bold, reverse, underline	10	UNIX, OpenVMS
D_RND_MNU_SEL Selected Menu Entry	Yes	Bold	2	UNIX, OpenVMS
D_RND_MSG Message Window Body	Yes	Reverse	4	UNIX, OpenVMS
D_RND_MSG_BDR Message Window Border	Yes	Reverse	4	UNIX, OpenVMS
D_RND_SCR_BAR Scroll Bar	Yes	Reverse	8	UNIX, OpenVMS
D_RND_SCR_IND Scroll Bar Indicators	Yes	Bold, reverse	8	UNIX, OpenVMS
D_RND_SEL_BCK Selection Window Body	Yes	Remove reverse	N/A	UNIX, OpenVMS
D_RND_SEL_BDR Selection Window Border	No	N/A	N/A	UNIX, OpenVMS
D_RND_SEL_EQS Sel Wnd Quick-Selects	Yes	Underline	10	UNIX, OpenVMS
D_RND_SEL_SEL Select Wnd Selected Item	Yes	Add reverse	N/A	UNIX, OpenVMS
D_RND_SEL_TTL Selection Window Title	No	N/A	N/A	UNIX, OpenVMS
D_RND_WIN_BCK Generic Window Background	No	N/A	N/A	All
D_RND_WIN_BDR General Window Border	No	N/A	N/A	UNIX, OpenVMS
D_RND_WIN_TTL General Window Title	No	N/A	N/A	UNIX, OpenVMS
User Rendition 1 through User Rendition 5	Yes	None	1	All

Renditions for specific UI elements

There are some renditions you can set for specific UI elements (rather than types of UI elements):

• To apply help window renditions to a window that isn’t a help window, use U_HELPREND. (The help window renditions are Help Window Body, Help Window Title, and Help Window Border.)
• To set renditions for a specific input field, use the rendition qualifiers or arguments for .FIELD, IB_FIELD, or I_FLDMOD, or set them in a display method or an edit format method (see %IDISPLAY_METHOD and %IEDITFMT_METHOD).
• To set renditions for an ActiveX Toolkit list, use the published properties for ActiveX lists. See Published properties for ActiveX Toolkit lists.
• To set renditions for other UI elements (i.e., UI elements that are not fields), use .BORDER, .BOX, .FILL, .LINE, .TEXT, .TITLE, .WFIELD, T_SETUP, and %TS_TABSET. Additionally, you can use %U_SELPALETTE to enable users to select a color palette for a specific UI element (among other things), and you can also change color and attribute settings with the Synergy windowing routines, such as W_DISP. (See Synergy Windowing API for information.)

Rendition schemes and Toolkit renditions for types of UI elements

In addition to the renditions for specific UI elements, you can set renditions for types of UI elements. For example, the Read-Only Input Field Display renditions control the look of read-only input fields (though there may be overrides for individual fields, and the Read-Only Input Field Processing renditions may be used for an active read-only input field).

On UNIX and OpenVMS, there are 47 Toolkit renditions for types of UI elements. On Windows, there are only a few. In both cases, five of these are user-assigned Toolkit renditions. (See the Renditions table.) There are more on UNIX and OpenVMS because on these platforms Toolkit controls the look of all UI elements. On Windows, however, the Windows Control Panel and Windows settings and defaults control the look of most UI elements, leaving only nine UI elements for Toolkit renditions (plus the five user-assigned Toolkit renditions).

A full set of renditions is a rendition scheme. You can create, change, and delete rendition schemes, and you can save them to and load them from rendition files as described in the following table.

Working with Rendition Schemes
To…	Do the following…	For more information, see…
Create a rendition scheme	Start by modifying an existing rendition scheme. Then use U_SAVREND to save it to a new rendition file by passing the name of a non-existent file as the filename argument.	U_SAVREND
Load a rendition scheme from your Toolkit application	Use U_LDREND (if you want to specify a channel on which the file is open) or U_RSTREND (if you want to specify the filename or a rendition file rather than a channel).	U_LDREND U_RSTREND
Modify a rendition scheme from your application	Use U_REND.	U_REND
Save the current rendition scheme or a specified rendition scheme from your application	Use U_STOREND (if you want to specify a channel on which the rendition file is open) or U_SAVREND (if you want to specify the filename of the rendition file rather than a channel).	U_STOREND U_SAVREND
Enable your users to modify, load, save, or delete rendition schemes	Call U_MODREND or U_EDITREND from your application or give your users access to Synergy UI Toolkit Control Panel or Proto, both of which call U_EDITREND when you select “Renditions” from their menu. (See U_MODREND versus U_EDITREND below.)	Using the Renditions window (Windows) Using the U_EDITREND screens (UNIX and OpenVMS)
Manually modify, load, save, or delete rendition schemes	Open Synergy UI Toolkit Control Panel or Proto and select “Renditions” from the menu. This opens the Renditions screen, which enables you to do these things as well as modify color palette entries.	Using the Renditions window (Windows) Using the Palette Entry window (Windows) Using the U_EDITREND screens (UNIX and OpenVMS)

For Windows, note the following:

• You can bring color for Toolkit renditions under the control of Windows settings by assigning Synergy system colors to renditions. For information on system colors and the default palette entries, see Colors and the color palette on Windows.
• We recommend that you set the background colors for the Input Field Display renditions and the Input Window Background renditions to the same value. The default palette entries for these renditions are 3 and 1 respectively. (Incidentally, the default background settings for palette entries 3 and 1 on Windows are system colors.)

U_MODREND versus U_EDITREND

Both U_MODREND and U_EDITREND open the Renditions window, which enables users to load, change, save, and delete rendition schemes (as well as color palette entries). The difference is that while U_EDITREND automatically saves rendition changes to the loaded rendition (and can save them to a specified rendition scheme), U_MODREND just modifies the rendition scheme loaded in memory. U_MODREND doesn’t save the rendition scheme unless the user clicks the Save button and supplies a rendition scheme name.

Files and environment variables used for rendition schemes

The following files and environment variables are used with rendition schemes:

• dtkrnd.ism. A file that contains records defining various rendition schemes. The key for this file is the rendition scheme name. The maximum size of a rendition scheme name is 30 characters, and the scheme name is not case sensitive. A blank key is reserved for the working rendition scheme.
• DTKRND. An environment variable used to define an alternate location for dtkrnd.ism. Set this if you want to use the rendition file dtkrnd.ism from a directory other than the current one.
• DTKRNDFIL. An environment variable used to define an alternate location and name for the rendition file. Set this if you want to use a rendition file other than the default (dtkrnd.ism).

UI Toolkit looks for the rendition file as follows:

• If the DTKRNDFIL is defined, it determines the rendition file location and name.
• If DTKRNDFIL is not defined, UI Toolkit attempts to open the file as DTKRND:dtkrnd.ism.
• If Toolkit can’t open DTKRND:dtkrnd.ism, it attempts to open the file dtkrnd.ism in the current directory.

Customizing user-assigned Toolkit renditions

U_EDITREND, U_MODREND, and U_REND enable you to customize the five user-assigned Toolkit renditions, which are renditions that you and your users can assign to a type of element. (See Uses for user-assigned Toolkit renditions below.) If you call U_EDITREND or U_MODREND, you can specify the number of user-assigned renditions to be modified and, on UNIX and OpenVMS, their descriptions in the selection window and example windows in the Sample Windows screen section.

By default, the following is true on UNIX and OpenVMS:

• User-assigned renditions are not displayed for editing by either U_EDITREND or U_MODREND. By passing the optional parameter for the number of user-assigned renditions, you can activate from 1 to 5 of these renditions.
• Any active user-assigned rendition receives the description “User Rendition n” in the Select Screen Area selection window, where n is the user-assigned rendition number. By passing the optional array of user-assigned rendition descriptions, you can replace the default descriptions.
• Any active user-assigned rendition is presented in the Sample Windows screen area as a single-line, unbordered window that contains only the description of the rendition. You can optionally create your own sample windows for user-assigned renditions and pass their IDs in the optional user renditions window IDs parameter. If you do this, you must also specify which areas of the window to affect when the user modifies the rendition. You can specify the window body, border, title, or any combination thereof, and you can specify a single field number to affect, or you can specify all fields. See U_EDITREND and U_MODREND for more information.

Uses for user-assigned Toolkit renditions

User-assigned Toolkit renditions can be assigned to types of UI elements. For example, if you’ve written routines to create and maintain a checklist window of your own invention (like the one in figure 1), you can use user-assigned renditions to assign unique combinations of attributes and colors to the window background and text, to the border and title, and to the check mark character.

1. Window with user-assigned renditions.

For example, you could assign user rendition 1 as the rendition for the checklist body, user rendition 2 as the rendition for the border and title, and user rendition 3 as the rendition for the check mark character. The routines in your application that create and maintain these windows can call U_REND with the D_COPY argument to get the current settings for these renditions and then apply them to the windows.

Additionally, if you want to give your end users access to these renditions, you can tie a utility menu entry to a call to U_EDITREND within your application and tell U_EDITREND that three user renditions will be used. (A utility menu entry is one that begins with U_ and is handled by an EUTILS_METHOD routine.)

If your application runs on UNIX or OpenVMS, you can pass a three-element array of the descriptions for these renditions—for example, “Checklist Body,” “Checklist Border,” and “Checklist Check Mark.” These descriptions will then appear in the Select Screen Area window when U_EDITREND or U_MODREND is called, enabling users to modify them as they would any other Toolkit rendition.

UNIX and OpenVMS also enable you to customize the prototype for the window that will appear in the Sample Windows window when you call U_EDITREND or U_MODREND. To continue with the checklist window example above, you could create a window that looks just like the checklist window that your routines create and modify. (Note that it doesn’t need to be a functioning model of the window, and note that the sample check mark characters should be window fields created with the W_FLDS subroutine.) You would place this window at the position in the screen where you want it to appear when the user selects one of these renditions from the Select Screen Area window. Then, when you call U_EDITREND or U_MODREND, pass the ID of this window in all three elements of the sample window ID’s array.

• In the areas array, you would pass D_RND_AREA for the first element (to affect the window’s processing area), D_RND_BRDR+D_RND_TITLE for the second (to affect the border and title), and 0 for the third (because this will affect fields instead of an area).
• In the field_numbers array, you would pass 0 for the first two elements and WFN_ALL for the third element, so that all of your check marks will be affected by a change to this rendition. You have now integrated the renditions presentation for your new window class with the other classes of windows in UI Toolkit.

See U_EDITREND for additional information.

Using the Renditions window (Windows)

The Renditions window (figure 2) enables you to manually restore, modify, delete, and save rendition schemes. The Sample windows area shows how the current renditions will look. There are several ways to access this dialog:

• Call U_EDITREND.
• In Proto, select General > Renditions.
• In the Synergy UI Toolkit Control Panel (synctl), select Preferences > Renditions.

Note that on Windows, the Renditions menu entry for Proto or the Synergy UI Toolkit Control Panel will work only if DTKRND or DTKRNDFIL is set to a writable location outside of Program Files. If neither is set, selecting this menu entry will result in an error: "Unable to update rendition file: dtkrnd Renditions file is read-only."

2. Modifying a rendition.

To modify a rendition, do the following:

1.

To modify a rendition scheme other than the one that’s loaded, click Load and select the rendition scheme by name, or click Use Default if you want to switch to the default rendition scheme.

2.

Select a rendition by clicking one of the named squares under “Sample windows” or by selecting a rendition name from the “Screen area” list.

3.

To assign a different color palette entry to the Toolkit rendition, click one of the numbered squares under “Color palette.” For more information on modifying the color palette, see Using the Palette Entry window (Windows) below.

4.

Select any text attributes you want to assign to the rendition.

5.

Repeat step 2 through step 4 for each Toolkit rendition whose screen area you want to modify.

6.

To save the renditions as a rendition scheme that you can access later by name, click Save and specify a name.

7.

When you’re finished, click OK to exit the Renditions dialog box. The rendition scheme that is loaded when you click OK will become the new default.

Using the Palette Entry window (Windows)

You can use the Palette Entry Window to change the foreground (text) and background colors of any palette entry. (For other methods, see Defining and modifying the color palette.)

1.

In the Renditions dialog box, select the number for the palette entry you want to modify, and click the Change Colors button.

The Palette Entry window is displayed for the palette entry. (See figure 3.) This dialog box displays colors you can apply to the foreground or background for the palette entry. System colors correspond to Windows system colors and can be changed only from Windows Control Panel. User colors are Synergy colors that you can change by clicking the Define color button or by using the COLORn setting in synergy.ini or synuser.ini. (See COLORn for more information.)

If you make a change in this dialog box, Toolkit updates the corresponding entry in the [colors] section of synergy.ini or synuser.ini if “Save colors to initialization file” is checked in the Renditions window. If there is no existing [colors] section, Toolkit will create one.

2.

Click on a color in the “System colors” or “User colors” area.

3.

Click “Apply background” if you want to assign the color as the background for the palette entry, or click “Apply foreground” to assign the color to the foreground (used for text). Then click OK.

3. Assigning a color to a palette entry.

Using the U_EDITREND screens (UNIX and OpenVMS)

On UNIX and OpenVMS, if you call U_EDITREND or select General > Renditions in Proto or Preferences > Renditions in Synergy UI Toolkit Control Panel, Toolkit displays three windows:

• Select Screen Area
• Renditions
• Sample Windows

Modify a rendition scheme

1.

In the Select Screen Area screen, use the arrow keys to highlight the rendition name for the screen area you want to change. Then press Enter.

2.

In the Renditions window, use the arrow keys to move to the rendition you want to apply to (or remove from) the rendition and press Enter.

3.

When you’re finished selecting renditions for the current screen area, press the Exit shortcut.

4.

Repeat step 1 through step 3 for each screen area you want to modify.

5.

To save the renditions as a rendition scheme that you can access later by name, select Save rendition scheme from the Renditions menu and enter a name for your rendition scheme.

Loading an existing rendition scheme

1.

From the Renditions menu, select Load rendition scheme.

2.

In the Select Scheme window, use the arrow keys to highlight the scheme you want to load, and press Enter.

Assigning different colors to a palette entry

If you are using a color monitor and you have enabled color on your system, you can change colors when your cursor is on one of the color codes in the Renditions window. (For information on enabling color on your system, see WNDC.)

Each color palette entry has a background color code and a foreground color code, each of which can be from 0 to 255. These codes and the colors that they specify are system specific. For example, some systems use basic ANSI color codes, a few of which are listed in the table below:

Color	ANSI code
Black	0
Blue	1
Green	2
Cyan	3
Red	4
Magenta	5
Yellow	6
White	7

To change the background or foreground color for a palette entry,

1.

In the Renditions screen, use the arrow keys to move to the palette entry (under “Colors”) you want to modify.

2.

From the Renditions menu, select Change colors. The Color Codes screen is displayed.

3.

Enter the numeric codes for the colors you want applied to the background and foreground for the color palette entry.

The new background and foreground colors for the palette entry immediately go into effect, changing all screen areas that use the palette entry.

4.

When you are done modifying a color palette, you can continue to change renditions for the current screen area or press the Exit shortcut to return to the Select Screen Area window.