MSGBOX function

Purpose

Display a message box containing a text string and an optional title, using one or more styles, and returning the button selected by the user.

Syntax

lResult& = MSGBOX(txt$ [, [style&], title$])

Remarks

The MSGBOX function is comprised of the following elements:

txt$

Indicates the text to display within the message box.

style&

Optional parameter which determines the appearance of the message box. Some styles may be combined (OR'ed together) to specify the button and icon displayed in the message box. If style& is omitted, PowerBASIC substitutes %MB_OK. The following styles are defined in WIN32API.INC, in the form of numeric equates:

%MB_OK	Display OK button (default)
%MB_OKCANCEL	Display OK and Cancel buttons
%MB_ABORTRETRYIGNORE	Display Abort, Retry and Ignore
%MB_YESNOCANCEL	Display Yes, No and Cancel
%MB_YESNO	Display Yes and No buttons
%MB_RETRYCANCEL	Display Retry and Cancel buttons
%MB_ICONERROR	Display Error icon (stop sign)
%MB_ICONINFORMATION	Display Information icon ("i")
%MB_ICONQUESTION	Display Query icon (question mark)
%MB_ICONWARNING	Display Warning icon (exclamation)
%MB_DEFBUTTON1	Default to 1st button (default)
%MB_DEFBUTTON2	Default to 2nd button
%MB_DEFBUTTON3	Default to 3rd button
%MB_APPLMODAL	Application Modal - Despite the name, the user can continue to interact with other dialogs without dismissing the MSGBOX. (default)
%MB_SYSTEMMODAL	System Modal - Operates identically to %MB_APPLMODAL, except the MSGBOX is given the %WS_EX_TOPMOST style so that it remains above all other windows and dialogs.
%MB_TASKMODAL	Task Modal - All top-level windows belonging to the current application are disabled until the MSGBOX is dismissed. %MB_TASKMODAL is commonly used to display a truly modal MSGBOX.

title$

Optional title to be displayed in the caption of the message box. If title$ is not specified, "PowerBASIC" is used automatically.

lResult&

Identifies the Button selected by the user. This will be equal to one of the following equates:

%IDOK	OK button
%IDCANCEL	Cancel button
%IDABORT	Abort button
%IDRETRY	Retry button
%IDIGNORE	Ignore button
%IDYES	Yes button
%IDNO	No button

Additional styles may be found in WIN32API.INC in the section prefixed with %MB_. If you are not interested in which button the user selects, use a MSGBOX statement rather than a MSGBOX function.

A question mark may be used as an abbreviation for the MSGBOX statement.

Restrictions

Strings displayed by the MSGBOX function are displayed only up to the first $NUL character, if any.