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

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

See Also

MessageBox, MessageBoxIndirect

Category

Dialog Boxes

Back to the Function list.
Back to the Reference section.


Last Modified: February 10, 2000
This page is copyright © 2000 Paul Kuliniewicz. Copyright Information Revised October 29, 2000
Go back to the Windows API Guide home page.
E-mail: vbapi@vbapi.com Send Encrypted E-Mail
This page is at http://www.vbapi.com/ref/m/messageboxex.html