MESSAGEBOX( ) Function

  • Article

Displays a user-defined dialog box.

MESSAGEBOX(eMessageText [, nDialogBoxType ][, cTitleBarText][, nTimeout])

Parameters

  • eMessageText
    Specifies the text that appears in the dialog box. You can also specify any valid Visual FoxPro function, object, or data type instead of eMessageText. The maximum amount of text you can specify is 1024 characters.

    Note

    Visual FoxPro converts object references to the string, "(Object)". If you specify a function that evaluates to a noncharacter value, Visual FoxPro automatically uses the TRANSFORM( ) function to provide the character equivalent. In the following example, a character type date is returned and passed to MESSAGEBOX( ):

    MESSAGEBOX(DATE())

    Tip

    To move a portion of the message to the next line in the dialog box, use a carriage return, CHR(13), in eMessageText. The height and width of the dialog box increases as needed to contain eMessageText.

  • 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.

    Note

    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.

  • 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 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

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.

Return value

Button

1

OK

2

Cancel

3

Abort

4

Retry

5

Ignore

6

Yes

7

No

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

The shortest abbreviation for MESSAGEBOX( ) is MESSAGEB( ).

The MESSAGEBOX( ) function uses smart parameters in that the parameter type determines which parameter is used. 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:

MESSAGEBOX("HELLO","MyTitle",68,6000)
MESSAGEBOX("HELLO",68,"MyTitle",6000)
MESSAGEBOX("HELLO",68,6000)
MESSAGEBOX("HELLO",68,6000,"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.

eMessageTitle = 'My Application'
eMessageText = 'Record not found. Would you like to search again?'
nDialogType = 4 + 16 + 256
*  4 = Yes and No buttons
*  16 = Stop sign icon
*  256 = Second button is default

nAnswer = MESSAGEBOX(eMessageText, nDialogType, eMessageTitle)

DO CASE
   CASE nAnswer = 6
      WAIT WINDOW 'You chose Yes'
   CASE nAnswer = 7
      WAIT WINDOW 'You chose No'
ENDCASE

See Also

Reference

WAIT Command

DO CASE ... ENDCASE Command

INPUTBOX( ) Function

TRANSFORM( ) Function

Other Resources

Functions