RAMSES	Systems Ecology
Start         Modules:   A-Z   Function   Layer        QuickRefs:   DM   AuxLib   AuxLibE   SciLib   EasyMW   MW   ISIS   RMSLib

DEFINITION MODULE DMAlerts;

  (*******************************************************************

    Module  DMAlerts     ('Dialog Machine' DM_V3.0)

      Copyright (c) 1985-2006 by Andreas Fischlin and ETH Zurich.

    Purpose   Display alert messages.

    Remarks   Alerts serve the purpose of informing the user
              of anomalies, such as exceptional or erroneous
              program states or of some other warning messages
              the user must recognize.  He has to confirm that
              he has read the message by clicking a so-called
              "OK"-pushbutton before the program will allow
              him to continue.

              Method:  An alert window can be brought up in
              front of all other windows (ShowAlert or
              ShowPredefinedAlert).  It contains textual
              messages describing the anomaly or error
              condition which led to its dis- play.  An alert
              window is characterized by a double frame and
              the absence of the title bar.  The messages are
              produced by calling a procedure provided by the
              client program, which writes the text into the
              alert window by calling procedure WriteMessage
              (ShowAlert).  In case of ShowPredefinedAlert,
              all data displayed have to be provided in
              advance in the form of a resource of type "ALRT"
              (for details see Macintosh Development System
              tools: "Dialog Creator" or "ResEdit").  To get
              the user's attention the system sounds initially
              a couple of beeps or flashes the menu bar in
              case the current sound level has been set to
              zero.  Subsequently the user is forced into a
              modal dialog, which can only be terminated by
              clicking on the automatically added "OK"-push-
              button or by pressing one of its keyboard
              equivalents: the return or enter key.

              This module belongs to the 'Dialog Machine'.


    Programming

      o Design
        Andreas Fischlin          24/12/1985

      o Implementation
        Andreas Fischlin          24/12/1985


    ETH Zurich
    Systems Ecology
    CHN E 35.1
    Universitaetstrasse 16
    8092 Zurich
    SWITZERLAND

    URLs:
        <mailto:RAMSES@env.ethz.ch>
        <http://www.sysecol.ethz.ch>
        <http://www.sysecol.ethz.ch/SimSoftware/RAMSES>


    Last revision of definition:  29/01/1987  AI

  *******************************************************************)

    (***************************************************************

    Positions within the alert window are defined in coordinates of a
    cell grid, which has its origin in the upper left corner (1,1) of
    the alert window.   Each cell has a fixed size, which fits a
    character, and is denoted by its coordinates. Text is displayed
    by using the system font Chicago only. Strings may be positioned
    by specifying the coordinates of the first character. The
    automatically added "OK"-pushbutton is placed in the lower right
    corner and occupies 3 by 11 cells. A minimum alert size of 3 by
    20 cells will be used always.   The maximum dimensions are 19 by
    62 cells.

    ***************************************************************)

    PROCEDURE WriteMessage(line,col: CARDINAL; msg: ARRAY OF CHAR);
    (*Start writing message text msg at cell (line,col)*)

    PROCEDURE ShowAlert(height,width: CARDINAL; WriteMessages: PROC);
    (*
        Activates alert window with specified dimensions height
        and width given in cell units.  The message text is
        produced by a call to procedure WriteMessages, which
        must be provided by the client program.  Typically it
        contains calls to procedure WriteMessage.
    *)

    PROCEDURE ShowPredefinedAlert(fileName: ARRAY OF CHAR; alertID: INTEGER;
                                str1,str2,str3,str4: ARRAY OF CHAR);
    (*
        Activates a predefined alert window read from a Macintosh
        resource of type "ALRT" with ID = alertID contained
        in the resource fork of the file fileName.  In case that
        the fileName passed is empty, the default search strategy
        to find the resource is followed.   Up to four strings
        (str1, str2, str3, str4) may be specified in order to insert
        them at the place of the placeholders within the predefined
        text.   In order to perform correctly, the resource must
        contain just one control item: an "OK"-pushbutton.
    *)

END DMAlerts.