Description
Displays a system MessageBox with the title, text, icon, and buttons you specify.
Syntax
MessageBox ( title, text {, icon {, button {, default } } } )
|
Argument |
Description |
|---|---|
|
title |
A string specifying the title of the message box, which appears in the box's title bar. |
|
text |
The text you want to display in the message box. The text can be a numeric datatype (double or longlong), a string, or a boolean value. |
|
icon (optional) |
A value of the Icon enumerated datatype indicating the icon you want to display on the left side of the message box. Values are:
|
|
button (optional) |
A value of the Button enumerated datatype indicating the set of CommandButtons you want to display at the bottom of the message box. The buttons are numbered in the order listed in the enumerated datatype. Values are:
|
|
default (optional) |
The number of the button you want to be the default button. The default is 1. If you specify a number larger than the number of buttons displayed, MessageBox uses the default. |
Return value
Integer.
Returns the number of the selected button (1, 2, or 3) if it succeeds and -1 if an error occurs. If any argument's value is null, MessageBox returns null.
Usage
If the value of title or text is null, the MessageBox does not display. Unless you specify otherwise, PowerBuilder continues executing the script when the user clicks the button or presses enter, which is appropriate when the MessageBox has one button. If the box has multiple buttons, you will need to include code in the script that checks the return value and takes an appropriate action.
Before continuing with the current application, the user must respond to the MessageBox. However, the user can switch to another application without responding to the MessageBox.
When you are running a version of Windows that supports right-to-left languages and want to display Arabic or Hebrew text for the message and buttons, set the RightToLeft property of the application object to true. The characters of the message will display from right to left. However, the button text will continue to display in English unless you are running a localized version of PowerBuilder.
When MessageBox does not work
Controls capture the mouse in order to perform certain operations. For instance, CommandButtons capture the mouse during mouse clicks, Edit controls capture for text selection, and scroll bars capture during scrolling. If a MessageBox is invoked while the mouse is captured, unexpected results can occur.
Because MessageBox grabs focus, you should not use it when focus is changing, such as in a LoseFocus event. Instead, you might display a message in the window's title or a MultiLineEdit.
MessageBox also causes confusing behavior when called after PrintOpen. For details, see PrintOpen.
Examples
This statement displays a MessageBox with the title Greeting, the text Hello User, the default icon (Information!), and the default button (the OK button):
MessageBox("Greeting", "Hello User")The following statements display a MessageBox titled Result and containing the result of a function, the Exclamation icon, and the OK and Cancel buttons (the Cancel button is the default):
integer Net
long Distance = 3.457
Net = MessageBox("Result", Abs(Distance), &
Exclamation!, OKCancel!, 2)
IF Net = 1 THEN
... // Process OK.
ELSE
... // Process CANCEL.
END IF