MESSAGEBOX( ) Function
Displays a user-defined dialog box.
MESSAGEBOX(eMessageText [, cTitleBarText][, nDialogBoxType ][, nTimeout])
Return Values
Numeric
Parameters
eMessageText
Specifies the text that appears in the dialog box. Use a carriage return (CHR(13)) in eMessageText to move a portion of the message to the next line in the dialog box. The height and width of the dialog box is increased as necessary to contain cMessageText.You can use any valid Visual FoxPro function or data type instead of eMessageText. If the function you use evaluates to a non-character value, Visual FoxPro automatically uses TRANSFORM to provide the character equivalent as in the following example:
MESSAGEBOX(DATE())nDialogBoxType
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.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.
Value Dialog box buttons 0 OK button only 1 OK and Cancel buttons 2 Abort, Retry, and Ignore buttons 3 Yes, No, and Cancel buttons 4 Yes and No buttons 5 Retry and Cancel buttons Value Icon 16 Stop sign 32 Question mark 48 Exclamation point 64 Information (i) icon Value Default button 0 First button 256 Second button 512 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.
Additional information about the constants is available in the FoxPro.h file, located in the Visual FoxPro home directory. Using defined constants such as MB_ABORTRETRYIGNORE + MB_ICONQUESTION + MB_DEFBUTTON2 can be more readable than 2 + 32 + 256.
cTitleBarText
Specifies the text that appears in the title bar of the dialog box. If you omit cTitleBarText, the title "Microsoft Visual FoxPro" appears in the title bar.nTimeout
Specifies the number of milliseconds Visual FoxPro displays cMessageText without input from the keyboard or the mouse before clearing cMessageText. Any valid timeout can be specified. A value of less than 1 will never timeout until user input (same as without the nTimeout parameter). When a timeout occurs, MESSAGEBOX( ) returns –1.
Remarks
The value MESSAGEBOX( ) returns indicates which button in the dialog box was chosen. In dialog boxes with a Cancel button, pressing ESC to exit the dialog box returns the same value (2) as choosing Cancel.
Note that the shortest abbreviation for this function is MESSAGEB( ).
The following table lists the values MESSAGEBOX( ) returns for each button.
| Return value | Button |
|---|---|
| 1 | OK |
| 2 | Cancel |
| 3 | Abort |
| 4 | Retry |
| 5 | Ignore |
| 6 | Yes |
| 7 | No |
The MESSAGEBOX( ) function uses smart parameters where parameter type dictates which parameter is being used. The first parameter is required and is always cMessageText, however the optional second parameter can be nDialogBoxType if type is numeric, or cTitleBarText if type if type is character. The nTimeout parameter is always assumed for the second optional numeric parameter passed. Valid examples include:
MESSAGEBOX("HELLO","MyTitle",36,1)
MESSAGEBOX("HELLO",36,"MyTitle",1)
MESSAGEBOX("HELLO",36,1)
MESSAGEBOX("HELLO",36,1,"MyTitle")
Example
The following example displays a user-defined dialog box. The message "Record not found. Would you like to search again?" is displayed as the caption in the user-defined dialog box, and "My Application" is displayed in the title bar.
The user-defined dialog box contains Yes and No buttons and the question mark icon, and the second button (No) is the default button. When you choose one of the buttons, your choice is displayed.
cMessageTitle = 'My Application'
cMessageText = 'Record not found. Would you like to search again?'
nDialogType = 4 + 32 + 256
* 4 = Yes and No buttons
* 32 = Question mark icon
* 256 = Second button is default
nAnswer = MESSAGEBOX(cMessageText, nDialogType, cMessageTitle)
DO CASE
CASE nAnswer = 6
WAIT WINDOW 'You chose Yes'
CASE nAnswer = 7
WAIT WINDOW 'You chose No'
ENDCASE