Apple II
Technical Notes
_____________________________________________________________________________
                                                  Developer Technical Support


Apple IIGS
#48:    All About AlertWindow

Revised by:    Dave Lyons                                           July 1989
Written by:    Dan Oliver & Keith Rollin                        November 1988

This Technical Note documents a new call in the Window Manager which eases the 
creation of Alert windows.
Changes since November 1988:  Documented new features and behavior of 
AlertWindow in System Software 5.0.
_____________________________________________________________________________

AlertWindow is available in Window Manager version 2.2 and later (Apple IIGS 
System Disk 3.2 and later).  This call takes three parameters which are used 
to create a dialog box with text, buttons, and an optional icon.

AlertWindow works by taking a pointer to an "alert string."  This alert string 
defines the size and location of the alert window, specifies what icon (if 
any) it uses, defines the text it displays, and indicates the number of 
buttons and their names which it displays.

The alert string is a very powerful and complicated structure to be able to 
specify all of this information, and it is even more powerful with the added 
capability of "substitution strings."  Substitution strings work in a manner 
similar to ParamText substitutions; certain sections of the text are 
designated as variables to be replaced by other text when you display the 
dialog.


The Call

AlertWindow ($590E)

    input:     WORD    Space for result.
               WORD    alertFlags.  Bit 0 is 0 if substitution strings are C-
                       type strings (NULL terminated), 1 if they are Pascal-
                       type strings (leading length byte).  Bits 1 and 2 are 
                       00 if alertStrRef is a pointer, 01 if it is a handle, 
                       and 10 if it is a resource ID (the resource type is 
                       $8015).
               LONG    Pointer to substitution string array; anything if no 
                       substitutions are to be made.
               LONG    alertString (see alertFlags)
    output:    WORD    Button number that was selected where 0 is the first 
                       button title in the alert string, 1 is the next button 
                       title, and 2 is the third.


The Format of the Alert String

Size Character

The first character of the alert string is the size character, which indicates 
the size of the alert window.  The character can be ASCII 1-9 to indicate any 
one of nine standard alert window sizes.  The goal of standard sizes is to 
have alert windows that can contain the same amount of message text in 320 
mode or 640 mode, without changing the size.  However, making this happen may 
require some careful message and button text composition.

            Size Character    Approximate Maximum # of Characters
            _____________________________________________________
                  1                         30
                  2                         60
                  3                        110
                  4                        175
                  5                        110
                  6                        150
                  7                        200
                  8                        250
                  9                        300
            _____________________________________________________

The following table shows the dimensions of the standard alert windows.  This 
table gives an idea of the size of each window.  Application code should not 
rely on the exact widths, heights, or position of standard windows.  If an 
application needs an exact window size, it can specify zero as the size 
character and use the next eight bytes as four word-sized integers which 
specify the rectangle of the window.

Character    Height 320    Width 320    Height 640    Width 640
_____________________________________________________________________________
    1            46           152           46           200
    2            62           176           54           228
    3            62           252           62           300
    4            90           252           72           352
    5            54           252           46           400
    6            62           300           54           452
    7            80           300           62           500
    8           108           300           72           552
    9           134           300           80           600
    0    (Character followed by 4 integers that represent size and position.)
_____________________________________________________________________________

Icon Number

The next character is the icon number.  The icon number can be 0-9 where:

    0 =        No icon.
    1 =        custom icon, followed by:
               LONG    Pointer to image data.
               WORD    Number of bytes image data is wide.
               WORD    Number of scan lines image data is high.
    2 =        Stop icon.
    3 =        Note icon.
    4 =        Caution icon.
    5 =        Disk icon.
    6 =        Disk swap icon.
    7 - 9 =    Reserved--do not use.

Separator Character

The next character is a separator character.  The separator can be any 
character and cannot appear in the message text or button strings.  The 
separator is used to separate the message from the first button string and 
each button string from each other.  For purposes of standardization the slash 
(/) might be a good choice, unless you will be substituting pathnames (see the 
section "Don't Use Separator Characters in Substitution Strings").

Message Text

Following the separator character is the message text.  Any characters which 
LETextBox2 allows are valid in the message text.  See the section "Special 
Characters" for additional message text functions.  The total size of the 
message text, after string substitution, is limited to 1,000 characters.

Button Strings

The first character after the separator character following the message text 
is the beginning of the first button's title.  The title can be followed with 
either another separator character and button title or a string termination 
character (i.e., zero (0)) to end the alert string.  A total of three button 
titles may be included at the end of the alert string.  These buttons are 
evenly spaced and centered at the bottom of the alert window.  The width of 
each button is the same size and is set according to the widest button title.  
The total size of the button text, after string substitution, is limited to 80 
characters.

Termination of Alert String

A zero ($00) comes after the last button title to end the alert string.


The Substitution Strings

The message text and button strings can contain special characters that are 
replaced by substitution strings when you display the alert window.

Special Characters

The following special characters can be embedded in the message text and 
button strings of an alert.  If you want the special character itself to 
appear in the body of the text, enter it twice in the string.

    ^        If a caret (^) is the first character in a button 
             string, the button is the default button.  The default 
             button is the button selected if the user presses the 
             Return key or the Enter key.  This button also has a 
             bold outline on the screen.  Only one button can be 
             the default button.  After the caret, the button title 
             must follow like any other title (including other 
             special characters).

             Note:  If the caret is to appear in the message 
                    text, it must be entered twice, side-by-side.  A 
                    single caret in message text has no effect and 
                    is deleted from the message.

    #        Substitute with a standard string.  The pound sign (#) 
             must be followed by an ASCII character.  Characters 0-
             6 can be used (7-9 are reserved and should not be 
             used) where:

                 #0 is replaced by OK
                 #1 is replaced by Cancel
                 #2 is replaced by Yes
                 #3 is replaced by No
                 #4 is replaced by Try Again
                 #5 is replaced by Quit
                 #6 is replaced by Continue

    *        Substitute with the given string.  The asterisk (*) 
             followed by ASCII character in the range 0-9 denotes 
             that a substitution string should be inserted at that 
             point.  The asterisk and the following character are 
             replaced by the corresponding string in the 
             substitution array.  A pointer to the substitution 
             array is one of the parameters passed to AlertWindow 
             and is defined as an array of LONG pointers where:

                 LONG[0]    Pointer to the string that 
                            substitutes for *0.
                 LONG[1]    Pointer to the string that 
                            substitutes for *1.
                 LONG[2]    Pointer to the string that 
                            substitutes for *2.
                 LONG[3]    Pointer to the string that 
                            substitutes for *3.
                 LONG[4]    Pointer to the string that 
                            substitutes for *4.
                 LONG[5]    Pointer to the string that 
                            substitutes for *5.
                 LONG[6]    Pointer to the string that 
                            substitutes for *6.
                 LONG[7]    Pointer to the string that 
                            substitutes for *7.
                 LONG[8]    Pointer to the string that 
                            substitutes for *8.
                 LONG[9]    Pointer to the string that 
                            substitutes for *9.

             Substitution strings can be a C-type (NULL-
             terminated), Pascal-type (a string prefixed with a 
             length byte), or Return-terminated.  NULL- and Return-
             terminated strings are selected by passing 0 to 
             AlertWindow as the string flag.  Pascal strings are 
             selected by passing 1.

             Elements do not need to be defined if they are not 
             referenced in the alert.


Don't Use Separator Characters in Substitution Strings

Do not include a separator character in any substitution strings.  Beginning 
with System Software 5.0, substitutions are performed before the alert string 
is scanned for separators.  For example, if the separator character is a slash 
and a pathname containing several slashes is substituted for the string, the 
resulting alert will contain several more buttons than expected.


Examples

Following are some examples of alert strings that can be passed to AlertWindow 
in APW 65816 assembler syntax.

A simple alert string:

          dc    c'13/Text of Message/Button 1',il'0'---
                   \     \              \              \
   Size 50 high     Icon  Message        Button Title   Zero terminates alert.
    by 200 wide.

                  |--------------------------------------|
                  | #################################### |
                  | #   ______                         # |
                  | #  | Note |    Text of Message     # |
                  | #  | Icon |                        # |
                  | #  |______|                        # |
                  | #                                  # |
                  | #               _____________      # |
                  | #              /             \     # |
                  | #             |    Button 1   |    # |                                                         
                  | #              \_____________/     # |
                  | #                                  # |
                  | #################################### |
                  |--------------------------------------|

A more complex alert string:

    dc   c'51/This is the *0 of *3 alert *2*1 and standard'
    dc   c'text called "#4" /'
    dc   c'^#0,Really/*4/Yo!',il'0'
	
|-----------------------------------------------------------------------|
| ##################################################################### |
| #   ______                                                          # |
| #  | Stop |    This is the message text of an alert window and      # |
| #  | Icon |    standard text called "Try Again."                    # |
| #  |______|                                                         # |
| #                                                                   # |
| #          =============       _____________      _____________     # |
| #        //             \\    /             \    /             \    # |
| #       ||  OK, Really   ||  |    Door #2    |  |      Yo!      |   # |                                                         
| #        \\             //    \_____________/    \_____________/    # |
| #          =============                                            # |
| ##################################################################### |
|-----------------------------------------------------------------------|

          Where substitution array =
                          dc   i4'sub0,sub1,sub2,sub3,sub4'
                  sub0    dc   c'message text',il'0'
                  sub1    dc   c'dow',il'0'
                  sub2    dc   c'win',il'13'
                  sub3    dc   c'an',il'0'
                  sub4    dc   c'Door #2',il'0'