MessageBoxEx Function

Declare Function MessageBoxEx Lib "user32.dll" Alias "MessageBoxExA" (ByVal hWnd As Long, ByVal lpText As String, ByVal lpCaption As String, ByVal uType As Long, ByVal wLanguageId As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.1 or later.
Windows 2000: Supported.
Windows CE: Not Supported.

Description & Usage

MessageBoxEx opens and operates a small message box on the screen. Message boxes are typically used either to communicate important information (such as an error message) or to prompt the user. The message box only closes when the user presses one of the buttons presented.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns one of the following flags specifying the button the user clicked on:

IDABORT: The Abort button was clicked.
IDCANCEL: The Cancel button was clicked (or the user dismissed the message box using the Esc key).
IDCONTINUE: Windows 2000: The Continue button was clicked.
IDIGNORE: The Ignore button was clicked.
IDNO: The No button was clicked.
IDOK: The OK button was clicked.
IDRETRY: The Retry button was clicked.
IDTRYAGAIN: Windows 2000: The Try Again button was clicked.
IDYES: The Yes button was clicked.

Visual Basic-Specific Issues

None.

Parameters

hWnd

A handle to the window opening the message box.

lpText

The text to display inside the message box.

lpCaption

The text to display inside the caption area of the message box's title bar.

uType

A combination of various flags specifying the behavior and appearance of the message box. The available flags are grouped according to function. If no flags in a certain group are specified, the default is used.

Use one of the following flags to specify which buttons to display in the message box. (Note that MB_HELP can be combined with any of the other flags.)

MB_ABORTRETRYIGNORE: The message box contains the Abort, Retry, and Ignore buttons.
MB_CANCELTRYCONTINUE: Windows 2000: The message box contains the Cancel, Try Again, and Continue buttons. This is meant to replace the MB_ABORTRETRYIGNORE flag.
MB_HELP: Windows 95, 98, NT 4.0 or later, 2000: Add the Help button to the message box. When the user clicks the Help button, the WM_HELP message is sent to the owner of the message box (specified by the hWnd parameter). This flag can only be used by combining it with another button flag (i.e., the Help button cannot appear alone).
MB_OK: The message box contains the OK button. This is the default.
MB_OKCANCEL: The message box contains the OK and Cancel buttons.
MB_RETRYCANCEL: The message box contains the Retry and Cancel buttons.
MB_YESNO: The message box contains the Yes and No buttons.
MB_YESNOCANCEL: The message box contains the Yes, No, and Cancel buttons.

Use one of the following flags to specify which icon to display in the message box:

MB_ICONASTERISK, MB_ICONINFORMATION: Display the information icon: a lowercase letter "i" inside a blue circle.
MB_ICONERROR, MB_ICONHAND, MB_ICONSTOP: Display the stop-sign icon in the message box.
MB_ICONEXCLAMATION, MB_ICONWARNING: Display the exclamation-point icon in the message box.
MB_ICONQUESTION: Display the question-mark icon in the message box.

Use one of the following flags to specify which button is selected by default:

MB_DEFBUTTON1: The first button is the default. This is the default.
MB_DEFBUTTON2: The second button is the default.
MB_DEFBUTTON3: The third button is the default.
MB_DEFBUTTON4: The fourth button is the default.

Use one of the following flags to specify the modality of the message box:

MB_APPLMODAL: The message box is application-modal. The user cannot switch to any other windows owned by the application until he or she first closes the message box. This is the default.
MB_SYSTEMMODAL: The message box is system-modal. The user cannot switch to any other windows until he or she first closes the message box.
MB_TASKMODAL: The message box is thread-modal. The user cannot switch to any other windows owned by the calling thread until he or she first closes the message box.

Use zero or more of the following flags to specify other options for the message box:

MB_DEFAULT_DESKTOP_ONLY: Windows NT, 2000: Same as MB_SERVICE_NOTIFICATION, except that the system will display the message box only on the interactive window station's default desktop.
MB_RIGHT: The text in the message box is right-justified.
MB_RTLREADING: Display the message text and caption using right-to-left reading order if desired by the system language.
MB_SETFOREGROUND: Make the message box the foreground window.
MB_TOPMOST: Make the message box a topmost window.
MB_SERVICE_NOTIFICATION: Windows NT 4.0 or later, 2000: The calling thread is a service notifying the user of an event. The hWnd parameter must be 0.
MB_SERVICE_NOTIFICATION_NT3X: Windows NT 3.1 through 3.51: Same as MB_SERVICE_NOTIFICATION. The value of this flag changed with the release of NT 4.0.

wLanguageId

A language identifier, created by MAKELANGID, which identifies the language used to display the message box's buttons. The specified language must be installed on the system.

Constant Definitions

Const IDABORT = 3
Const IDCANCEL = 2
Const IDCONTINUE = 5
Const IDIGNORE = 5
Const IDNO = 7
Const IDOK = 1
Const IDRETRY = 4
Const IDTRYAGAIN = 4
Const IDYES = 6
Const MB_ABORTRETRYIGNORE = &H2
Const MB_CANCELTRYCONTINUE = &H2
Const MB_HELP = &H4000
Const MB_OK = &H0
Const MB_OKCANCEL = &H1
Const MB_RETRYCANCEL = &H5
Const MB_YESNO = &H4
Const MB_YESNOCANCEL = &H3
Const MB_ICONASTERISK = &H40
Const MB_ICONERROR = &H10
Const MB_ICONEXCLAMATION = &H30
Const MB_ICONHAND = &H10
Const MB_ICONINFORMATION = &H40
Const MB_ICONQUESTION = &H20
Const MB_ICONSTOP = &H10
Const MB_ICONWARNING = &H30
Const MB_DEFBUTTON1 = &H0
Const MB_DEFBUTTON2 = &H100
Const MB_DEFBUTTON3 = &H200
Const MB_DEFBUTTON4 = &H300
Const MB_APPLMODAL = &H0
Const MB_SYSTEMMODAL = &H1000
Const MB_TASKMODAL = &H2000
Const MB_DEFAULT_DESKTOP_ONLY = &H20000
Const MB_RIGHT = &H80000
Const MB_RTLREADING = &H100000
Const MB_SETFOREGROUND = &H10000
'Const MB_TOPMOST = ???
'Const MB_SERVICE_NOTIFICATION = ???
'Const MB_SERVICE_NOTIFICATION_NT3X = ???

Example

' This code is licensed according to the terms and conditions listed here.

' Display a warning message box with the Yes and No option
' owned by window Form1.  Make the message box system-modal to force the
' user to reply immediately.  Have "No" selected by default, and display
' the buttons in American English.
Dim mbresult As Long  ' result of message box
Dim flags As Long  ' message box flags
Dim lang As Long  ' language ID

' For convenience, use a variable to represent the flag settings.
flags = MB_YESNO Or MB_ICONWARNING Or MB_DEFBUTTON2 Or MB_SYSTEMMODAL
' Generate the proper language ID.
lang = MAKELANGID(LANG_ENGLISH, SUBLANG_ENGLISH_US)
' Display the message box.
mbresult = MessageBox(Form1.hWnd, "Are you sure you want to do that?", "Warning!", flags, lang)
' Determine what the user pressed.
If mbresult = IDYES Then
  Debug.Print "OK, go ahead and do that."
Elseif mbresult = IDNO Then
  Debug.Print "Operation aborted."
End If