%U_WINCOLOR

Perform Windows‑specific color operations

WTSupported in traditional Synergy on Windows

 

 

 

value = %U_WINCOLOR(subfunction[, arg, …])

or

xcall U_WINCOLOR(subfunction[, arg, …])

Return value

value

On Windows, a value specific the to subfunction. On UNIX, always returns false. On OpenVMS, always returns true. (^VAL)

Arguments

subfunction

The operation to perform: (n)

D_CHOOSECOLOR

Display the Color dialog box with an initial color selection.

D_GETCOLORS

Return RGB values associated with Synergy colors.

D_HYPER_FG

Return the RGB value for Toolkit hyperlink prompts.

D_PALETTE_RGB

Return the foreground and background colors (as RGB values) for a Synergy palette entry.

D_SETCOLOR

Use an RGB value to set a Synergy color.

arg

(optional) One or more arguments if required for subfunction.

Discussion

%U_WINCOLOR performs Windows‑specific color operations. See the individual subfunctions for details.

If a value other than one of those listed above is passed for subfunction, a fatal Toolkit error will occur.

D_CHOOSECOLOR

value = %U_WINCOLOR(D_CHOOSECOLOR, color, [help_filename][, help_context_id])

Return value

value

On Windows, the user selected color, or the color passed as color if the user cancels. (^VAL)

Arguments

color

The color (RGB value) you want initially selected when the Color dialog box opens. (n)

help_filename

(optional) The name of the help file. (a)

help_context_id

(optional) The context identifier for help. Required if help_filename is passed. (n)

Discussion

The D_CHOOSECOLOR subfunction of %U_WINCOLOR displays the Color dialog box with an initially selected color (color). This function returns either the color selected by the user or, if the user cancels, the color specified by color. See the GetCellColor Discussion for information on RGB values.

If help_filename is passed, the dialog will have a Help button. Help_filename can be the name of either a WinHelp file (.hlp) or an HTML Help file (.chm):

Examples

The following example displays a dialog box with the initial value specified by color (i4) and returns the color chosen by the user (if any) in new_color (i4).

new_color = %u_wincolor(D_CHOOSECOLOR, color)

The next example includes a help button on the dialog box.

new_color = %u_wincolor(D_CHOOSECOLOR, color, "helpfile.hlp",
&                       select_color_id)

D_GETCOLORS

value = %U_WINCOLOR(D_GETCOLORS, color_array, [start][, end])

or

xcall U_WINCOLOR(D_GETCOLORS, color_array, [start][, end])

Return value

value

On Windows, true. (^VAL)

Arguments

color_array

The first element in an array of returned RGB values for Synergy colors. If this array is not large enough to store all the returned colors, a fatal error may result (though results are unpredictable). (n)

start

(optional) The index of the first color to return (0 through 511). A value less than 0 or greater than 511 will cause a fatal runtime error. (n)

end

(optional) The index of the last color to return (0 through 511). A value less than 0 or greater than 511 will cause a fatao runtime error. If the value is less than start, no colors (or error) will be returned. (n)

Discussion

The D_GETCOLORS subfunction of %U_WINCOLOR returns an array filled with the RGB values for a range of Synergy colors. D_GETCOLORS gets this information from the current color definitions. These can be the memory‑resident defaults, colors defined in synergy.ini or synuser.ini, or colors set with D_SETCOLOR.

Start and end values correspond to numbers for Synergy colors. For example, of you pass 1 as start, the first element in the array will be the value for Synergy color 1. If you don’t pass start, the array index will be one higher than the accessed color. Element 1 will contain Synergy color 0, element 2 will contain Synergy color 1, and so forth. This is because Synergy DBL arrays start with element 1, but Synergy colors start with color 0.

Here’s how start and end work:

See also

Examples

The following example returns in color_array (256i4) the RGB values for Synergy colors 0 through 255:

success = %u_wincolor(D_GETCOLORS, color_array)

The next example returns in win_sys_colors (256i4) the RGB values for Synergy colors 256 through 511:

success = %u_wincolor(D_GETCOLORS, win_sys_colors, 256, 511)

D_HYPER_FG

value = %U_WINCOLOR(D_HYPER_FG)

Return value

value

On Windows, the color of Toolkit hyperlink prompts as an RGB value. (^VAL)

Discussion

The D_HYPER_FG subfunction of %U_WINCOLOR returns the color of Toolkit hyperlink prompts as an RGB value. See the GetCellColor Discussion for information on RGB values.  (n)

Examples

The following example returns in hyper_color (i4) the RGB value associated with a Toolkit hyperlink prompt.

hyper_color = %u_wincolor(D_HYPER_FG)

D_PALETTE_RGB

value = %U_WINCOLOR(D_PALETTE_RGB, palette, fg_color, bg_color[, attr])

or

xcall U_WINCOLOR(D_PALETTE_RGB, palette, fg_color, bg_color[, attr])

Return value

value

On Windows, true if successful, or false if not. (^VAL)

Arguments

palette

A Synergy palette entry number (1‑16). (n)

fg_color

The returned foreground color (RGB value). (n)

bg_color

The returned background color (RGB value). (n)

attr

Optional attribute to apply. You can supply only one attr argument, but its value can be composed by adding together the defined literals in tools.def or by using the supplied combination definitions (for example, A_HR for highlight and reverse). (n)

Discussion

The D_PALETTE_RGB subfunction of %U_WINCOLOR returns the foreground and background colors associated with a Synergy palette entry as RGB values. (See the GetCellColor Discussion for information on RGB values.) If attr is passed, the specified attribute (A_* in tools.def) are applied before evaluating the colors. (See the Attribute Flag Definitions table.)

See also

Customizing the look of your application for information on Synergy palettes.

Examples

This example returns the foreground and background colors associated with Synergy palette entry 6.

success = %u_wincolor(D_PALETTE_RGB, 6, fg_color, bg_color)

D_SETCOLOR

value = %U_WINCOLOR(D_SETCOLOR, color, rgb)

or

xcall U_WINCOLOR(D_SETCOLOR, color, rgb)

Return value

value

On Windows, true if successful, or false if not (for example, if color is invalid). (^VAL)

Arguments

color

A Synergy color (0‑255). A value less than 0 or greater than 255 will cause a fatal runtime error. (n)

rgb

An RGB value. (n)

Discussion

The D_SETCOLOR subfunction of %U_WINCOLOR sets a Synergy color (specified by color) to the RGB value represented by the value passed rgb.

D_SETCOLOR settings override color settings in synergy.ini and synuser.ini, as well as memory‑resident defaults. But D_SETCOLOR settings last only until the program is exited. (Use the %U_SAVELOG function if you wish to save this new color to the [colors] section of synergy.ini or synuser.ini.)

See also

Examples

The following example sets Synergy color 77 to the RGB value specified in color (i4).

success = %u_wincolor(D_SETCOLOR, 77, color)