18


MFP EXAMPLE LISTING (cont'd)                                            mfp

 221:                          "This value must be entered",
 222:                          "in light years. Fractional",
 223:                          "light years are permitted.",
 224:                          0
 225:                      };
 226:  char *mass_txt[] =  {   "Please enter the systems",
 227:                          "total mass in grams.",
 228:                          "",
 229:                          "This includes all masses",
 230:                          "that rotate around the",
 231:                          "center of mass of this",
 232:                          "system.",
 233:                          "",
 234:                          "Planetary bodies can be",
 235:                          "ommitted if no data is",
 236:                          "present.",
 237:                          0
 238:                      };
 239:  char **help_txt[] = {   name_txt,
 240:                          size_txt,
 241:                          lux_txt,
 242:                          alux_txt,
 243:                          sftp_txt,
 244:                          age_txt,
 245:                          magn_txt,
 246:                          ltyr_txt,
 247:                          mass_txt
 248:                      };
 249:  
 250:  void inst( void )
 251:  {
 252:      int x = 0;
 253:      color( WHITE, BLACK );
 254:      wcls( 5,50, 21,79 );
 255:      while( help_txt[ mfp_field ][ x ] )
 256:      {
 257:          cup( 7+x,50 );
 258:          print( help_txt[ mfp_field ][ x++ ] );
 259:      }
 260:  }
 261:  
 262:  void help( void )
 263:  {
 264:      char buf[ 4096 ];
 265:      scrswp( buf, 0 );
 266:      color( BLACK, WHITE );
 267:      wcls( 24,1,25,80 );
 268:      mess24("Your outta luck: no help available, press any key...");
 269:      pause();
 270:      scrswp( buf, 1 );
 271:  }





                                      19


MFP EXAMPLE LISTING NARRATIVE                                           mfp




    Lines 1 - 5:

      Includes for the prototypes and defines for the standard C functions
      used.

    Line 6:

      Include file needed to use MFP.

    Lines 8 - 12:

      Prototypes of the functions used in this example.

    Lines 14 - 22:

      Definition and intialization of variables to be used for data entry.
      This definition must preceed the MFP field definitions.

    Lines 24 - 32:

      An MFP entry field must be defined in this manner: MFP is a typedef
      and must preceed the MFP entry field variable, in this case the
      entry field variable would be ln1. The entry field variable must be
      an array defined with an open and close bracket. The entry field
      variable is initialized using the equal sign and enclosing the entry
      field parameters within braces. A semicolon must terminate each field
      definition.

    Line 24:

      Definition of a 20 character entry field for the name array. The entry
      data will be upper case and be positioned at row 5 column 20. It will
      have a black foreground and a white background. There is a prevalidation
      function called inst(). No post validation has been defined.

    Line 25:

      Definition of a 2 digit short integer entry field for the short integer
      binarys variable. Notice the ampersand, (&) preceeding the binarys
      variable name. This is absolutely neccessary because MFP needs a pointer
      to the data. This is not the case with character arrays because the name
      alone is the pointer. So all numeric variables must be preceeded with
      the ampersand in the MFP declaration. The picture uses the same format
      as printf(). This is the case for all numeric entry fields.

    Lines 26 - 32:

      Differ in the variable type and entry field size. These examples 
      represent all the variable types MFP can deal with. The entry field 
      length, decimal points, screen position and color are defined by you.



                                      20


MFP EXAMPLE LISTING NARRATIVE (cont'd)                                  mfp


    Line 34:

      Definition of the MFP list. The definition of this variable is
      straightforward enough. MFP needs a list of pointers to each entry
      field. The pointer to an entry field is its name without the array
      brackets. This variable happens to be called "lst". MFP will allow input
      into each field defined in "lst" and in the order that you put each entry
      field into lst. You can put whatever entry fields you want in whatever
      order you desire. The entry field must be defined prior to defining the
      list.

             -- All MFP lists must be terminated with a zero --

      All entry fields must be seperated by commas inside the MFP list.
      The list variable must be defined as an array of pointers to variables
      of type MFP. That is why lst is prefixed by an asterick and suffixed
      by an open and close bracket. This list variable called lst will be
      passed to MFP as it's first parameter.

    Line 36:

      Definition of a HOT key procedure. PROC is a typedef needed to define
      a procedure variable, in this case p1. The PROC variable must be
      declared as an array with an open and close bracket. The PROC variable
      is initialized using the same technique as MFP. The first parameter
      must be the keyboard key that will activate this PROC.

      Many of the keyboard keys have been defined for clarity. Any key that
      the inkey() function can sense is legal for a PROC. The inkey() function
      is used by MFP for all keyboard I/O this is why the PROC must use the
      value of the key returned by inkey(). In this example the FN1 definition
      evaluates to Function key 1 or "F1".

      The second parameter seperated by a comma is a pointer to the function
      that will execute when the key is pressed. A pointer to any function
      is its name without the open and close parenthesis. In this example
      a pointer to the function help() is used. The function must have been
      previously prototyped. In this example help() was prototyped in line 11.

    Line 37:

      HOT key PROC definition that sets up function key 2 to execute a
      function called fast(). The function fast() is a special function
      defined and programmed in the MFP library. It is prototyped in the mfp.h
      header. The fast() function places numbers in each entry field and
      prompts the user for which entry field they want to edit. When the user
      keys in the field number they are positioned into that field and are
      allowed to edit the data in that field. When they are finished editing,
      the fast() function terminates and the user is positioned back to the
      field they were previously editing. We suggest that you incorporate this
      feature into your applications - especially in screens with a large
      number of entry fields. If a user makes a mistake in a previous field or
      just wants to change one field's contents, the fast() function will be
      easier than moving up or down to the field to be changed.

                                      21


MFP EXAMPLE LISTING NARRATIVE (cont'd)                                  mfp




      These HOT key PROC's only execute when mfp(), menu(), or scrn() are
      active. This should present little-to-no difficulty since most of the
      time your programs will be executing these functions awaiting user input.

    Line 39:

      Definition of the PROC list needed by MFP. This list which is called
      plist must be passed as the second parameter to MFP or scrn(). The PROC
      list must be defined in the same manner as the MFP list. It also must
      be terminated with a zero, to define the end of the list.

    Line 44:

      Calls the function to draw the screen and the screen header is passed 
      as it's parameter.

    Line 45:

      Calls the function that displays the field prompts.

    Line 48:

      Calls the function to display the passed text on row 24.

    Line 49:

      Defines a global variable called "ed_list" to point to the MFP list,
      lst. The ed_list variable is the same variable type as the MFP list
      except it is used for the fast() function. If you are going to use the
      fast() function and you are including it into your PROC list you must
      define the ed_list variable. Most of the time you will define it as the
      same list as your MFP list. Sometimes you may want to define it as ano-
      ther list, to exclude or include other fields that are, or are not, acc-
      essable otherwise. The ed_list variable is initialized in the MFP library
      as pointing to nothing or NULL. If you find that the fast() function is
      doing nothing, check your ed_list definition. It must be defined before
      calling mfp().

    Line 50:

      This is the magic moment, here we call MFP. The parameters are lst
      and plist. By now we know what these parameters are and how they are
      defined. At this time the fields are displayed and the user is capable
      of performing data entry. When the user exits the last field or ends
      the edit session, mfp() returns.

    Line 51:

      Display to the user the available options on row 24.




                                      22


MFP EXAMPLE LISTING NARRATIVE (cont'd)                                  mfp



    Lines 52 - 56:

      Await a response from the user. The inkey() function operates exactly
      like BASIC's INKEY statement. It tests the keyboard buffer for a charac-
      ter, if none exists it returns with a NULL. Otherwise, it returns with
      an integer value representing the key pressed. So we wait as long as no
      key is pressed.

    Line 57:

      Converts the key to it's uppercase equivalent.

    Lines 58 - 63:

      Determine the course of action to be taken based upon the key pressed.
      If the user responds by pressing the 'e' or 'E' key the user will be
      looped back into another edit session.

    Line 64:

      Sets the color to a white foreground and a black background in prepar-
      ation of exiting to DOS.

    Line 67:

      This is the function header for a draw screen function. The parameter
      header is used for the screen header.

    Line 72:

      Calls the clear screen function clrscr().

    Line 74:

      Calls the window or block clear screen. The function wcls() will clear
      a rectangular area of screen defined by upper left and lower right co-
      ordinates.

    Lines 76 - 85:

      Draws three vertical lines. The cup() function is used for <CU>rsor
      <P>ositioning. The row parameter is first followed by the column. The
      top left position would be cup( 1,1 ).

    Line 88:

      Displays the date in the upper left of the screen. The ldate() function
      is used which returns a pointer to the character array supplied. This 
      array is stuffed with the current date retrieved from DOS.

    Line 90:

      Displays the time in the same manner as the date was displayed.

                                      23


MFP EXAMPLE LISTING NARRATIVE (cont'd)                                  mfp



    Lines 100 - 123:

      This is the function that displays the prompts on the screen.

    Lines 125 - 131:

      Displays a message of text on row 24 of the screen.

    Lines 133 - 238:

      These are the help text strings, defined as an array of pointers for
      each field.

    Lines 239 - 248:

      Defines a single variable as a pointer to an array of pointers. The 
      pointers are the help text. This simplifies coding of the online context
      sensitive help demonstrated here.

    Line 250:

      This is the function header for the inst() function that is the common
      prevalidation function used in all the entry fields.

    Line 252:

      Initializes and defines variable 'x'. This variable will be used to
      index through the lines of help text.

    Line 254:

      This clears the area of the screen right of the entry fields reserved
      for the help text.

    line 255: