%U_MSGBOX

Pop up a Windows‑style message box

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
button = %U_MSGBOX(message, [styles], [title], [select_col][, help_id])

or

xcall U_MSGBOX(message, [styles], [title], [select_col][, help_id])

Return value

button

False if the user doesn’t select a message box button, but instead tries to select a menu entry. If a message box button is selected, returns the corresponding option: (^VAL)

D_MIDOK = OK button selected.

D_MIDCANCEL = Cancel button selected.

D_MIDABORT = Abort button selected.

D_MIDRETRY = Retry button selected.

D_MIDIGNORE = Ignore button selected.

D_MIDYES = Yes button selected.

D_MIDNO = No button selected.

Arguments

message

The message text or string. (a)

styles

(optional) One or more style options to set values for the dialog box, the buttons and the icon on the dialog box, and modality. See the Styles options table. If styles is not passed, %U_MSGBOX defaults to the documented default values. (n)

title

(optional) The title of the message box. (a)

select_col

(optional) The selection column ID (UNIX and OpenVMS only). (n)

help_id

(optional) The help identifier, which is passed to EHELP_METHOD if the user selects “O_HELP” while in this function. (a)

Discussion

%U_MSGBOX pops up a Windows‑style message box.

If a time‑out occurs on UNIX or OpenVMS, g_select is set to true and g_entnam is set to the entry name specified in tkctl.def for g_time_entry. By default, g_time_entry is defined as “O_TIMEOUT”. %U_MSGBOX cannot time out on Windows.

Message is wrapped according to the same rules as apply to the U_MESSAGE subroutine.

The styles argument enables you to set optional values for the dialog box, the buttons and the icon on the dialog box, and modality. The dialog box, icon, and modality options have no effect on UNIX and OpenVMS. See the table below for valid options.

The following options, defined in tools.def, can be combined using .BOR. or the vertical bar (|) operator.

Styles options

Category

Option

Definition

Dialog

D_MCENTER

Center dialog box over application window (Not available in Synergy .NET)

Button

D_MOK

OK button only (default)

D_MOKCANCEL

OK and Cancel buttons

D_MABTRETIGN

Abort, Retry, Ignore buttons

D_MYESNOCANCEL

Yes, No, Cancel buttons

D_MYESNO

Yes and No buttons

D_MRETRYCANCEL

Retry and Cancel buttons

Default button

D_MDEFBUTTON1

Set default to first button (default)

D_MDEFBUTTON2

Set default to second button

D_MDEFBUTTON3

Set default to third button

Icon style (no icon is the default)

D_MICONSTOP

Stop sign

D_MICONQUESTION

Question mark (?)

D_MICONEXCLAM

Exclamation point (!)

D_MICONINFO

Information (i)

Modality

D_MAPPLMODAL

Application modal (default)

D_MSYSTEMMODAL

System modal

If you omit title in a Windows environment with traditional Synergy, the message box inherits the application’s window title. With Synergy .NET, the default title is the Windows default, “Error”. In UNIX and OpenVMS environments, the default for title is blank.

On UNIX and OpenVMS, if select_col is passed and non‑zero, the specified column is placed on the menu and removed on exit. As an alternative, you can place the column before calling %U_MSGBOX. The default behavior for each environment’s handling of columns is controlled by the g_plc_col_args flag, which is defined in the distributed tkctl.def file. See g_plc_col_args for information.

On Windows, select_col is ignored. (Columns passed as select_col usually contain reserved menu entries that are automatically supported on Windows. Excessive placing and removing of columns causes Windows menu bars to flicker.)

See also

Examples

The following example pops up a window titled “Inquire” that contains the text “Error opening file”. On UNIX and OpenVMS, a single‑item selection window is displayed containing the item “OK”. On Windows, a stop sign icon is displayed, along with an OK button. See figure 1.

rtn = %u_msgbox("Error opening file", D_MOK|D_MICONSTOP, "Inquire")

If the user selected “OK”, rtn would contain D_MIDOK. If the user selected a menu entry (available only on UNIX and OpenVMS), rtn would be false, and g_select would be true.

1. Sample %U_MSGBOX window for Unix or OpenVMS (left) and Windows (right).