+                        PROGRAMMING WITH PANELS


    Only a few Panel routines are needed to do complete screen level I/O
    with your application program.  What follows here and on subsequent pages
    is a description of each routine available to link with your program.

+   void pan_init();

    This function performs miscellaneous initialization tasks and must
    be the first panel function called by the application program.

+   void pan_activate(char *fn);

    This routine will paint the screen using the panel defined in the text
    file <fn>.pan.  Memory is allocated for a panel variable table.  If
    a panel was previously active it will exist behind the new panel.
    Optionally, the character string fn may be a complete panel definition.
    The activate function determines whether the string is a file name or
    a panel definition by the presence or absence of a newline character
    within the string.  A file name will not have a newline character in it.

+   unsigned pan_execute(char *name, int sub, int alarm);

    Positions the cursor to the named field or first unprotected field if
    name is null.  Sub is the subscript of name field.  A bell will sound
    if alarm is true.  Control will return from this routine when a response
    key is pressed.  The response key code (as defined in keys.h ) is the
    return value.

    The following is a list of global variables assigned values by the
    pan_execute function:

       pan_row         Indicates the row on which the cursor was placed
                       prior to detecting a response key from the user.

       pan_col         Indicates the column on which the cursor was placed
                       prior to detecting a response key from the user.

       pan_field_name  Indicates the current field name under the cursor
                       when the user pressed a response key.

       pan_field_sub   Indicates the current field subscript under the
                       cursor when the user pressed a response key.


+   void pan_destroy();

    This routine frees memory occupied by the panel variable table and
    restores the panel behind the active panel if present.

+   void pan_field_attr(char *name, int sub, char *attr);

    Changes the screen attributes of the named panel field after the
    panel has been activated.  Useful for indicating an error to the user
    by highlighting or blinking the contents of the erronious field.

+   void pan_put_field(char *name, int sub, char *value);

    This routine transfers value to the named panel field.


+   void pan_get_field(char *name, int sub, char *value);

    This routine transfers the named panel field to  value .

+   void pan_sound(int freq, int dur);

    Produces a sound of freq frequency and at least dur duration on the
    speaker.  The duration is in hundreths of a second.

+   void pan_delay(int dur);

    Wait for at least dur hundreths of a second to elapse.

+   unsigned pan_get_key();

    Wait for a keystroke from the user and return the key code as defined
    within the KEYS.H header file.

+   void pan_idle_func(int (*func)());

    Sets up a user supplied function to be called while pan_execute or
    pan_get_key is waiting for a keystroke from the user.  func is a
    pointer to a function which returns an integer value.  The NULLF
    value, defined within panel.h may be used to disable an idle
    function call.

+   void pan_error(16, int line, char *msg);

    Abort the application program by cleaning up any active panels.  This
    function then displays the msg parameter and line number if not zero.

+   void pan_resp_keys(unsigned resp_keys[]);

    This function allows the programmer to override the default set of
    response keys.  The argument is a table to key codes terminated
    with a zero entry.


                           *** END OF TOPIC ***
