Click or drag to resize

MessageBox Function

X#
Displays a user-defined dialog box.

Namespace:  XSharp.VFP
Assembly:  XSharp.VFP (in XSharp.VFP.dll) Version: 2.19
Syntax
 FUNCTION MessageBox(
	eMessageText AS USUAL,
	 nDialogBoxType AS LONG,
	 cTitleBarText AS STRING,
	 nTimeOut AS LONG
) AS LONG
Request Example View Source

Parameters

eMessageText
Type: Usual
Specifies the text that appears in the dialog box. You can also specify any other value instead of eMessageText. The runtime will convert the value to a string before displaying it.
nDialogBoxType
Type: Long
Specifies the buttons and icons that appear in the dialog box, the default button when the dialog box is displayed, and the behavior of the dialog box. See the table in the remarks section for more information.
cTitleBarText
Type: String
Specifies the text that appears in the title bar of the dialog box. If you omit cTitleBarText, the name of your program appears in the title bar.
nTimeOut
Type: Long
Specifies the number of milliseconds X# displays eMessageText without input from the keyboard or the mouse before clearing eMessageText. You can specify any valid timeout value. A value of less than 1 never times out until user enters input and behaves the same as omitting the nTimeout parameter.

Return Value

Type: Long
Numeric data type. MessageBox( ) returns a value that indicates which button was chosen in the dialog box. The following table lists the values MessageBox( ) returns for each button.
ValueDefined constantDescription
1 IDOKOK
2 IDCANCELCancel
3 IDABORTAbort
4 IDRETRYRetry
5 IDIGNOREIgnore
6 IDYESYes
7 IDNONo
In dialog boxes with a Cancel button, pressing Esc to exit the dialog box returns the same value (2) as choosing Cancel. MessageBox( ) returns a value of -1 when a timeout occurs.
Remarks
In the following tables, the dialog box button values 0 to 5 specify the buttons that appear in the dialog box. The icon values 16, 32, 48, and 64 specify the icon that appears in the dialog box. The default values 0, 256, and 512 specify which button in the dialog box is the default button. The default button is selected when the dialog box is displayed. Omitting nDialogBoxType is identical to specifying a value of 0 for nDialogBoxType.
ValueDefined constantDescription
0 MB_OK OK button only
1 MB_OKCANCELOK and Cancel buttons
2 MB_ABORTRETRYIGNOREAbort, Retry, and Ignore buttons
3 MB_YESNOCANCELYes, No, and Cancel buttons
4 MB_YESNOYes and No buttons
5 MB_RETRYCANCELRetry and Cancel buttons
16 MB_ICONSTOPStop sign
32 MB_ICONQUESTIONQuestion mark
48 MB_ICONEXCLAMATIONExclamation point
64 MB_ICONINFORMATIONInformation (i) icon
0 MB_DEFBUTTON1First button
256 MB_DEFBUTTON2Second button
512 MB_DEFBUTTON3 Third button
nDialogBoxType can be the sum of up to three values, one value from each of the preceding tables. For example, if nDialogBoxType is 290 (2+32+256), the specified dialog box has the following characteristics:
- Abort, Retry, and Ignore buttons.
- The message box displays the question mark icon.
- The second button, Retry, is the default.

Using defined constants such as MB_ABORTRETRYIGNORE + MB_ICONQUESTION + MB_DEFBUTTON2 can be more readable than 2 + 32 + 256. The question mark icon is no longer recommended, because it does not clearly represent a specific type of message and because the phrasing of a message as a question could apply to any message type. In addition, users could confuse the message symbol question mark with Help Information. Therefore, it is not recommended to use the question mark symbol in your message boxes. The system continues to support inclusion only for backwards compatibility.

The MessageBox( ) function has several overloads based on the parameter types that you pass. The first parameter is required and is always eMessageText. However, the optional second parameter can be nDialogBoxType if the type is Numeric or cTitleBarText if type is Character. The nTimeout parameter is always assumed for the second optional numeric parameter passed. Valid examples include:

X#
1MessageBox("HELLO","MyTitle",68,6000)
2MessageBox("HELLO",68,"MyTitle",6000)
3MessageBox("HELLO",68,6000)
4MessageBox("HELLO",68,6000,"MyTitle")
Examples
X#
 1eMessageTitle = 'My Application'
 2eMessageText = 'Record not found. Would you like to search again?'
 3nDialogType = 4 + 16 + 256
 4*  4 = Yes and No buttons
 5*  16 = Stop sign icon
 6*  256 = Second button is default
 7nAnswer = MessageBox(eMessageText, nDialogType, eMessageTitle)
 8DO CASE
 9CASE nAnswer = 6
10WAIT WINDOW 'You chose Yes'
11CASE nAnswer = 7
12WAIT WINDOW 'You chose No'
13ENDCASE
See Also