Format 15
DISPLAY MESSAGE BOX creates a simple message box
DISPLAY MESSAGE BOX
{ text } . . .
Remaining phrases are optional and may be used in any order.
TITLE {IS} title
{= }
TYPE {IS} type
{= }
ICON {IS} icon
{= }
DEFAULT {IS} default
{= }
{GIVING } value
{RETURNING}
Syntax Rules
1. Text is a literal or data item.
2. Title is an alphanumeric literal or data item.
3. Type, icon, and default are numeric literals or data items.
4. Value is a numeric data item.
General Rules
1. Format 15 (DISPLAY MESSAGE BOX) creates a simple modal pop-up window with a title-bar, a text message, an icon (on some systems) and one or more push buttons. It then waits for the user to push one of the buttons and returns the results. The window is then destroyed. Message boxes come in "OK" and "Yes/No" formats, with an optional "Cancel" button in each format. Message boxes are a programming convenience when you need to create a simple dialog box that can fit one of these predefined formats.
2. Text forms the body of the message box. It is the string of text that the user will see. When more than one text item is specified, they are concatenated together to form a single string that the user sees. The limit on the length of the message string is host dependent. The host system wraps the text as needed to fit the message box. If you want to force the text to a new line, you can embed an ASCII line-feed character (h"0A" in COBOL) where you want the new line to start. For example, the following code produces a message box with two lines of text:
78 NEWLINE VALUE H"0A". DISPLAY MESSAGE BOX, "This is line 1", NEWLINE, "and this is line 2" .
3. When text is numeric, it is converted to a text string using the CONVERT phrase rules. Leading spaces in the resulting string are suppressed in the message. When text is numeric-edited, leading spaces are suppressed in the message, and the rest of the item is displayed without modification. For all other data types, text is displayed without modification.
4. Title is displayed in the message box's title bar. If title is omitted, the message box displays the same title as the application's main window.
5. Type, icon, default and value use a set of constants to describe the type of message box and the buttons it contains. These constants have level 78 definitions for them in the COPY library "acugui.def" supplied with the compiler. These constants are as follows:
78 MB-OK VALUE 1. 78 MB-YES-NO VALUE 2. 78 MB-OK-CANCEL VALUE 3. 78 MB-YES-NO-CANCEL VALUE 4. 78 MB-YES VALUE 1. 78 MB-NO VALUE 2. 78 MB-CANCEL VALUE 3. 78 MB-DEFAULT-ICON VALUE 1. 78 MB-WARNING-ICON VALUE 2. 78 MB-ERROR-ICON VALUE 3.
6. Type describes the set of buttons contained in the box. The possible values are:
| Type Value
| Buttons
|
| MB-OK
| "OK" button
|
| MB-YES-NO
| "Yes" and "No" buttons
|
| MB-OK-CANCEL
| "OK" and "Cancel" buttons
|
| MB-YES-NO-CANCEL
| "Yes", "No" and "Cancel" buttons |
7. Icon describes the icon that will appear. The icon appears only under Windows. On other systems, the icon selected is ignored. If icon is set to MB-ERROR-ICON, then a "stop" icon is shown. If icon is set to MB-WARNING-ICON, then an "exclamation" icon displays. If icon is set to MB-DEFAULT-ICON, then boxes with "OK" buttons will display an "information" icon, and boxes with "Yes/No" buttons will display a "question mark" icon. If icon is omitted or contains an invalid value, then MB-DEFAULT-ICON is used.
8. Default describes which button will be the default button (i.e., the button used if the user simply presses "return"). The possible values are:
| Value
| Button
|
| MB-OK
| "OK" button
|
| MB-YES
| "Yes" button
|
| MB-NO
| "No" button
|
| MB-CANCEL
| "Cancel" button |
9. Value will contain the identity of the button the user pressed to leave the message box. It uses the same values as default does, described above. For example, if the user presses the "No" button, then value will contain MB-NO.