ALERT
8.0.7, PLBCMP GUI Only
The ALERT instruction invokes a standard dialog to display a message to the operator. Program execution pauses at the ALERT statement until the operator responds to the message box controls. The instruction uses the following format:
|
|
|
|
|
Where:
label
Optional. A Program Execution Label.
window
Optional. A previously created WINDOW object variable on which the ALERT is displayed.
type
Required. A user-defined type as described below or one of the following ALERT types: CAUTION, NOTE, PLAIN, or STOP.
message
Required. A previously defined Character String Variable, string Literal, character variable or literal, decimal constant, or numeric variable indicating the message that is displayed.
result
Required. A Numeric Variable that returns the user's response.
title
Optional. A Character String Variable, a string Literal, decimal constant, or numeric variable indicating the title that is displayed on the alert box.
Flags Affected: OVER
Note the following:
The CAUTION alert displays an icon with an exclamation mark and has one button named OK.
The NOTE alert displays an icon with an "i" character and has one button named OK.
The PLAIN alert displays an icon with a question mark and has three buttons named YES, NO and CANCEL.
The STOP alert displays an icon of a stop sign and has one button named OK.
The alert box is placed at a system defined location on the window and may not be changed.
The message operand specifies the data for the message or a specific alert resource.
For multi-line alert messages, a 0x7F character separates lines within the text by replacing the 0x7F with an appropriate character sequence applicable for the client UI (9.7A):
|
Operating System |
The 0x7F is replaced by a |
|
Windows |
0x7F is replaced a CR followed by a LF character sequence.. |
|
Client Browser |
"</br>" tag sequence. |
If the message operand is a character literal or character variable, a default alert is used based on the value of the type operand. The character string is scanned for ^0, ^1, ^2 or ^3 character sequences. If one of these character sequences is found, it is replaced by the last string given by the PARAMTEXT instruction for the given sequence.
If the message operand is a decimal constant or numeric variable, the value of the operand loads an alert resource. This resource is used as the alert template.
The alert message is limited to a length of 255 characters. This 255 character limit includes the expanded 0x7F character sequences as described in Note (7.) above.
The {result} operand contains the value of the button that terminated the alert. For the CAUTION, NOTE, and STOP alerts, the return value is always one (1). For the PLAIN alert, the return value is one if "Yes" was selected, two (2) if "No" was selected, and three (3) if "Cancel" was selected or the ESC key is pressed. If the ALERT does not contain a cancel button, pressing the ESC key produces no action.
If a FILEPI instruction is active, it is terminated.
An optional {title} parameter changes the title of the ALERT message box. If not specified, the program name is used.
If the optional {window} is not specified, the current window is used.
If {result} is too small to contain the response value, the OVER flag is set.
{type} may be one of the predefined values of CAUTION, NOTE, PLAIN, or STOP. Additionally, a user-defined type may be specified using the format TYPE={value}. {value} may be a numeric variable, decimal value or a defined constant from PLBEQU.INC containing a combination of the following values: Note that the constants in PLBEQU.INC are enabled by defining PLBALERT as a one (1) prior to the inclusion of the file.
|
Value |
Define |
Meaning ... |
|
0x0 |
$MB_OK |
OK button. The message box contains one push button: OK. |
|
0x1 |
$MB_OKCANCEL |
OK/CANCEL buttons. The message box contains two push buttons: OK and Cancel. |
|
0x2 |
$MB_ABORTRETRYIGNORE |
ABORT/RETRY/IGNORE buttons. The message box contains three push buttons: ABORT, RETRY and IGNORE. |
|
0x3 |
$MB_YESNOCANCEL |
YES/NO/CANCEL buttons. The message box contains three push buttons: Yes, No and Cancel. |
|
0x4 |
$MB_YESNO |
YES/NO buttons. The message box contains two push buttons: Yes and No. |
|
0x5 |
$MB_RETRYCANCEL |
RETRY/CANCEL buttons. The message box contains two push buttons: Retry and Cancel. |
|
|
|
|
|
0x10 |
$MB_ICONSTOP |
Stop-sign icon. A stop-sign icon appears in the message box. |
|
0x20 |
$MB_ICONQUESTION |
Question-mark icon. A question-mark icon appears in the message box. |
|
0x30 |
$MB_ICONEXCLAMATION |
Exclamation-point icon. An exclamation-point icon appears in the message box. |
|
0x40 |
$MB_ICONINFORMATION |
Information icon. An icon consisting of a lowercase letter 'i' in a circle appears in the message box. |
|
|
|
|
|
0x0 |
$MB_DEFBUTTON1 |
Default button one. The first button is the default button. Note that the first button is always the default unless MB_DEFBUTTON2, MB_DEFBUTTON3 or MB_DEFBUTTON4 is specified. |
|
0x100 |
$MB_DEFBUTTON2 |
Default button two. The second button is a default button. |
|
0x200 |
$MB_DEFBUTTON3 |
Default button three. The third button is a default button. |
|
0x300 |
$MB_DEFBUTTON4 |
Default button four. The fourth button is a default button. |
|
|
|
|
|
0x10000 |
$MB_SETFOREGROUND |
Set foreground window. The message box becomes the foreground window. Internally, Windows calls the 'SetForegroundWindow' API function for the message box. |
|
0x80000 |
$MB_RIGHT |
Text right justified. |
|
0x100000 |
$MB_RTLREADING |
Right to left reading. |
When using a user-defined type, a {result} value of zero indicates there is not enough memory to create the message box.
If the function succeeds and the ALERT is a user-defined
type, {result} is one of the following values returned by the dialog
box:
|
Value |
Define |
Button selected by the user was ... |
|
1 |
$IDOK |
OK |
|
2 |
$IDCANCEL |
CANCEL |
|
3 |
$IDABORT |
ABORT |
|
4 |
$IDRETRY |
RETRY |
|
5 |
$IDIGNORE |
IGNORE |
|
6 |
$IDYES |
YES |
|
7 |
$IDNO |
No |
ALERT dialogs cannot be scaled using the WINDOW Scale method.
When using the PL/B Web server, only the PLAIN ALERT type is supported.
Beware that the 'ALERT' instruction can disrupt OS event messages resulting in PLB events that are lost or altered to give inconsistent results in different UI environments. This instruction should not be used when the PLB applications require a very specific sequence of PLB event operations and behaviors in many different OS UI environments. This warning applies for all runtimes including Windows and client browser UI environments.
Since the PWS ALERT cannot simulate the indeterminate behaviors of the Windows 'MessageBox' used for the PLBWIN ALERT instruction, the PWS ALERT clears all PLB user events in an attempt to force consistent behaviors for the different client browser types.
See Also: Example Code, System Interface Instructions
|
|