Alerts

Server applications generate the EVENT_SYSTEM_ALERT event whenever a user interface change occurs that could affect the user. In addition to triggering EVENT_SYSTEM_ALERT, the server sets the alert level in the object's state bits to convey the level of urgency to the client.

To determine when the user is notified, clients call IAccessible::get_accState to get the object's state information.

Applications always perform the stages of an alert in a specified order.

To perform the stages of an alert

1. Adjust the visual presentation of the object. For example, change an icon to red.
2. Set the alert level state flag for the object to one of the following:
   • STATE_SYSTEM_ALERT_LOW
   • STATE_SYSTEM_ALERT_MEDIUM
   • STATE_SYSTEM_ALERT_HIGH
3. Send any appropriate events related to the appearance change; for example, EVENT_OBJECT_DESCRIPTIONCHANGE.
4. Send the EVENT_SYSTEM_ALERT event.
5. When the client receives the EVENT_SYSTEM_ALERT event, it immediately calls IAccessible::get_accState to obtain the alert state flags of the referenced object.

The same process is repeated when the alert status changes. For example, when the battery indicator icon changes to yellow, its STATE_SYSTEM_ALERT_MEDIUM flag is set, and the EVENT_SYSTEM_ALERT message is sent and references this icon object. When the indicator changes back to green, its STATE_SYSTEM_ALERT_MEDIUM flag is cleared so that none of the alert flags are set, and another EVENT_SYSTEM_ALERT message is sent. A client receives this event, checks the icon object's state flags, and finds that none of the alert flags are set, which indicates that the alert for this object is over.

A visual change triggers more than one event. For example, an accessible object generates the EVENT_OBJECT_VALUECHANGE event when its value string changes. It generates an accompanying EVENT_SYSTEM_ALERT event to indicate to the client that some priority level applies to the previous event.

Although the appropriate events are generated when a change occurs, server developers should minimize sending redundant events.

Using Alert Levels

Server developers can combine the predefined state flags with an alert level that indicates the importance of the other flags. The alert levels are:

• STATE_SYSTEM_ALERT_LOW
• STATE_SYSTEM_ALERT_MEDIUM
• STATE_SYSTEM_ALERT_HIGH

To determine when to notify users, clients can use these alert levels to gauge the information's urgency.