Programmer 7500/MAX_PROGRAMMERS.iso/PASCAL/SCREDIT2.ZIP/SKELETON.DOC

Text File | 1988-12-22 | 12.3 KB | 336 lines

   This program file is the skeleton code used by Turbo ScrEdit when it
   generates the programs that access the screens in a screen file.

   You may modify this file if you wish. DO NOT change any line that has
   words surrounded by "**". Turbo ScrEdit Locates these key words and
   replaces them with code needed for the screen files. You may change
   anything else that you wish.

   The discussion that follows will help you understand the way Turbo
   ScrEdit uses this code. The source code in this file has been divided
   into sections with labels surrounded by "**". In the text that follows
   I will describe the code that is inserted by Turbo ScrEdit following
   each of these labels. As you read the descriptions that follow, locate
   each label in the code below.

*Version*

   For Pascal:

   This section is where a $INCLUDE or USES statement is placed depending
   on the compiler that you select during source code generation. If you
   are using Turbo Pascal 4.0 or 5.0 a USES statement is placed here that
   will use the file ScrEd40.pas to compile the unit file ScrEd40.TPU. If
   you are using Turbo Pascal 3.0 then a $include statement will include
   the source file ScrEd30.pas at compile time.

   In either case the code used here contains all the procedures required
   to open, process, and close screen files.

   For C:

   This section is where a #include statement is placed. The code placed
   here contains all the procedures required to open, process, and close
   screen files.


*Buffers*

   When you create a screen using Turbo ScrEdit, a small file that contains
   the record definition and screen initialization procedures is created.

   This is where the screen buffers and initialization procedures will be
   placed. Turbo ScrEdit allows you to select whether the buffer modules
   are to be copied into the code at this point or included at compile time
   by using $include or #include statements.


*User Variables*

   Turbo ScrEdit will not place any additional code here. You may define
   your program's global variables and procedures beginning here.


* Example of loading and displaying screens *

  The entire procedure "Load_Screen" is intended to illustrate how to load
  and display screens in a screen file. You will probably want to delete
  this procedure and copy the "S_LoadScreen" statements into your own
  procedures.

  You may convert this into a working procedure for your programs by
  changing the procedure to:

  For Pascal:

      Procedure Load_Screen;
      Begin
      Case S_Num of

        Don't change anything between Case and End;

        End;
      End;


  For C:

      void Load_Screen();
      {
      switch (S_Num)
        {

        Don't change anything between switch and };

        }
      }

  If you make this change you can load a screen by assigning "S_Num" the
  screen number from the case statement that corresponds to the screen name
  that you want loaded. Be aware that Turbo ScrEdit will change the value
  of S_Num to the actual screen number in the screen file index.

  ** NOTE ** the field S_Num is defined in ScrEd30.pas or ScrEd40.tpu.
  All of the fields that have been defined for use with Turbo ScrEdit
  procedures start with "S_". Try not to use the "S_" naming convention
  in your programs to avoid having conflicts with Turbo Scredit.



*ScreenFileName*

   Turbo ScrEdit places the statement here that will  open the screen file.

   An important thing to know about this call is that it turns the system
   cursor off. If the program ends abnormally the cursor may be left off.
   To insure that the cursor is not left off, always call S_CloseScreenFile.
   S_CloseScreenFile is documented ahead in this document.


*InitRoutines*

   After the screen file is opened the screen buffer initialization
   procedures must be performed. There will be a procedure for each of the
   screens that were selected in the screen file when the source code was
   generated.

   ** IMPORTANT NOTE ** if for some reason the initialization procedures are
   not performed, your program will malfunction. Data will not be moved to
   and from the screen properly. In some cases your program will hang the
   system because data is being move to a memory location pointed to by
   memory pointers that have incorrect values. In most cases if you have
   problems using Turbo ScrEdit this will be the cause.


*System Switches*

  Turbo ScrEdit allows you to customize some features. You may change
  the values of these fields any time you wish in your program.


  S_Sound      + When set to TRUE will cause Turbo ScrEdit to Issue a
                 tone of (S_Freq) frequency and (S_Dur) duration.
               - When set to FALSE, no sounds will be issued no matter
                 what the values of (S_Freq) and (S_Dur) may be.
  S_Freq         Sound frequency
  S_Dur          Duration of tone

  S_ShowStatus + When TRUE, Turbo ScrEdit will display the status of the
                 keyboard switches INSERT, CAPS, NUMLOCK, and SCROLL LOCK
                 on the bottom line (25th) of the screen. The Status line
                 will be updated each time you call S_ReadField, S_ReadKey,
                 or S_ReadScreen.
               - When FALSE, No status line is displayed.

  S_Cursor     : This switch has three settings that can be used to define
                 the type of system cursor used in data entry fields.
                 S_Normal = Normal underline cursor.
                 S_Bold   = Block size cursor.
                 S_Off    = System cursor is removed from the screen and
                            a non blinking block cursor is used.

  S_Point      : Is used as an index of the screen fields.
                 Data entry will begin at the field pointed to by
                 S_Point. See the discussion of S_READSCREEN and
                 S_READFIELD for more information.

  S_Msg        : Is a string variable that can contain a string of up
                 to 78 characters. Any string of characters assigned to
                 this variable will be displayed on the bottom line of the
                 screen with the next call to S_READSCREEN, S_READFIELD, or
                 S_READKEY. After the call S_Msg is returned as null string.


* 1st Example Code *

  This code initializes the pointers used to control the next screen to be
  loaded by the demonstration part of this program. You will want to delete
  these lines when you build your own program.


There are three methods supported by Turbo ScrEdit to process your screens.

  S_READKEY    - returns a single key stroke in S_Ch and/or sets key flags.
  S_READFIELD  - reads data into one field on the screen and sets key flags.
  S_READSCREEN - reads data into all the data entry fields on a screen and
                 sets key flags.


* Demo Mode 2 * demonstrates S_READFIELD.

  This code is intended to illustrate how to read a single field at a time.
  When your program needs to have control between each field that the user
  keys you can use this method. Most of what you see in this code can be
  removed when you use it in a program. The Code that you would use will
  look like this:

  For Pascal:

       S_Point := field number;

       S_READFIELD;

  For C:

       S_Point = field number;

       S_ReadField();


  The field number that S_POINT is assigned can be found on the screen
  listing that is produced using the F5 option of Turbo ScrEdit's main
  menu, or if you don't have a printer you can number the fields with
  paper and pencil. Fields are numbered left to right and top to bottom.

  When you call S_READFIELD a number of things happen.

  - If you have set S_POINT to a display only field an error message will
    be displayed. Remember when you use this method of processing a screen
    you are taking responsibility to direct Turbo ScrEdit to the field that
    you want used.

  - Any values that have been moved to fields in the screen record are
    displayed on the screen.

  - If the field S_Msg has been assigned a message it is displayed on
    the bottom line of the screen.

  - Turbo ScrEdit then prompts the user to enter data into the field.

  Turbo ScrEdit will continue to accept keystrokes into the field until
  one of the following occurs:

  1 - Any of the special keys are pressed. See the section labeled
      "* special key testing *" for more info on what special keys are.

  2 - The Field is filled with keystrokes.

  3 - The Left or Right arrows are used to move the cursor off either
      end of the field.

  4 - The ENTER key is pressed.

  The field validation statements that are assigned to a field will only
  be used to test the contents of a field when conditions 2, 3, or 4 occur.

  * NOTE * remember that when the special keys are pressed, data entry
  ends and Turbo ScrEdit returns immediately to your program. Don't use
  the data returned in the field unless your program verifies that it
  is valid data. Keep in mind the only three conditions described above
  that Turbo ScrEdit will validate the data using processing
  specifications.


* Demo mode 0 or 1 * demonstrates S_READSCREEN

  The if statement here is only needed to make the example of using
  S_READSCREEN work in the demonstration mode 0 or 1. Your working code
  will look like this:

  For Pascal:

      S_READSCREEN;

  For C:

      S_ReadScreen();

  When you call S_READSCREEN a number of things happen.

  - Any values that have been moved to fields in the screen record are
    displayed on the screen.

  - If the field S_Msg has been assigned a message it is displayed on
    the bottom line of the screen.

  - If S_Point has been assigned a screen field number, data entry will
    begin on the specified field. If S_Point is set to a display only field
    or a non-existent field, Turbo ScrEdit will advance to the next data
    entry field on the screen.

    If the screen has no  fields Turbo ScrEdit calls S_READKEY and will
    return when the next key is pressed. The value of the key pressed is
    returned in the character field S_Ch.

    If the screen has only "display only" fields on it Turbo ScrEdit will
    call S_READKEY and return when the next key is pressed.

    If the screen has data entry fields on it, Turbo ScrEdit will accept
    data into the fields until a special keystroke is detected. See
    "* special key testing *" for more info on what special keys are.

  - When the ENTER key is pressed the entire screen is returned to your
    program. Any field validation specifications that have been defined
    for the fields on the screen are only considered when ENTER is pressed.

  When Turbo ScrEdit returns to your program from this call, S_Point will
  be set to zero for Pascal or -1 for C.


* Example code for demonstration mode * demonstrates S_READKEY.

  This code can be deleted and is only used to demonstrate using S_READKEY
  and providing a generic way of switching screens.

  In most cases you will use S_READKEY to prompt your user for a response.
  You could do something like this:

     Repeat
         S_Msg := 'Delete this record Y/N';
         S_ReadKey;
     Until UpCase(S_Ch) In['Y','N'];

  In this example several things happen:

  - The contents of the screen record are moved to the screen.

  - The message assigned to S_MSG is displayed on the bottom line of
    the screen.

  - Turbo ScrEdit waits until a key is pressed, and then returns the
    keystroke in S_CH.

  This example will continue prompting and displaying the message until
  either "Y" or "N" is pressed.

  S_READKEY does not have any connection with screen fields, the key pressed
  is returned to your program but not displayed on the screen.



* Special Key Testing *

  This code demonstrates the entire spectrum of special key strokes and
  combinations of key strokes that you can test for. The best way to
  understand this code is to try each condition as you run a program.


* Closing the screen file *

  If your program ends without closing the screen file the system cursor
  will be left off.

  If your program executes another program, close the file before executing
  the next program, and reopen the screen file when control returns.