Include buttons in a window

WTSupported in traditional Synergy on Windows




.BUTTON name [, TEXT(button_text)|BITMAP(file)] –
        [, METHOD(method_name[, elb_name])] [, SELECT(character)]



The name of the button (maximum 30 characters).

TEXT (button_text)

(optional) The text to display on the button face.

BITMAP (file)

(optional) The filename for a graphic to display on the button face. See Toolkit button graphics for supported formats and information on creating transparent button graphics.

METHOD (method_name[, elb_name])

(optional) Specify a method to invoke when the button is clicked; optionally include the name of the library for the method. If not specified, the button’s name is the menu entry signaled when the button is pressed.

SELECT (character)

(optional) The quick‑select character for the button. If not passed or blank, the button will not have a quick‑select character.


On Windows, you can use the .BUTTON command to add buttons to a window. The maximum number of buttons allowed in a window is 127.

When a window is being processed, its buttons are automatically enabled by default, and when a window is not being processed, its buttons are automatically disabled by default. However, note the following:

The placement of the button is determined by the .BUTTON_SET command. If no .BUTTON_SET command is specified, the buttons are placed (in their defined order) at the bottom of the window, left‑justified.

The order in which buttons are defined determines how they are added to the window tabbing order. tab moves forward and shift+tab moves backward through the buttons as if they were fields in the input window.

Focus (display of the active item) is shown on the buttons as a thin dotted line around the text portion of the button. When focused, the button can be “pressed” using either the spacebar or the enter key. Whether focused or not, any button can be selected (“pressed”) by clicking on it with the left mouse button.

If neither TEXT nor BITMAP is specified, the button name will be displayed on the button face.

If method_name is specified, it will be invoked when the button is clicked. The arguments passed to the method are the window ID, button name, and the 20 optional method data arguments passed to I_INPUT.

If a select character is specified, pressing alt+character will have the effect of pressing the button. See the B_BUTTON Discussion.

The window will expand downward or to the right to accommodate the buttons. This expansion may cause your window to extend beyond the bottom or right side of your application window. Also, the button will be a standard size. Therefore, text that exceeds the size of the button will not be visible.

Toolkit button graphics

UI Toolkit buttons support the following graphics formats:

If an image is too large for the button face, the image will be cropped; Toolkit won’t scale the image to fit the button. If Toolkit can’t find the file, or if it isn’t one of the supported file types, Toolkit will leave the button face blank.

On Windows versions prior to Windows 8, you can make button images “transparent”— that is, you can specify a color to be replaced by the button face color, which can vary from user to user. To do this, set the SYN_TRANSPARENT_COLOR environment variable and, if necessary, the SYN_TRANSPARENCY_THRESHOLD environment variable.


When a button with a graphic is disabled (grayed out), the transparent portions of the graphic remain transparent. In other words, they retain the button face color.

.BUTTON has no effect on applications running on UNIX or OpenVMS. Script does, however, save button information on these platforms, so if the window is loaded on a Windows platform, the button will be displayed (assuming ISAM‑compatible platforms).

See also


This example displays an OK button that signals “I_OK,” a Cancel button that signals “O_ABANDON,” and a Help button that calls HELP_METHOD when pressed. The OK button has the quick‑select character “K.” When alt+k is pressed, a click of the OK button is simulated.

.button I_OK, text("OK"), select(K)
.button O_ABANDON, text("Cancel")
.button help, text("Help"), method("HELP_METHOD")