All DatabasesInside Mac - Basic Toolbox
Alert
Alert Draw an alert and process user interaction
#include <Dialogs.h> Dialog Manager
short Alert( alertID, filterProc );
short alertID ; ID of an 'ALRT' type resource
ProcPtr filterProc ; address of custom event filter; NIL= standard
returns dialog item number (or -1 after last alert level)
Alert is a variation of ModalDialog that creates and destroys its window.
Alerts are normally used to get the user's attention and obtain a simple
response.
alertID is the ID of a type 'ALRT' resource. It is a template containing the
size of the alert window, a resource ID of a 'DITL' item list, and a
stage-list used in handling up to four levels of alert urgency.
filterProc is the address of a custom routine that will get a chance to examine,
modify, or remove events before they are processed by the Dialog
Manager. A value of NIL (0) specifies to use standard filtering (the
Return or Enter key is converted to a click of the default button).
Note: The custom filter procedure is identical to that used in
ModalDialog. See that topic for input parameters and an example
of use. However, it is possible for an alert's default button to be
other than the first item. Your filterProc may examine the aDefItem
field of the DialogRecord structure to see which item number to
return in the event of a press of the Return key.
Returns: a 16-bit integer identifying what user action took place. It is one
of:
-1 The alert was not drawn (and nothing happened) because the
current stage of the alert indicated that this was appropriate.
an item number The user selected this item either with the mouse or by
pressing Return.
Notes: Alert is a way to display a message, especially a warning or a caution, and
get simple user input, especially the click of a button. It works like this:
• It reads the alert template resource ('ALRT') and its item list ('DITL') if
either is not already in memory.
• It looks for an 'actb' resource with the same ID as the alert. Setting the
ctSize field to -1 shows that you want to use the default color table. Any
other value for ctSize means the alert color table will be copied before it's
passed to SetWinColor so you can purge it without causing problems for
the alert.
• It copies the color dialog item list resource before passing it so you can
purge it without affecting the alert.
• If this alert is the same as the last one, it increments the global variable
ACount (the alert stage), otherwise it sets ACount to 0 and ANumber to
alertID.
• It makes the sound appropriate to the current stage of the alert by calling
the current sound routine (see ErrorSound).
• If information in the template indicates that at this level of the alert no
dialog box is to be drawn, it returns -1.
• Using the template information, it calls NewDialog to create and display
the contents of the alert box.
• It processes all events until an enabled item is selected.
• It removes the alert window and returns with the item number
The functions StopAlert, NoteAlert, and CautionAlert work the same
as Alert except that an icon is automatically drawn in the upper left
corner. A simple way to implement multiple alerts is to create one alert
containing one or more static text items of ^0, ^1, etc. and use
ParamText to define the text that gets displayed.
You can examine the value of the alert stage via GetAlrtStage and reset it
via ResetAlrtStage (or simply access the global variables).
Referenced by (76):