DP Tool Club 12/CD_ASCQ_12_0294.iso/vrac/panshr24.zip/PANELS24.DOC

Text File | 1993-11-17 | 16KB | 478 lines

  ▒▒▒▒▒▒▄ ▒▒▒▒▒▒▄ ▒▒▒▄▄ ▒▒▄ ▒▒▒▒▒▒▄ ▒▒▄     ▒▒▒▒▒▒▄              ▒▒▒▒▒▒▄
  ▒▒█▀▒▒█ ▒▒█▀▒▒█ ▒▒█▒▒█▒▒█ ▒▒█▀▀▀▀ ▒▒█     ▒▒█▀▀▀▀     F        ▒▒█▀▀▀▀
  ▒▒▒▒▒▒█ ▒▒▒▒▒▒█ ▒▒█ ▀▒▒▒█ ▒▒▒▒▒▄  ▒▒█     ▒▒▒▒▒▒▄       O      ▒▒█
  ▒▒█▀▀▀▀ ▒▒█ ▒▒█ ▒▒█   ▒▒█ ▒▒█▀▀▀  ▒▒█      ▀▀▀▒▒█         R    ▒▒█
  ▒▒█     ▒▒█ ▒▒█ ▒▒█   ▒▒█ ▒▒▒▒▒▒▄ ▒▒▒▒▒▒▄ ▒▒▒▒▒▒█              ▒▒▒▒▒▒▄
   ▀▀      ▀▀  ▀▀  ▀▀    ▀▀  ▀▀▀▀▀▀  ▀▀▀▀▀▀  ▀▀▀▀▀▀               ▀▀▀▀▀▀



                           Version 2.4

                        A User Interface























                           BC Systems
                          7801 Dublin
                       Wichita, KS  67206

                        CIS: 73171,2442


                  Copyright 1989-1993, Jay Brown


I. Overview

"Panels for C" is a set of routines which may be called by your
Application program to do screen oriented input and output.  Screen
layouts, or panels, are simple text files that you can create with
an ordinary word processor.  Panels always have a file extension of
PAN.  The format of a panel is covered in a later section.

A panel definition may reside in its own file separate from your
application source code, or it may be defined as a string within
your application code.  The advantage for a separate file is the
interpreted nature of the screen layout.  The panel may be changed
without recompiling the application program.  The advantage of
using a string to define the panel is reduced disk I/O during the
execution of your program.

The author recommends that during the development of an
application, panels are defined within their own files.  When an
application is compiled for production, you may consider moving the
panel definitions to the program source for efficiency and
security.  A utility call PAN2H has been created to translate a
panel file to a C header file.  Also, a utility to simplify the
creation and modification of panels has been developed, called IPD
(Interactive Panel Design).

Panels for C is distributed as shareware.  This software is
protected by copyright laws.  Users may register by purchasing
either the object or source packages, see the enclosed order form.
Registered users can expect the software to be supported by the
publisher.  Also, notification of future releases can be expected.
BC Systems grants to purchasers of either object or source packages
a no-fee license to resell applications created with the Panel
routines.  The only constraint is that the application code and
documentation MUST contain the following acknowledgement:

             Portions copyright 1989-1993, J. Brown.



II. Executing a Panels Program

While a panel is active, during the execution of a panels
application program, the following keys are used for data input:

<Right Tab>    Moves cursor to the next unprotected screen field.

<Left Tab>     Moves cursor to the previous unprotected screen
               field.

<Enter>        Moves cursor to the first unprotected screen field
               on the next line.

<Home>         Moves cursor to the first unprotected screen field.

<End>          Move cursor to the end of the current field.

<Ins>          Toggles insert mode on and off.  The cursor is a
               little larger when insert mode is on.

<Del>          Deletes the character under the cursor.

<Ctrl><End>    Erase to end of field.

<Arrows>       Moves the cursor in the appropriate direction,
               possibly into a protected area.  A click will be
               heard, if attempting to enter data into a protected
               area.

<Func keys> <Page Up> <Page Down> <Esc>
               When one of these keys is pressed execution returns
               to the application program.  These response keys
               are the default, and any keystroke can be
               configured as a response key by the application
               programmer.


III. Panel Design

                        Text File Format

A panel text file begins with an optional size statement followed
by an optional background statement.  One or more tag statements
are used to relate field attributes and field names to special
characters or symbols.  After the tag statements is the actual
screen layout, which must begin with a tagged symbol.

  size <ul_row> <ul_col> <lr_row> <lr_col>
  background <color>
  tag <sym> <attr> [<variable list>]
         .
         .
         .
  <symbol>..................................
  ..........................................
  ..........................................
         .
         .
         .


                         Size Statement

This is an optional panel statement, and if present must precede
the background statement or the first tag statement.  This
statement simply sets the size and location of the window in which
the panel will be constructed.

  Format:
    size <ul_row> <ul_col> <lr_row> <lr_col>

  where:
    <ul_row> upper left row of the window
    <ul_col> upper left column of the window
    <lr_row> lower right row of the window
    <lr_col> lower right window column

  Example:
    size 0 0 13 39  Defines a panel to be 14 rows by 40 columns
                    located in the upper left part of the screen.


If a size statement is not present within a panel definition, the
default window coordinates are 0,0 and 24,79.  If a panel is
defined to be smaller than the previous active panel, the previous
panel will be partially visible behind the new panel.  However, the
overlaid panel will not be active again until the new panel is
destroyed (i.e. no I/O functions may be performed on the previous
panel).


                      Background Statement

This is an optional panel statement, and if present must precede
the first tag statement.  This statement simply sets the screen
background color when a color adapter is in use.  If a monochrome
adapter is in use the background statement is ignored.

  Format:
    background <color>

  where:  <color> is a digit 0 - 7

  Color codes:  0 = Black (Default)
                1 = Blue
                2 = Green
                3 = Cyan
                4 = Red
                5 = Magenta
                6 = Brown
                7 = White


                          Tag Statement

A tag statement allows you to relate a special character or symbol
with a field definition.  This definition includes the field
attributes as well as the field names.

  Format:
    tag <sym> <attr> [<variable list>]

  where:
    <sym>      is one character symbol not used anywhere on the
               actual screen layout.  This symbol will relate
               screen attributes and field names to specific
               locations on the screen.

    <Attr>     is the field attribute.

  Attribute codes:
          P = Protected
          U = Unprotected (Default)
          H = High Intensity
          L = Low Intensity (Default)
          B = Blink
          R = Reverse
          _ = Underline
          D = Dark
          0 = Black
          1 = Blue
          2 = Green
          3 = Cyan
          4 = Red
          5 = Magenta
          6 = Brown
          7 = White (Default)

Some attributes may have no effect with certain monitor types (i.e.
the color codes will have no effect when using a monochrome display
adapter).  Some attributes are mutually exclusive -- either P or U
may be used, but not both; either H or L may be used; and only one
color code may be specified.

<variable list>     One or more field names separated by at least
                    one blank.  Valid names are no more than eight
                    characters beginning with a letter.  No
                    special characters are allowed.

Each variable or field name is matched to a field on the screen
layout.  If more fields are defined with the tag symbol than
variables in the list, the last variable name in the list is used
to name the remaining fields.  In this case, a subscript other than
1 is used to access like named fields.


                            Examples



In this example, there are two unprotected fields.  The first field
may be accessed using the name FIELD subscripted by 1, and the
second field is referenced as FIELD with a subscript of 2.

The screen background color is defined to be blue.  The ! symbol
defines protected red fields.  The @ symbol defines protected,
reverse fields with white characters.  The asterisk tagged field is
named SELECT and will be unprotected, underlined and green.

The screen background color is defined to be white.  The ! symbol
defines protected red fields.  This example demonstrates the use of
the size statement.  The panel is defined as a 7 x 27 character box
to be displayed in the lower right part of the screen.


                          Panel Design

Try your hand at designing your own panel!  Use any word processor
to create the panel file.  Be sure your file has an extension of
PAN.

Optionally, you may use IPD to create and modify a panel, type:

                           ipd [<fn>]

After your panel text file has been created, type:

                          showpan <fn>

where <fn> is your panel file name without the .PAN extension.


IV. 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 routine is used to initialize the Panels for C
     environment.  It determines what video adapter is in use, etc.
     This function must be called before any of the other functions
     are used.

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 the 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
     erroneous 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 hundredths of a second.

void pan_delay(int dur);

     Wait for at least dur hundredths 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
     panel_execute or 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.  The abort code of 16 should be used
     by the application program, other codes are used within the
     panel routines.

void pan_resp_keys(unsigned exitkeys[]);

     This function allows the programmer to override the default
     response keys.  An array of unsigned integers is passed.  The
     last value within the exitkeys table must be zero.

PAN_LIST *pan_linit();

     Allocate and initialize a list pick structure.  This function
     returns a pointer to the list pick structure.

void pan_ladd(PAN_LIST *list, char *desc, void *data);

     Add a list pick element to the indicated list structure.  desc
     is the text to appear in the list, and "data" is anything
     associated with the element and hidden from the user.

void pan_lfree(PAN_LIST *list, int free_desc, int free_data);

     Free all memory associated with the indicated list structure.
     "free_desc" is a flag indicating whether to free memory
     associated with each list item description.  "free_data" is a
     flag indicating whether to free memory associated with each
     hidden data object.

void pan_lact(PAN_LIST *list);

     This function activates the indicated list structure, i.e.
     makes it visible to the user.

unsigned pan_lexec(PAN_LIST *list);

     This function executes the indicated list structure, i.e.
     allows the user to make a selection.  The exit key code is
     returned by this function.


V. Compilation and Linkage

Included in the Panels for C package is one or more of the
following object files:

     SPANELR.OBJ    MicroSoft C DOS small model
     LPANELR.OBJ    MicroSoft C DOS large model
     SPANELP.OBJ    MicroSoft C OS/2 small model
     LPANELP.OBJ    MicroSoft C OS/2 large model
     SPANELTC.OBJ   Turbo C DOS small model
     LPANELTC.OBJ   Turbo C DOS large model


                           MicroSoft C

Assuming you have written a DOS program to be compiled with
MicroSoft C, you could use one of the following commands to compile
and link it with the Panel routines:

     Small model:
          cl /AS /F 2000 YourPgm.c spanelr.obj

     Large model:
          cl /AL /F 2000 YourPgm.c lpanelr.obj

The /F option sets the size of the program stack for the executable
file.  This must be set to an adequate value.  A makefile is also
included in the package to illustrate how panel programs are built.


                             Turbo C

Using the Turbo C integrated development environment, create a
project file with your source file name and either SPANELTC.OBJ or
LPANELTC.OBJ listed in it.  Select the make EXE option from the
compile menu.

For other compilers, consult your reference manual.  Be sure to
include the files PANEL.H and KEYS.H in your source code.