%U_MSGBOX

Pop up a Windows-style message box

button = %U_MSGBOX(message, [styles], [title], [select_col][, help_id])

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.

On Windows in traditional Synergy, %U_MSGBOX creates a Windows-style message box with one to three buttons, depending on the arguments passed. The icon can be a stop sign, exclamation point (!), question mark (?), or the information icon (i). Button choices are Yes, No, OK, Cancel, Abort, Retry, and Ignore. Since this function invokes the standard Windows MessageBox function, which is application-modal, no menu processing (or any other type of processing) is available while a message box is displayed.
On Windows in Synergy .NET, Toolkit uses a cell-based-style message box if g_netnativemsgbox (a field in tools.def) is set to false, which is the default. If g_netnativemsgbox is set to true, Toolkit uses a native Windows message box.
On UNIX and OpenVMS, %U_MSGBOX follows the same steps to create a message window as U_MESSAGE does. (See the U_MESSAGE Discussion.) %U_MSGBOX, however, looks for a window named u_msgbox, creates a selection window (rather than a “Press… to continue” message), and processes the selection window for valid options. If a menu entry is selected, the function returns false and g_select is cleared. Otherwise, %U_MSGBOX returns the value that corresponds to the selected button.

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.

Default positioning on Windows is determined by Windows Common Dialogs and is generally centered in the screen. Specifying D_MCENTER, however, centers the dialog box over the application window, which matches UNIX and OpenVMS behavior.
On Windows, the close button for the message box is disabled if you pass D_MABTRETIGN or D_MYESNO. If you pass a styles option that includes the Cancel button, the close button causes %U_MSGBOX to return D_MIDCANCEL. If you pass D_MOK, the close button causes %U_MSGBOX to return D_MIDOK.

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)
Modality	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.)