home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / bbs / dev / cmanual-3.0.lha / CManual-3.0 / Intuition / Alerts / Alerts.doc < prev    next >
Encoding:
Text File  |  1993-10-12  |  7.1 KB  |  199 lines
  1. 6    ALERTS
  2.  
  3. 6.1  INTRODUCTION
  4.  
  5. Alerts is the last resource your program can use in order to
  6. inform the user about a problem. When your program displays an
  7. alert all screens are moved down, and a black and red box is
  8. opened at the top of the display. It not only gives the user a
  9. hart attack, but it will also tell him/her what went wrong, and
  10. if there is a way out.
  11.  
  12.  
  13.  
  14. 6.2  DIFFERENT LEVELS OF WARNINGS 
  15.  
  16. There exist three levels of warnings:
  17.  
  18. 1. If you want to alert the user that something went wrong, but
  19.    it is nothing serious, you can flash the screens. You do it
  20.    by calling the function DisplayBeep(), and the background
  21.    colour of all screens will be flashed.
  22.  
  23. 2. If something went wrong, and you want to inform the user,
  24.    maybe even want that he/she does something, you should open a
  25.    Requester. (Described in chapter 5 REQUESTERS.)
  26.  
  27. 3. If something went TERRIBLE WRONG, (the system is crashing
  28.    etc) your program should activate an Alert message,
  29.    DisplayAlert().
  30.  
  31.  
  32.  
  33. 6.3  HOW TO USE THE DISPLAYALERT() FUNCTION
  34.  
  35. Synopsis: result = DisplayAlert( nr, message, height ); 
  36.  
  37. nr:       (long)  Value which describes if it is a
  38.           RECOVERY_ALERT or a DEADEND_ALERT.
  39.  
  40. message:  (char *) Pointer to an array of characters (char). It
  41.           contains the strings we want to display, and some
  42.           extra information (position etc). The string itself
  43.           is divided into substrings, which all contain
  44.           information about its position etc.
  45.           
  46.           Each substring consists of:
  47.           
  48.           - 2 bytes (16-bit) which are used for the x position
  49.             of the text.
  50.           - 1 byte (8-bit) which is used for the y position of
  51.             the text.
  52.           - The text string which ends with a NULL ('\0') sign.
  53.           - A Continuation byte. If it is TRUE there is another
  54.             substring after this one, else this was the last
  55.             substring.
  56.  
  57.           (See below for more information)
  58.  
  59. height:   (long) The height of the Alert box.
  60.  
  61. result:   (long) The function DisplayAlert() returns a boolean
  62.           value. If it is a RECOVERY_ALERT and the user pressed
  63.           the left mouse button it returns TRUE else, if the
  64.           user pressed the right mouse button, it returns
  65.           FALSE. If it is a DEADEND_ALERT the function will
  66.           immediate return FALSE.
  67.  
  68.  
  69.  
  70. 6.4  EXAMPLES OF STRINGS AND SUBSTRINGS
  71.  
  72. If we want to display the following Alert message:
  73.  
  74. ---------------------------------------------------------------
  75. |                                                             |
  76. |  ERROR! Not enough memory!                                  |
  77. |                                                             |
  78. ---------------------------------------------------------------
  79.  
  80. the string would be declared and initialized like this:
  81.  
  82.   /* Declare the array of char (the string): */
  83.   char message[30]; /* 30 bytes needed. */
  84.  
  85.   /* Fill the string with the message: (Remember to give    */
  86.   /* space for the first 3 bytes which will contain the x/y */
  87.   /* position.)                                             */
  88.   strcpy( message, "   ERROR! Not enough memory!" );
  89.   /* The NULL sign is automatically placed at position 28. */
  90.  
  91.   /* Fill the string with the position (x,y) (first 3 bytes)  */
  92.   message[0]=0;  /* X position is less than 256, therefore 0. */
  93.   message[1]=32; /* 32 pixels out. */
  94.   message[2]=16; /* 16 lines down. */
  95.  
  96.   /* Set the Continuation byte to FALSE since there are no */
  97.   /* more substrings after this one:                       */
  98.   message[29]=FALSE;
  99.  
  100.  
  101.  
  102. If we on the other hand want to display the following Alert message:
  103.  
  104. ---------------------------------------------------------------
  105. |                                                             |
  106. |  ERROR! Not enough memory!                                  |
  107. |                                                             |
  108. |  Buy a memory expansion!                                    |
  109. |                                                             |
  110. ---------------------------------------------------------------
  111.  
  112. the string would be declared and initialized like this:
  113.  
  114.   /* Declare the array of char (the string): */
  115.   char message[58]; /* 58 bytes needed. */
  116.  
  117.   /* Fill the array with the first substring: (Remember to */
  118.   /* give space for the first 3 bytes which will contain   */
  119.   /* the x/y position.)                                    */
  120.   strcpy( message, "   ERROR! Not enough memory!" );
  121.  
  122.   /* Add the second substring: (Remember this time to give */
  123.   /* space for 5 bytes in the beginning of the string.     */
  124.   /* They are used for the NULL sign which finish off the  */
  125.   /* first substring, the Continuation byte, and three     */
  126.   /* bytes for the position for the second substring.)     */
  127.   strcat( message, "     Buy a memory expansion!");
  128.   /* The NULL sign which finish of the second substring is */
  129.   /* automatically placed at position 56. */
  130.  
  131.   /* Fill the first substring with the position (x,y) */
  132.   /* (first 3 bytes) */
  133.   message[0]=0;  /* X position is less than 256, therefore 0. */
  134.   message[1]=32; /* 32 pixels out. */
  135.   message[2]=16; /* 16 lines down. */
  136.  
  137.   /* Add the NULL sign which finish of the first substring: */
  138.   /* (It was deleted when we connected the two strings with */
  139.   /* the strcat() function.)                                */ 
  140.   message[28]='\0';
  141.  
  142.   /* Set the Continuation byte to TRUE which tells     */
  143.   /* Intuition that there is another substring coming: */
  144.   message[29]=TRUE;
  145.   
  146.   /* Fill the second substring with the position (x,y): */
  147.   message[30]=0;  /* X position is less than 256. */
  148.   message[31]=32; /* 32 pixels out. */
  149.   message[32]=32; /* 32 lines down. */
  150.  
  151.   /* Set the Continuation byte to FALSE since there are */
  152.   /* no more substrings after this one: */
  153.   message[57]=FALSE;
  154.  
  155.  
  156.  
  157. 6.5  FUNCTIONS
  158.  
  159. DisplayAlert()
  160.  
  161.   This function activates an Alert message.
  162.  
  163.   Synopsis: result = DisplayAlert( nr, message, height ); 
  164.  
  165.   nr:       (long)  Value which describes if it is a
  166.             RECOVERY_ALERT or a DEADEND_ALERT.
  167.  
  168.   message:  (char *) Pointer to an array of characters (char). It
  169.             contains the strings we want to display, and some
  170.             extra information (position etc). The string itself
  171.             is divided into substrings, which all contain
  172.             information about its position etc.
  173.           
  174.             - 2 bytes (16-bit) which are used for the x position
  175.               of the text.
  176.             - 1 byte (8-bit) which is used for the y position of
  177.               the text.
  178.             - The text string which ends with a NULL ('\0') sign.
  179.             - A Continuation byte. If it is TRUE there is another
  180.               substring after this one, else this was the last
  181.               substring.
  182.  
  183.   height:   (long) The height of the Alert box.
  184.  
  185.   result:   (long) The function DisplayAlert() returns a boolean
  186.             value. If it is a RECOVERY_ALERT and the user pressed
  187.             the left mouse button it returns TRUE else, if the
  188.             user pressed the right mouse button, it returns
  189.             FALSE. If it is a DEADEND_ALERT the function will
  190.             immediate return FALSE.
  191.  
  192.  
  193.  
  194. 6.6  EXAMPLES
  195.  
  196. Example 1
  197.   This example displays an Alert message at the top of the
  198.   display.
  199.