Programmer 7500/MAX_PROGRAMMERS.iso/INFO/TURBOPAS/MULTIMAP.ZIP/MULTIMAP.DOC

Text File | 1985-10-03 | 9.0 KB | 190 lines

    The procedures in Multimap.Box are intended to facilitate the handling of
display and data entry screens on an IBM-XT with the Color Graphics Adapter,
DOS 2.0, and Turbo Pascal.  Any compatibility with other personal computer is
strictly coincidental. However, any work-alike machine should be able to
handle these routines.

    Fields are "Mapped" onto the screen according to specified parameters.
Fields that can be updated have control records built in the Heap.  These
dynamic records are in the form of a circular linked list.  Cursor control
and positioning are supported.  Up to 8 video pages in 40 column mode and 4
pages in 80 column mode are supported and may be processed simultaneously.

    The primary procedures intended for use are as follows:

* Map(Text, Page, Line#, Column#, Foreground, Background);

    This procedure will write TEXT on page PAGE at line number LINE# and
column number COLUMN# in foreground color FOREGROUND and background color
BACKGROUND.  This procedure DOES NOT record any information about the text
that is written (ie. this is not for updateable fields).

    TEXT is defined as a String[80].

    PAGE is a valid video page.  Video pages are numbered 0 to 7 in 40 column
mode and 0 to 3 in 80 column mode.
    In 80 column mode if you specify a page greater then 3 the text will wrap
around to video page PAGE-4.  Thus pages 0 and 4 are the same, as are pages 1
and 5, 2 and 6, and 3 and 7.  It is therefore possible to define two distinct
areas on a given video page.

    Line# is a value between 1 and 25.

    Column# is a value between 1 and 80.

    Foreground and Background are byte values.  If the value for a foreground
or a background color is within the range of valid colors then the display
color will be changed to the specified color.  If the value is not within the
range then the current colors will be used.  See the Turbo Reference manual
for the range of valid colors.


* Init_Paging;  (No Parameters)

    Must be called once before any "Mapu's" (described below) are called.
This procedure initializes a table of pointer values to Nil preparing the
table for the subsequent recording of pointers values.

* MapU(Text, Page, Line#, Column#, Foreground, Background);

    This procedure is similar to MAP (above) and the parameters function the
same.  The difference is that this procedure DOES record information about
this field in a record on the Heap.  The Text will be displayed on the video
page but not recorded in the field record, therefore TEXT is an initial value
such as underscores or X's.  The number of characters in the initial value
determines the maximum size of the field.

* ReadMap(Page, Field);

    After you have created a page with Map and MapU you are ready to allow
the user to enter data on the screen. ReadMap is the procedure that does
this.

    Page is the page that you wish to process.

    Field is an Integer value indicating the number of the field that you
initially want the cursor to be positioned at.  Fields are numbered in the
same order as they are MapU'ed, hence the first field that is MapU'ed is Field
1, the second field MapU'ed is Field 2, and the Nth field Mapu'ed is Field N.
This is handy if there is a data entry error in a field: you can position the
cursor at the field in error.  Most times you will specify Field=1.

    Upon calling ReadMap several things happen.  First, the specified video
page is displayed. Then the cursor is positioned at the field specified.  If
there is an error locating the record for this field an error message is
displayed.  Now the user is ready to enter data onto the screen.  Characters
are displayed as they are typed and are also recorded in the field record in
the heap.  When the cursor reaches the end of a field it will jump to the next
field.  Pointers are updated to reflect the new field and processing continues
with this field.

    There are several cursor positioning keys at the user's disposal:

         Tab or Shift Tab positions the cursor at the next or previous field.

         Baskspace is defined to function the same as Shift Tab (there is no
             destructive backspace).

         The Home key will position the cursor at the first field.

         The End key will position the cursor at the last field.

         The left and right arrow keys move the cursor once space to the left
         or right.  When the cursor reaches the end or beginning of a field it
         will jump to the next field.

         The up and down arrow keys will move the cursor to the first field on
         the next or previous line.

         The Delete key will delete the character at the cursor position.

         The Insert key will insert one space at the cursor position.

    After calling ReadMap there are only three ways to leave the procedure:

    1.  A global Boolean variable called Functionkey_Pressed will be true.
        If this is the case then a global Byte variable called Functionkey
        will contain the number of the function key that was pressed.  Valid
        values will be from 1 to 40.  The extended function key values are
        obtained by pressing the Shift, Ctrl, or Alt key with a function key.

    2.  A global Boolean variable called Escape will be true.  Indicating that
        the Esc key was pressed.

    3.  A local Boolean variable called Return will be true.  If it's not
        Escape or Functionkey_Pressed then it had to be the return key.

*  some_variable := Get_Data( Page, Field);

    During the ReadMap procedure all data entered is stored on the heap.
Upon leaving Readmap it will be necessary to retrieve the data and possibly
store it in a record somewhere.  This is what Get_Data does.  Get_Data is
a function and must be used in an assignment statement.  Some_Variable should
be defined as a String variable.  The length may not be greater than 80
characters.  Page is the page number of a valid page.  Field is an Integer
expression indicating the number of the field that you want to retrieve (see
ReadMap about how fields are numbered).

Hint:  While numbers are used to indicate which field to retrieve, this does
       leave something to be desired in the area of readability in your source
       code.  If you define a type however, that contains names in the same
       order as the fields are MapU'ed, then you can use the Ordinal value of
       the name as the field number.

       Example:   Type Page1_Names = (Dummy,First,Middle,Last);
                  Begin
                   (* MapU's go here *)
                   First_Name := Get_Data(1,ord(First));
                  End;

       There must be a dummy value as the first value for the type because
       ordinal values start at zero but the Field records are number from
       one.

* DisplayPage( Page );

    Immediately displays the specified video page.

* Cursorsize(Start, Stop);

    Controls the appearance of the cursor.  Start is the beginning scan line.
Stop is the ending scan line.  Scan line are numbered 0 to 7 starting at the
top.  A normal cursor is (6,7).  To hide the cursor use (8,0).

* ClearPage( Page, Color);

    Erases a video page and establishes a background color.
    Page is a valid video page.
    Color is a valid background color.

* Reset_Page( Page );

    Use this to clean up the heap or to prepare to reuse a page that has been
    MapU'ed.  This procedure disposes of all records for the specified page
    from the Heap and sets this pages pointers, in the pointer table, to Nil.
    Other pages information is not changed.

The program Testmap.pas illustrates some of the techniques described here.
Compile it, run it, see if you like it.

NOTE:

    These routines are supplied as is, without warranty of any kind either
    expressed or implied.   The user is responsible as to the fitness and
    applicability of these routines to their particular application and/or
    hardware.  The supplier of these routines can not be held liable for
    consequential or inconsequetial damages or loss of data.

    Limited assistance is available through the TechMail Bulletin Board at
    [phone].  Leave a message, comment or suggestion.

    You may copy and distribute these routines provided that no portion is
    altered in any way.

    If you find that these routines are beneficial and useful to you,
    please support continued development by sending a contribution ($10 - $20)
    to:
         Terry Zuch
         P.O. Box 10371
         Harrisburg, Pa.  17105-0371