message_box

Platform:

WINDOWS ONLY: for a cross-platform version, see IupMessage().

Definition:

requires(WINDOWS) -- (or explicit test around calls as below)
include msgbox.e
if platform()=WINDOWS then -- (if requires(WINDOWS) is not being used)
integer i = message_box(string msg, string title, integer style=MB_OK, atom hWnd=mWnd)
else
-- something else...
end if

Description:

Display a window with the specified message and title.

The style parameter determines the combination of buttons that are available for the user to press, plus some other characteristics, as detailed below.

The hWnd parameter allows you to specify the owning window, see notes below.

A return value of 0 indicates a failure to set up the window, otherwise one of the values listed below is returned.

pwa/p2js:

Not supported

Comments:

Only works on Microsoft Windows, for other operating systems and cross-platform capability use something like IupMessage (which also works fine on Windows).

Earlier versions allowed style to be a sequence - for legacy code wrap such in or_all().

Previous versions of this routine used a hWnd obtained from the C function GetActiveWindow, which could cause all manner of rude and and nasty behaviour, including disabling Task Manager, at least according to Raymond Chen, who knows far more than anyone else on the planet about such things. You can use procedure set_mb_hwnd(atom hWnd) to set a default for all future calls to message_box(). There is little or no excuse for being unable to provide a better and more sensible value, however if hWnd is NULL (the default), then MB_TASKMODAL is applied automatically (suspends all top-level windows associated with the current thread).

The following constants should be used for style:

To indicate the buttons displayed in the message box, specify one of the following values [optionally plus MB_HELP].

MB_OK	#00	-	OK
MB_OKCANCEL	#01	-	OK and Cancel
MB_ABORTRETRYIGNORE	#02	-	Abort, Retry, Ignore (use 6 instead)
MB_YESNOCANCEL	#03	-	Yes, No, and Cancel
MB_YESNO	#04	-	Yes and No
MB_RETRYCANCEL	#05	-	Retry and Cancel
MB_CANCELTRYCONTINUE	#06	-	Cancel, Try Again, Continue
MB_HELP	#4000	-	Add a Help button (sends WM_HELP)

To display an icon in the message box, specify one of the following values.
Note that MB_ICONQUESTION is no longer recommended as it is ambiguous with respect to question vs. help, and should therefore be avoided.

MB_ICONSTOP	#10	-	A stop-sign appears
MB_ICONHAND	#10	-	(same as MB_ICONSTOP)
MB_ICONERROR	#10	-	(same as MB_ICONSTOP)
MB_ICONQUESTION	#20	-	A question-mark icon appears (deprecated)
MB_ICONEXCLAMATION	#30	-	Exclamation-point appears in the box
MB_ICONWARNING	#30	-	(same as MB_ICONEXCLAMATION)
MB_ICONASTERISK	#40	-	Lowercase letter i in a circle appears
MB_ICONINFORMATION	#40	-	(same as MB_ICONASTERISK)

To specify the default button, (ie the one that gets initial focus and is selected by Return) specify one of the following values.

MB_DEFBUTTON1	#000	-	First button (default)
MB_DEFBUTTON2	#100	-	Second button
MB_DEFBUTTON3	#200	-	Third button
MB_DEFBUTTON4	#300	-	Fourth button

To indicate the modality of the dialog box, specify one of the following values.

MB_APPLMODAL	#0000	-	User must respond before doing something else (default)
MB_SYSTEMMODAL	#1000	-	Serious: All applications suspended until user responds
MB_TASKMODAL	#2000	-	Similar to MB_APPLMODAL, for when hWnd=NULL

To specify other options, use one or more of the following values.

MB_SETFOREGROUND	#10000	-	Message box becomes the foreground window
MB_DEFAULT_DESKTOP_ONLY	#20000	-	Same as desktop of the interactive window station
MB_TOPMOST	#40000	-	Message box has the WS_EX_TOPMOST style
MB_RIGHT	#80000	-	The text is right-justified
MB_RTLREADING	#100000	-	For Hebrew and Arabic systems
MB_SERVICE_NOTIFICATION	#200000	-	Serious: The caller is a service. hWnd must be NULL.

Possible values returned by message_box() (0 means failure):

IDABORT	3	-	Abort button was selected.
IDCANCEL	2	-	Cancel button was selected.
IDCONTINUE	11	-	Continue button was selected.
IDIGNORE	5	-	Ignore button was selected.
IDNO	7	-	No button was selected.
IDOK	1	-	OK button was selected.
IDRETRY	4	-	Retry button was selected.
IDTRYAGAIN	10	-	Try Again button was selected.
IDYES	6	-	Yes button was selected.

Example:

set_mb_hwnd(getHwnd(main)) -- (or 4th param on each call)
integer response = message_box("Do you wish to proceed?",
                               "My Application",
                               MB_YESNOCANCEL)
if response=IDCANCEL or response=IDNO then
    abort(1)
end if

For a complete runnable program, see demo\Hello.exw