Intuition Alerts

Intuition Alerts

Alerts are for emergency messages. They can be displayed even when the system is in a very fragile state, such as when the system is low on memory or when some of the system lists are corrupt.

Alerts can be displayed by either the system or an application. They are reserved for urgent messages and dire warnings in situations that require the user to take some immediate action. Alerts should only be used where no other display type is possible. For instance, when the system has crashed or is about to crash, an alert could be used to inform the user of the cause.

The sudden display of an alert is a jarring experience for the user. The system stops dead while the alert is displayed and waits for the user input. For this reason, alerts should only be used when there is no recourse. If possible, use requesters or windows to display warning messages in place of alerts.

System alerts are managed entirely by Intuition. The program does not have to take any action to invoke or process these alerts.

The alert appears at the top of the video display. They are displayed full width and as tall as needed. Alerts are always displayed on a black background. The text of the alert is displayed within a rectangular border. Both the text and the border are displayed in a single color which is determined by the type of the alert.

The user responds to an alert by pressing one of the mouse buttons. The left mouse button signifies a positive response such as "Retry" or "OK". The right mouse button signifies a negative response such as "Cancel" or "Abort".

Alerts Save Up User Input
The events produced by the user during an alert are not consumed by the alert. These events are passed through to the program when the alert returns. There could be a great deal of input queued and waiting for processing by the application.

Types of Alerts

There are two levels of severity for alerts:

RECOVERY_ALERT

Recovery alerts are used in situations where the caller believes that the system can resume operations after handling the error. The alert is used as a warning, and is displayed in amber.

A recoverable alert displays the text of the alert and flashes the border while waiting for the user to respond. It returns TRUE if the user presses the left mouse button in response to the alert, otherwise FALSE is returned.

DEADEND_ALERT

Deadend alerts are used in situations where the caller believes that no recovery from the error is possible, and further operation of the system is impossible. This alert is used to inform the user of a fatal problem and is displayed in red. Deadend alerts are the same as recoverable alerts in every way except color.

Creating Alerts

The function DisplayAlert() creates and displays an alert message. The message will almost always be displayed regardless of the state of the machine (with the exception of catastrophic hardware failures). If the user presses one of the mouse buttons, the display is restored to its original state, if possible. If a recoverable alert cannot be displayed (because memory is low), DisplayAlert() will return FALSE, as if the user had selected cancel. DisplayAlert() is also used by the system to display the Amiga system alert messages.

BOOL DisplayAlert( ULONG alertNumber, UBYTE *string, ULONG height );

The alertNumber argument is a LONG value, specifying whether this is a RECOVERY_ALERT or a DEADEND_ALERT (see the <intuition/intuition.h> include file).

The string argument points to a string that is made up of one or more substrings. Each substring contains the following:

• The first component is a 16 bit x-coordinate and an 8 bit y-coordinate describing where to position the substring within the alert display. The units are in pixels. The y-coordinate describes the location of the text baseline.
• The second component is the text itself. The substring must be NULL terminated (it ends with a zero byte).
• The last component is the continuation byte. If this byte is zero, this is the last substring in the message. If this byte is non-zero, there is another substring in this alert message.

The complete string must be terminated by two NULL characters; one as the end of the last substring, and one as a NULL continuation byte, indicating that this was the last substring.

The height argument is the number of display lines required for the alert.

Display Alert Example

This program demonstrates an alert. An explanation of the positioning values for the alert strings is in the comment that precedes the alertMsg string.

/*
** displayalert.c -  This program implements a recoverable alert
*/
#define INTUI_V36_NAMES_ONLY
 
#include <exec/types.h>
#include <intuition/intuition.h>
 
#include <proto/exec.h>
#include <proto/intuition.h>
#include <proto/dos.h>
 
/* Each string requires its own positioning information, as explained
** in the manual.  Hex notation has been used to specify the positions of
** the text. Hex numbers start with a backslash, an "x" and the characters
** that make up the number.
**
** Each line needs 2 bytes of X position, and 1 byte of Y position.
**   In our 1st line: x = \x00\xF0 (2 bytes) and y = \x14 (1 byte)
**   In our 2nd line: x = \x00\xA0 (2 bytes) and y = \x24 (1 byte)
** Each line is null terminated plus a continuation character (0=done).
** This example assumes that the complier will concatenate adjacent
** strings into a single string with no extra NULLs.  The compiler does
** add the terminating NULL at the end of the entire string...The entire
** alert must end in TWO NULLs, one for the end of the string, and one
** for the NULL continuation character.
*/
 
uint8 *alertMsg =
    "\x00\xF0\x14" "OH NO, NOT AGAIN!" "\x00\x01"
    "\x00\x80\x24" "PRESS MOUSEBUTTON:   LEFT=TRUE   RIGHT=FALSE" "\x00";
 
struct IntuitionIFace *IIntuition = NULL;
 
int main()
{
    struct Library *IntuitionBase = IExec->OpenLibrary("intuition.library", 50);
    IIntuition = (struct IntuitionIFace *)IExec->GetInterface(IntuitionBase, "main", 1, NULL);
 
    if (IIntuition != NULL)
    {
        if (IIntuition->DisplayAlert(RECOVERY_ALERT, alertMsg, 52))
            IDOS->Printf("Alert returned TRUE\n");
        else
            IDOS->Printf("Alert returned FALSE\n");
    }
 
    IExec->DropInterface((struct Interface *)IIntuition);
    IExec->CloseLibrary(IntuitionBase);
 
    return 0;
}

Function Reference

The following are brief descriptions of the Intuition functions that relate to the use of Intuition alerts. See the SDK for details on each function call.

Function	Description
DisplayAlert()	Open an alert on the screen.