Apple II Technical Notes _____________________________________________________________________________ Developer Technical Support Apple IIGS #48: All About AlertWindow 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. _____________________________________________________________________________ Window Manager version 2.2, which is available on Apple IIGS System Disk 3.2 and later, includes a new call, AlertWindow. 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 gets 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 b e replaced with other text when you display the dialog. The Call AlertWindow ($590E) input: WORD - Space for result. WORD - String flag. 0 if substitution strings are C-type or NULL terminated, 1 if Pascal-type. LONG - Pointer to substitution string array, anything if no substitutions are to be made. LONG - Pointer to alert string. 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 information is to give 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, then it can specify zero as the size character and use the next 8 bytes as 4 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 you would like 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. Message Text Following the separator character is the message text. Any characters allowed by LETextBox2 are allowed in the message text. See Special Characters below for additional functions of message text. The total size of the message text, after substitution of strings, is limited to 1000 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 will be evenly spaced and centered at the bottom of the alert window. The width of each button will be the same size and will be set according to the widest button title. The total size of button text, after substitution of strings, is limited to 80 characters. Termination of Alert String A zero (0) 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 will be replaced with 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 the button selected if the user presses the Return key or the Enter key on the keyboard. 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 will be substituted with OK #1 will be substituted with Cancel #2 will be substituted with Yes #3 will be substituted with No #4 will be substituted with Try Again #5 will be substituted with Quit #6 will be substituted with 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 will be 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 will substitute for *0. LONG[1] Pointer to the string that will substitute for *1. LONG[2] Pointer to the string that will substitute for *2. LONG[3] Pointer to the string that will substitute for *3. LONG[4] Pointer to the string that will substitute for *4. LONG[5] Pointer to the string that will substitute for *5. LONG[6] Pointer to the string that will substitute for *6. LONG[7] Pointer to the string that will substitute for *7. LONG[8] Pointer to the string that will substitute for *8. LONG[9] Pointer to the string that will substitute 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. Examples Here 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' dc c'standard text called "#4" /' dc c'^#0,Really/*4/Yo!',il'13' |-----------------------------------------------------------------------| | ##################################################################### | | # ______ # | | # | Note | 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'