Window Toolkit - AlertWindow()

Purpose: Creates and presents an alert dialog to the user.

C usage:

#include <window.h>
extern pascal Word AlertWindow(Word alertFlags, Pointer subStrPtr, Long alertStrRef);

Original documentation
Apple IIGS Toolbox Reference Volume 3, pp. 52-6 to 52-12 and 52-21 to 52-22.

Macros for alertFlags

Macro Value Bitfield Meaning
awCString 0x0000 0 alertStrRef is a C-style (null-terminated) string
awPString 0x0001 0 alertStrRef is a Pascal-style string
awPointer 0x0000 1 alertStrRef is a pointer to a string
awHandle 0x0002 1 alertStrRef is a handle
awResource 0x0004 2 alertStrRef is a resource

The macros for awCString and awPointer are default selections for two separate bit fields.
A logical OR of the two values indicate a C-string supplied by pointer.

Minimal example

#include <Window.h>
#include <Orca.h>

char alertMsg[] = "13/Hello Apple IIGS!/Ok";

AlertWindow(awCString | awPointer, 0, (Long)alertMsg);

Alert string format

AlertWindow parses the supplied string as an alert definition rather than displaying it verbatim. The string specifies properties of the alert, its message text, button definitions, and optionally other behavior.

For example:

"13/Hello Apple IIGS!/Ok"

defines a simple alert containing the message “Hello Apple IIGS!” and an OK button.

See the Toolbox Reference for the complete alert-string syntax.

Apple IIGS AlertWindow dialog displaying “Hello Apple IIGS!” with an OK button

Why not declare alertStrRef as Pointer?

Because awPointer is only one way to interpret that parameter.
Depending on alertFlags, the same 32-bit alertStrRef field can contain a pointer, a handle, or a resource reference.
This is essentially an old-fashioned tagged union: the flags provide the “tag,” while alertStrRef carries the value.

Conceptually, you can think of it as:

union AlertReference {
    Long value;
    Pointer pointer;
};

Important Notes

  1. The alertStrRef can be much more complicated, with value substitution, multiple buttons, sounds, and custom routines. The format is documented in Volume 3.
  2. AlertWindow was added in System 3.2, and is not available on earlier systems (Apple II TechNote #48: All About AlertWindow).