home *** CD-ROM | disk | FTP | other *** search
/ Simtel MSDOS 1992 September / Simtel20_Sept92.cdr / msdos / turbopas / tp4menu1.arc / TP4MENU.DOC < prev    next >
Text File  |  1988-11-11  |  40KB  |  1,046 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.       Professional Program Shell for Turbo Pascal 4.0 developers.
  9.  
  10.                                 TP4MENU
  11.  
  12.                               Version 1.0
  13.  
  14.  
  15.       (c) Copyright BittWare Computing, 1988, ALL RIGHTS RESERVED
  16.  
  17.     
  18.  
  19.  
  20.  
  21.       Contents:
  22.  
  23.       License................................................. ii
  24.       Features................................................ iii
  25.       Order Form.............................................. iv
  26.       Files on this Disk...................................... v
  27.       General Information..................................... 1
  28.       Using the mouse......................................... 2
  29.       Using Demo Program...................................... 3
  30.  
  31.       Getting down to Development Work
  32.            Screen Pointers.................................... 4
  33.            Headers............................................ 5
  34.            Pull Down menus.................................... 6
  35.                  Without Data Entry........................... 8
  36.                  With Data Entry.............................. 9
  37.                  Complete Data Entry Example.................. 12
  38.                  Using Mask................................... 13
  39.                  Updating Menus............................... 14
  40.            Pick Lists......................................... 15
  41.            Help............................................... 16
  42.            Error Messages..................................... 17
  43.            General Windows.................................... 18
  44.  
  45.       Advanced Features
  46.            Using Disk to Save/Recall Menus.................... 19
  47.            Setting up HotKeys................................. 19
  48.       
  49.  
  50.  
  51.                                                                   ii
  52.                                  IMPORTANT!!!
  53.  
  54.       Make sure you READ and UNDERSTAND the ShareWare agreement 
  55.       below, BEFORE you use and/or redistribute this package. 
  56.              ^^^^^^
  57.       This software is intended to ease the development of a 
  58.       Professional User interface for your programs, and there are 
  59.       no royalties.  If you like this system, show your 
  60.       appreciation by registering your copy.  Print out the order 
  61.       form by typing: 
  62.  
  63.            dos>  print ordform.txt <cr> 
  64.  
  65.       Furthermore, you are allowed, and in fact encouraged, to pass 
  66.       this software along to anyone you wish, or to upload it to a 
  67.       bulletin board, provided the following criteria are met: 
  68.  
  69.       Absolutely NO MODIFICATIONS can be made when copying or 
  70.       redistributing this software.  Your unique registration 
  71.       number will already be on the order form when you purchase 
  72.       full registration, and you will receive a $5.00 commission 
  73.       when someone registers with your number. 
  74.  
  75.         1)  This software may not be sold for profit.
  76.             {public domain and user-supported software dealers please
  77.             contact us for permission}
  78.  
  79.         2)  The software and documentation may not be modified in 
  80.             any way, and redistributed.  This includes, but is not 
  81.             limited to, the copyright notices. 
  82.  
  83.         3)  ALL ORIGINAL documentation and files MUST be included.
  84.             ^^^                                  ^^^^
  85.         4)  The Source Code included with the registration can NEVER 
  86.             be copied or redistributed (copies for the sole purpose 
  87.             of backup/archive are allowed).  
  88.  
  89.       WARRANTY:
  90.       The author(s) and BittWare Computing make no warranty of any 
  91.       kind, expressed or implied. 
  92.  
  93.       DISCLAIMER:  
  94.       The author(s) and BittWare Computing do not assume any 
  95.       liability for the use of this software.  This includes but is 
  96.       not limited to lost profits, or other incidental damages, due 
  97.       to the use of this software.  
  98.  
  99.       By using this software you have agreed to all terms in this 
  100.       agreement. 
  101.       
  102.  
  103.  
  104.                                                                   iii
  105.       ShareWare for Turbo Pascal 4.0 Developers 
  106.  
  107.       This is NOT just a collection of routines, but a complete 
  108.       program shell. 
  109.            - Define your Menus and Variables
  110.            - Insert your procedures in the Supplied unit
  111.            - Compile
  112.  
  113.       POP-UP:  Header Select Lines, Pull-Down-Menus, Pick-From-List, 
  114.                Context-Sensitive Help, Errors, Windows 
  115.  
  116.       - Bullet-Proof Data Entry accomplished from Pull-Down-Menu or 
  117.       Window, includes line-editor
  118.  
  119.       - Pull-Down Menus can have options "masked."  Masked 
  120.       selections appear in a different color and are skipped over 
  121.       by highlight bar. 
  122.  
  123.       - Pick From List includes an example routine to pop-up a 
  124.       window and select a file with definable directory and search 
  125.       mask. 
  126.  
  127.       - Includes easy to understand Source Code for Example Shell, 
  128.       menu initialization, and global variables. 
  129.  
  130.       - User-definable window/menu colors, sizes, borders, titles, 
  131.       and placement 
  132.  
  133.       - Easily create context-sensitive help and error messages
  134.  
  135.       Autodetect and Support for VGA, EGA, CGA, ATT, and Monochrome
  136.       Microsoft Serial Mouse Driver (may support others)
  137.       NO Royalties!
  138.  
  139.       Complete Registration also includes:
  140.       ALL Source Code (additional source code is NOT shareware)
  141.       $5.00 sales commission on subsequent registrations with 
  142.       your number 
  143.  
  144.       
  145.  
  146.       Professional Program Shell for Turbo Pascal 4.0
  147.       Registration Number = 0000
  148.       Version = 1.0
  149.  
  150.       Check or Money Order Payable to:  "BittWare Computing"
  151.  
  152.       Mail To:  BittWare Computing
  153.                 P.O. Box 66164
  154.                 Baltimore, MD 21239
  155.       Phone:    (201)398-4669, until 11/15/88
  156.       Phone:    (201)455-1019, after 11/15/88
  157.  
  158.       For $10.00:
  159.            - Latest Version
  160.            - Documentation on Disk
  161.            - Source Code for interfacing/initializing menus
  162.            - Complete Source Code Example Shell
  163.            - Compiled Units (.tpu files) for actual menu/input routines
  164.            - NO royalties!
  165.            - Great feeling for participating in User-Supported Software 
  166.  
  167.       For $25.00 (TUG Members:  $20.00 with membership #)
  168.            - All of the Above PLUS
  169.            - Free Upgrade
  170.            - A unique Registration Number 
  171.              ($5.00 commission for all registrations made with your #)
  172.            - Full Source Code for Everything!
  173.  
  174.       Desired Features:________________________________________________
  175.  
  176.       _________________________________________________________________
  177.  
  178.       Any Known Bugs:__________________________________________________
  179.  
  180.       _________________________________________________________________
  181.  
  182.       We'll Customize a User Interface for you, contact for details.
  183.  
  184.       Are you interested in a Digital Signal Processing Workstation for 
  185.       the IBM PC?  ( )yes  ( )no
  186.  
  187.       Would you like to be put on our mailing list? ( )yes  ( )no
  188.  
  189.       ShareWare Copies @ $10.00 ea.   Qty. (   )     $_________
  190.  
  191.       Source Copies    @ $25/20* ea.  Qty. (   )     $_________
  192.  
  193.                                           Total      $_________
  194.       * TUG Membership # ____________
  195.  
  196.       Shipping Address:
  197.       Name:                    _____________________________
  198.  
  199.       Company, Mail Stop:      _____________________________
  200.  
  201.       Street:                  _____________________________
  202.  
  203.       City, State, Zip:        _____________________________
  204.       
  205.  
  206.  
  207.                                                                   v
  208.       Getting Started:
  209.            What the files are:
  210.  
  211.            README.DOC     :IMPORTANT INFORMATION, PLEASE READ!!
  212.            TP4MENU.DOC    :Documentation file, ready to print
  213.            ORDFORM.TXT    :Order form, ready to print
  214.            TP4MENU.EXE    :Ready to run demo program
  215.            TP4MENU.PAS    :Source code for main demo routine
  216.            PPS_GLOB.PAS   :Global variables, source 
  217.            PPS_INIT.PAS   :Menu Initialization code, source
  218.            PPS_USR.PAS    :User-Defined Procedures, source
  219.         *  INP_VAR.TPU    :Some input routines, object
  220.         *  BEEPKEY4.TPU   :Keyboard, sound routines, object
  221.         *  MENUVARS.TPU   :Menu Data Structures, object
  222.         *  MENUCODE.TPU   :Menu Manipulation, object
  223.         *  MENUMOUS.COM   :Ram-resident uSoft mouse interface
  224.            PPS_HELP.EXE   :Generates Help Message File, executable
  225.            PPS_HELP.PAS   :Generates Help Message File, source
  226.            TP4MENU.HLP    :Help message file
  227.            INSTALL.BAT    :Creates directory/copies files to harddisk
  228.  
  229.       * Source with registration
  230.  
  231.            Hard Disk Users:  Insert tp4menu floppy in drive a:, 
  232.       select drive a: and type install.bat.  This will create a 
  233.       directory off of the root (c:\tp4menu) and copy all 
  234.       necessary files. 
  235.       
  236.       
  237.  
  238.  
  239.                                                                   1
  240.       General Information:
  241.  
  242.       The best way to use this system is: 
  243.       
  244.       1)  Run the demo program for ideas on what the system can do 
  245.       
  246.       2)  Determine the features that are best for your application
  247.       
  248.       3)  Read the manual (tp4menu.doc) and look at the code
  249.  
  250.       The following files need to be modified in order to 
  251.       customize this program for your system: 
  252.  
  253.       You MUST rename these files and the corresponding include 
  254.       directives before modification.  Remember only unmodified 
  255.       files may be copied and redistributed. 
  256.  
  257.            1)  PPS_GLOB.PAS
  258.            2)  PPS_INIT.PAS
  259.            3)  PPS_USR.PAS
  260.            4)  TP4MENU.PAS
  261.            5)  PPS_HELP.PAS
  262.  
  263.       1.  PPS_GLOB.PAS includes the global variables that your 
  264.       procedures defined in #3 will use.  These variables should 
  265.       be initialized in the initialization section of this unit, 
  266.       as shown. 
  267.  
  268.       2.  PPS_INIT.PAS includes all the menu variable 
  269.       declarations, memory allocation for heap variables, and 
  270.       initialization of heap variables. This is where you will 
  271.       modify/create menus for your own application. 
  272.  
  273.       3.  PPS_USR.PAS is where the user-defined procedures are 
  274.       located.  This is where you can put the "meat" of your 
  275.       program.  The shell is currently set up to call these 
  276.       routines from the "Execute" part of the main menu, but you 
  277.       may call these routines from where-ever you like. 
  278.  
  279.       4.  TP4MENU.PAS is the main program.  This code consists 
  280.       mainly of case statements based on the menu selections.  
  281.       Here is where you set up what happens with the current menu 
  282.       choice. 
  283.  
  284.       5.  PPS_HELP.PAS is a separate program that generates the 
  285.       help message file.  Important note when editing this file 
  286.       is that the constants used here MUST be the same as those 
  287.       used in the main program.  The help constants for the demo 
  288.       routine are currently defined in the PPS_GLOB.PAS unit. 
  289.       
  290.  
  291.  
  292.                                                                   2
  293.       Using a mouse:
  294.  
  295.       The program menumous.com is a ram-resident mouse driver 
  296.       which works with the microsoft serial mouse (may also 
  297.       support others).  
  298.  
  299.            mouse movement ==> arrow keys
  300.            right button   ==> <enter>
  301.            left  button   ==> <esc>
  302.  
  303.       The mouse is a very effective means for using the menus.  
  304.       The only time the keyboard is actually required is for data 
  305.       entry. 
  306.  
  307.       To use the mouse driver:
  308.            - Install the mouse driver supplied with your mouse, 
  309.              probably mouse.com.
  310.            - type dos> menumouse <cr>
  311.  
  312.       Now moving your mouse will act like cursor keys, pressing 
  313.       the left button is the same as <esc> and the right button 
  314.       like <enter>. 
  315.       
  316.  
  317.       
  318.                                                                   3
  319.       Using Demo Program
  320.  
  321.       If you have a mouse, run mouse.com (mouse driver) and 
  322.       menumous.com (supplied) before running the demo. 
  323.  
  324.       To run the demo:
  325.  
  326.           dos> tp4menu <enter>
  327.  
  328.       Now, just play with the program a little bit, scroll 
  329.       through the menus, enter some data, try to fool the system.  
  330.       Press <F1> for help anywhere within the program.  The 
  331.       complete source code for the demo interface to the menu 
  332.       procedures is included as tp4menu.pas, (there is source 
  333.       code for some of the other units also.) 
  334.  
  335.       The examples given in the following text generally use 
  336.       source code from the demo program.  Familiarity with the 
  337.       demo program is essential for a good understanding of the 
  338.       text. 
  339.  
  340.       A good way to work is edit some of the menus in 
  341.       pps_init.pas and see how the changes affect the demo, BUT 
  342.       pps_init.pas MUST be renamed before editing.  When changing 
  343.       the name of any of the units, you will also need to change 
  344.       the name of the include directives in the corresponding 
  345.       units.  A good method of this is to use the "grep" program 
  346.       supplied with turbo 4.0.  For example, if you change 
  347.       pps_init.pas look for pps_init in the source code files:
  348.  
  349.       dos> grep -i pps_init *.pas
  350.  
  351.       File PPS_INIT.PAS:
  352.       unit pps_init;
  353.       File PPS_USR.PAS:
  354.            pps_init,
  355.       File TP4MENU.PAS:
  356.               pps_init,
  357.  
  358.       After renaming the file pps_init.pas you must also rename 
  359.       the unit name internal to pps_init.pas, and the include 
  360.       directives in pps_usr, and tp4menu.pas.  But, because 
  361.       you've now edited pps_usr and tp4menu, they must now be 
  362.       renamed.  The best thing to do is rename all source files! 
  363.  
  364.       To recompile, just use the make option
  365.  
  366.       dos> tpc /m tp4menu
  367.  
  368.       and make sure all source code, (or compiled units), are in 
  369.       the current directory. 
  370.       
  371.  
  372.  
  373.                                                                   4
  374.       Screen Pointers
  375.  
  376.       Most of the menus, PickLists, etc. require a pointer to a 
  377.       screen save buffer so the screen can be restored.  The 
  378.       following buffers have been defined in menuvars.pas.
  379.  
  380.           ScreenPtr         :pointer to 4000 bytes
  381.           HalfScreenPtr     :pointer to 2240 bytes (14 lines)
  382.           QuarterScreenPtr  :pointer to 1000 bytes
  383.           EighthScreenPtr   :pointer to 500 bytes
  384.  
  385.       Memory has been allocated as follows in pps_init.pas
  386.  
  387.        HelpScreen         :HalfScreenPtr;
  388.        HalfScreen1        :HalfScreenPtr;
  389.        HalfScreen2        :HalfScreenPtr;
  390.        QuarterScreen1     :QuarterScreenPtr;
  391.        EighthScreen1      :EighthScreenPtr;
  392.        EighthScreen2      :EighthScreenPtr;
  393.        TextScreen         :ScreenPtr;
  394.  
  395.        new(HelpScreen);
  396.        new(HalfScreen1);
  397.        new(HalfScreen2);
  398.        new(QuarterScreen1);
  399.        new(EighthScreen1);
  400.        new(EighthScreen2);
  401.        new(TextScreen);
  402.  
  403.       
  404.  
  405.  
  406.                                                                   5
  407.       Create/Use program Header:
  408.  
  409.       Create program Header:
  410.       All modification is done in PPS_INIT.PAS, and an actual 
  411.       example is given from that file. 
  412.  
  413.            1) define variable
  414.                      HdrList        :HdrPtr;
  415.  
  416.            2) allocate memory on heap
  417.                      new(HdrList);
  418.  
  419.            3) initialize variables
  420.  
  421.       {the ".str" variables set what text is displayed}
  422.       {".max" is the number of selections available up to a max of 6}
  423.       {".sel" item currently selected, initialized in this case to 1}
  424.       {the colors for this variable are set in the initialization}
  425.  
  426.            MenuSelFg      :Foreground color, item is selected
  427.            MenuSelBg      :Background color, item is selected
  428.            MenuNoSelFg    :Foreground color, item is NOT selected
  429.            MenuNoSelBg    :Background color, item is NOT selected
  430.  
  431.            HdrList^.str[1]   := 'Execute';
  432.            HdrList^.str[2]   := 'File Select';
  433.            HdrList^.str[3]   := 'Data Entry';
  434.            HdrList^.str[4]   := 'Quit';
  435.            HdrList^.max      := 4;
  436.            HdrList^.sel      := 1;
  437.  
  438.       Use Program Header
  439.            1) set byte variable to PickHeader(RowNumber,HeaderVar)
  440.  
  441.       var
  442.                 menu1         :byte;
  443.       begin
  444.                 menu1 := PickHeader(1,HdrList);
  445.                 case menu1 of
  446.                         1:  begin
  447.                                       {pull down execute menu}
  448.                                       {see next section for details}
  449.                             end;
  450.                         2:  begin
  451.                                       {File Select}
  452.                             end;
  453.                         3:  begin
  454.                                       {Data Entry}
  455.                             end;
  456.                         4:  begin
  457.                                       {exit procedure}
  458.                             end;
  459.                 end;
  460.       end.
  461.       
  462.  
  463.  
  464.                                                                   6
  465.       Create/Use Pull Down Menus
  466.  
  467.       There are 2 different ways to use the pull down menus:
  468.               1)  Menu selection
  469.               2)  Data Entry
  470.  
  471.       The two types are very similar, and in fact are the same data 
  472.       type.  In order not to waste memory, space is allocated 
  473.       specifically when variables are required.  See VarPtr in 
  474.       MenuPtrType below.  The VarPtr is explained in detail in the 
  475.       section on Data Entry Below. 
  476.  
  477.       Here is the data type defined in menuvars.pas.  Examples of 
  478.       implementation with/without data entry follow.
  479.  
  480.       type
  481.               MenuPtr         = ^MenuPtrType;
  482.               MenuPtrType     = record
  483.  
  484.       {text for selections}        str             :array[1..MenuMax] 
  485.                                                 of string[MaxTextWidth];
  486.       {selection "mask"}           SelPattern      :MenuString;
  487.       {number of selections}       max             :byte;
  488.       {item currently selected}    sel             :byte;
  489.       {upper-left, x-position}     x               :byte;
  490.       {upper-left, y-position}     y               :byte;
  491.       {column width, char's}       width           :byte; *
  492.       {width  of text portion}     TxtLen          :byte; *
  493.  
  494.       * Width should be equal to TxtLen for "No Data Entry"
  495.  
  496.       COLORS:
  497.       {border background}               BorderBg        :byte;
  498.       {border foreground}               BorderFg        :byte;
  499.       {not-masked,not selected}         Fg              :byte;
  500.       {masked foreground}               NoSelFg         :byte;
  501.       {selected item background}        SelBg           :byte;
  502.       {selected item foreground}        SelFg           :byte;
  503.       {unselected background}           NoSelBg         :byte;
  504.       {variables background}            VarBg           :byte;
  505.       {variables foreground}            VarFg           :byte;
  506.       {menu title, text}                title           :title_type;
  507.       {screen-save buffer pointer}      ScreenBufPtr    :Pointer;
  508.       {pointer to variables}            VarPtr          :Pointer;
  509.       {save old window up-left}         OldWindMin      :word;
  510.       {save old window lo-right}        OldWindMax      :word;
  511.                                      end;
  512.       
  513.  
  514.  
  515.                                                                   7
  516.  
  517.       The following examples are from pps_init.pas, source included.
  518.  
  519.       *Declare menus
  520.       var
  521.            PullDowns      :array[1..MaxPullDowns] of MenuPtr;
  522.  
  523.       *Allocate memory
  524.       *Initialize Masks to Full, and Color Defaults
  525.       begin
  526.            for indx := 1 to MaxPullDowns do begin
  527.                 new(PullDowns[indx]);
  528.                 for i2 := 1 to MenuMax do
  529.                      PullDowns[indx]^.SelPattern[i2] := '*';
  530.                 PullDowns[indx]^.BorderBg := MenuBorderBg;
  531.                 PullDowns[indx]^.BorderFg := MenuBorderFg;
  532.                 PullDowns[indx]^.Fg       := MenuHiFg;
  533.                 PullDowns[indx]^.SelFg    := MenuSelFg;
  534.                 PullDowns[indx]^.SelBg    := MenuSelBg;
  535.                 PullDowns[indx]^.NoSelBg  := MenuNoSelBg;
  536.                 PullDowns[indx]^.NoSelFg  := MenuLoFg;
  537.                 PullDowns[indx]^.VarFg    := MenuVarFg;
  538.                 PullDowns[indx]^.VarBg    := MenuVarBg;
  539.                 PullDowns[indx]^.VarPtr   := nil; {just to be safe}
  540.            end;
  541.       end;
  542.  
  543.       
  544.  
  545.  
  546.                                                                   8
  547.       *Initialize individual Menu
  548.       No Data Entry Example
  549.  
  550.       *Menu Text Initialization
  551.               PullDowns[ExeMenu]^.str[1]   := 'User 1 ';
  552.               PullDowns[ExeMenu]^.str[2]   := 'User 2 ';
  553.               PullDowns[ExeMenu]^.str[3]   := 'Good Beep ';
  554.               PullDowns[ExeMenu]^.str[4]   := 'Bab Beep ';
  555.               PullDowns[ExeMenu]^.max      := 4;
  556.               PullDowns[ExeMenu]^.sel      := 1;
  557.  
  558.       *Co-ordinates of upper-left corner
  559.               PullDowns[ExeMenu]^.x        := 1;
  560.               PullDowns[ExeMenu]^.y        := 2;
  561.  
  562.       *TxtLen and Width are equal for Non-Data Entry
  563.               PullDowns[ExeMenu]^.TxtLen   := 14;
  564.               PullDowns[ExeMenu]^.Width    := 14;
  565.               PullDowns[ExeMenu]^.title    := '';
  566.  
  567.               PullDowns[ExeMenu]^.ScreenBufPtr:= EighthScreen1; *
  568.  
  569.       *EighthScreen1 is a POINTER to adequate memory for width*height*2 
  570.       *of menu defined, here 1/8 of screen (500 bytes) is sufficient
  571.       *Hint, make sure two menus that use the same save buffer
  572.       *can NEVER be active simultaneously
  573.  
  574.       Using Pull-Down Menus, No Data Entry
  575.  
  576.               OpenPullDownMenu(PullDowns[ExeMenu]);
  577.                   Repeat
  578.                       Menu2 := PullDownMenu(PullDowns[ExeMenu]);
  579.                       Case Menu2 of
  580.                               1       :Do_User_1;
  581.                               2       :Do_User_2;
  582.                               3       :Good_Beep;
  583.                               4       :Bad_Beep;
  584.                       end; {case Menu2}
  585.                   Until( (Menu2 = 0) or Rtn2Main );
  586.               ClosePullDownMenu(PullDowns[ExeMenu]);
  587.  
  588.       The repeat, of course, is optional.  This shows how to repeat 
  589.       different operations until either <esc> or <F10> is pressed.
  590.       Rtn2Main is a global variable that gets set with <F10>.
  591.  
  592.       
  593.       
  594.       
  595.                                                                   9
  596.       Data Entry Example
  597.  
  598.       The "InpStrType" is defined in menuvars.pas
  599.       "Str" is what will be displayed in the menu
  600.       "Typ" defines the variable type, currently supported
  601.               int, longint, real, string
  602.  
  603.       type
  604.               InpStrPtr = ^InpStrType;
  605.               InpStrType = array[1..MenuMax] of record
  606.                              Str    :string[MaxTextWidth];
  607.                              Typ    :byte;
  608.                              Width  :byte;
  609.                           end;
  610.  
  611.       *declare variable
  612.       var
  613.               VarVars        :InpStrPtr;
  614.  
  615.       begin
  616.  
  617.       *allocate memory
  618.               new(VarVars);
  619.  
  620.               PullDowns[VarMenu]^.str[1]   := 'Set Mask';
  621.               PullDowns[VarMenu]^.str[2]   := 'String Var';
  622.               PullDowns[VarMenu]^.str[3]   := 'Real Var #1';
  623.               PullDowns[VarMenu]^.str[4]   := 'Real Var #2';
  624.               PullDowns[VarMenu]^.str[5]   := 'Int Var';
  625.               PullDowns[VarMenu]^.str[6]   := 'LongInt';
  626.               PullDowns[VarMenu]^.str[7]   := 'Auto Mode';
  627.               PullDowns[VarMenu]^.str[8]   := 'Pick Num';
  628.               PullDowns[VarMenu]^.str[9]   := 'Switch Var';
  629.               PullDowns[VarMenu]^.max      := 9;
  630.               PullDowns[VarMenu]^.sel      := 1;
  631.               PullDowns[VarMenu]^.x        := 1;
  632.               PullDowns[VarMenu]^.y        := 2;
  633.  
  634.       *set VarPtr = to pointer for variables allocated above
  635.               PullDowns[VarMenu]^.VarPtr   := VarVars;
  636.               PullDowns[VarMenu]^.TxtLen   := 14;
  637.               PullDowns[VarMenu]^.Width    := 28;
  638.               PullDowns[VarMenu]^.title    := 'Bullet-Proof Entry';
  639.               PullDowns[VarMenu]^.ScreenBufPtr:= EighthScreen1;
  640.  
  641.               PullDowns[VarMenu]^.SelPattern := MaskId[MaskVar];
  642.  
  643.       *The SelPattern is what "masks" out selections, see section 
  644.       *below on using masks for details. 
  645.       
  646.  
  647.  
  648.                                                                   10
  649.       Example from file PPS_INIT.PAS, procedure InitMenuVars
  650.       *initialize variables
  651.       *Please, don't be scared off by how this looks,
  652.       *it's really quite easy!
  653.       *There is a string variable which shows up when the menu is 
  654.       called, a variable which defines the type of variable at that 
  655.       location (i.e. string, integer, real, etc.), and a width 
  656.       variable which defines the character width.  If the width of the
  657.       variable is wider than the menu a separate window will 
  658.       automatically open up, demo example is file path.
  659.  
  660.       var
  661.            vp   :InpStrPtr;
  662.       begin
  663.       * vp = pointer to InpStrType (defined above), 
  664.               vp := PullDowns[VarMenu]^.VarPtr;
  665.  
  666.       * w = number of character spaces available, up to max
  667.       * for the above example (Width=28) - (TxtLen=14) - 2 ==> 12
  668.  
  669.        w := PullDowns[VarMenu]^.Width - PullDowns[VarMenu]^.TxtLen - 2;
  670.        for indx := 1 to 9 do 
  671.               vp^[indx].Width := w;
  672.  
  673.       * MaskVar is an example global variable which defines what 
  674.       * mask is active 
  675.       * StringCode tells entry routine this is a string 
  676.               vp^[1].Str := MaskList^.str[MaskVar];
  677.               vp^[1].Typ := StringCode;
  678.  
  679.               vp^[2].Str := StringVar;
  680.               vp^[2].Typ := StringCode;
  681.  
  682.       *For Variable initialization, variable values are converted to 
  683.       *strings for menu display (this is done automatically from now on)
  684.       *RealVar1 is a real variable which is initialized in pps_glob.pas
  685.  
  686.               vp^[3].Str := Real2Str(RealVar1,w,2);
  687.               vp^[3].Typ := RealCode;
  688.  
  689.               vp^[4].Str := Real2Str(RealVar2,w,2);
  690.               vp^[4].Typ := RealCode;
  691.  
  692.               str(IntVar,vp^[5].Str);
  693.               vp^[5].Typ := IntCode;
  694.       * integers can't be any longer than 6 chars (-32768)
  695.               vp^[5].Width := 6;
  696.  
  697.               str(LongIntVar,vp^[6].Str);
  698.               vp^[6].Typ := LongIntCode;
  699.               vp^[7].Str := OnOffList^.str[BoolVar];
  700.               vp^[7].Typ := IntCode;
  701.               str(MenuNum,vp^[8].Str);
  702.               vp^[8].Typ := LongIntCode;
  703.               vp^[9].Str := VarTypeList^.str[FrChgVar];
  704.               vp^[9].Typ := IntCode;
  705.       
  706.  
  707.  
  708.                                                                   11
  709.       Data Entry Usage:
  710.  
  711.               All that has to be done is call the routine 
  712.       "inpvars" with the menu name, a return code (which is not 
  713.       used in most cases) and the address of the variable.  The 
  714.       routine inpvars "knows" which item is selected, and what 
  715.       data type it is, so the bullet proof entry takes over, and 
  716.       won't change the variable unless a valid entry is received.  
  717.       If an invalid entry is received, the error window pops up 
  718.       with the invalid entry-ignored message.  Pressing the <Esc> 
  719.       key aborts.  Usage and a complete example follow on the 
  720.       next page.
  721.  
  722.            The example gives the source code in tp4menu.pas for 
  723.       the data entry portion of the demo program.  This also 
  724.       shows how to use the ChgVar procedure which is how 
  725.       variables are "scrolled" through.  This also shows how the 
  726.       HelpNum changes so <F1> gives "context-sensitive" help.  
  727.       The usage of repeat, and update are also demonstrated.
  728.       Mvp is a pointer to InpStrType, much the same as Vp was in 
  729.       the initialization section.
  730.  
  731.       
  732.  
  733.  
  734.                                                                   12
  735.       Usage:
  736.               InpVars(PullDown Menu Name, Rtn Code, Variable Address);
  737.       
  738.       example:
  739.       var
  740.         mvp  :InpStrType;
  741.       begin
  742.         OpenPullDownMenu(PullDowns[VarMenu]);
  743.         repeat
  744.              HelpNum := DataEntryHelp;
  745.              UpdateMenu(PullDowns[VarMenu]);
  746.              menu2 := PullDownMenu(PullDowns[VarMenu]);
  747.              mvp := PullDowns[VarMenu]^.VarPtr;
  748.              case menu2 of
  749.                   1    :begin
  750.                             HelpNum := MaskListHelp;
  751.                             OpenPickList(MaskList);
  752.                                 menu3 := PickList(MaskList);
  753.                                    if menu3 <> 0 then begin
  754.                          mvp^[menu2].str := MaskList^.str[menu3];
  755.                          PullDowns[VarMenu]^.SelPattern := MaskId[menu3];
  756.                                    end;
  757.                             ClosePickList(MaskList);
  758.                        end;
  759.                   2    :InpVars(PullDowns[VarMenu],x,@StringVar);
  760.                   3    :InpVars(PullDowns[VarMenu],x,@RealVar1);
  761.                   4    :InpVars(PullDowns[VarMenu],x,@RealVar2);
  762.                   5    :InpVars(PullDowns[VarMenu],x,@IntVar);
  763.                   6    :InpVars(PullDowns[VarMenu],x,@LongIntVar);
  764.                   7    :begin
  765.                             HelpNum := ChgVarHelp;
  766.                             ChgVar(OnOffList,BoolVar);
  767.                             Mvp^[Menu2].str := OnOffList^.str[BoolVar];
  768.                             if BoolVar = 1 then CommandMode := true
  769.                             else CommandMode := false;
  770.                        end;
  771.                   8    :begin
  772.                             HelpNum := MenuNumHelp;
  773.                         GetMenuNum(MenuNum,SpclNum,Pulldowns[NumPtsMenu]);
  774.                             str(MenuNum,Mvp^[Menu2].str);
  775.                        end;
  776.                   9    :begin
  777.                             HelpNum := ChgVarHelp;
  778.                             ChgVar(VarTypeList,FrChgVar);
  779.                             Mvp^[Menu2].str := VarTypeList^.str[FrChgVar];
  780.                        end;
  781.              end;
  782.         until ((menu2=0) or Rtn2Main);
  783.         ClosePullDownMenu(PullDowns[VarMenu]);
  784.       end;
  785.       
  786.  
  787.  
  788.                                                                   13
  789.       Using the Pull Down Menu Masks:
  790.  
  791.       The menus have a variable called SelPattern in the 
  792.       PullDownMenu record, see complete record above. 
  793.  
  794.       The SelPattern is a string variable of length MenuMax 
  795.       (Maximum number of menus allowed in the PullDownMenus).  
  796.       When a PullDownMenu is opened or updated this variable is 
  797.       checked. 
  798.  
  799.               '*' ==> Unmasked
  800.               ' ' ==> Masked
  801.  
  802.       See Example Masks in the pps_init.pas file, and usage in 
  803.       the data entry portion of the demo, tp4menu.pas. 
  804.  
  805.       For example the Odd Mask might look like this
  806.           PullDowns[VarMenu]^.SelPattern := '* * * * * *';
  807.  
  808.       The Even Mask might look like this
  809.           PullDowns[VarMenu]^.SelPattern := ' * * * * * ';
  810.  
  811.       The Full Mask might look like this
  812.           PullDowns[VarMenu]^.SelPattern := '***********';
  813.  
  814.       The First Half Mask might look like this
  815.           PullDowns[VarMenu]^.SelPattern := '******     ';
  816.  
  817.       The Last Half Mask might look like this
  818.           PullDowns[VarMenu]^.SelPattern := '      *****';
  819.  
  820.       The true implementation has variables equal to each one of 
  821.       these patterns and the 
  822.  
  823.             PullDowns[VarMenu]^.SelPattern := MaskID[MaskVar]; 
  824.  
  825.       where MaskID[MaskVar] are the patterns shown above.
  826.       
  827.       See complete example on page 12.
  828.       
  829.  
  830.  
  831.                                                                   14
  832.       Using Update
  833.  
  834.       Update is a procedure that is called whenever a parameter, 
  835.       or mask has changed in a PullDownMenu without closing and 
  836.       reopening the menu.  Update does exactly that, it updates 
  837.       the menu on the screen to the current status.  If the new 
  838.       mask masks out the item currently selected, the mask is 
  839.       changed to allow the current selection.  Update also 
  840.       reflects the new values of any variables being displayed. 
  841.  
  842.       Usage:
  843.           UpdateMenu(MenuName);
  844.  
  845.       Example:
  846.           UpdateMenu(PullDowns[FileMenu]);
  847.  
  848.       See complete example on page 12.
  849.       
  850.       
  851.       
  852.       
  853.                                                                   15
  854.       Pick Lists
  855.  
  856.       Pick Lists are used much the same as the pull down menus 
  857.       without data entry.  The window is opened, a variable is 
  858.       set to a function call (PickList) and the window is closed.  
  859.       Either the selection value is returned, or 0 if <Esc> is 
  860.       pressed.  Simple! 
  861.  
  862.       usage:
  863.               OpenPickList(ListName);
  864.               ByteVariable := PickList(ListName);
  865.                       Case ByteVariable of
  866.                               1       :
  867.                               2       :
  868.                       end;
  869.               ClosePickList(ListName);
  870.  
  871.       ListName is of type PickListPtr which points to:
  872.  
  873.               PickListPtrType = record
  874.                       str          :array[1..PickListMaxStr] of 
  875.                                           string[PickListStrW];
  876.                       max          :integer;
  877.                       maxX         :byte;
  878.                       sel          :byte;
  879.                       y            :byte;
  880.                       x            :byte;
  881.                       title        :title_type;
  882.                       ScreenBufPtr :Pointer;
  883.                       OldWindMin   :word;
  884.                       OldWindMax   :word;
  885.                       BorderBg     :byte;
  886.                       BorderFg     :byte;
  887.                       Fg           :byte;
  888.                       SelBg        :byte;
  889.                       NoSelBg      :byte;
  890.                       NoSelFg      :byte;
  891.               end;
  892.  
  893.       All Variables should be obvious, except MaxX which is the number 
  894.       of selections on each line.
  895.  
  896.       A pick list usage example is included in the data entry 
  897.       example on page 12.
  898.       
  899.       
  900.       
  901.                                                                   16
  902.       Help Messages
  903.  
  904.       Help files are first generated using pps_help.pas.  To 
  905.       create help, just assign a constant equal to the help name 
  906.       and define a record for that assignment.  Then within the 
  907.       main program code, set the variable HelpNum equal to the 
  908.       constant.  Constants must be defined consistantly in both 
  909.       the pps_help.pas and the main program, or in an included 
  910.       unit such as pps_glob.pas. 
  911.  
  912.       There is a variable within the help record called NextRec, 
  913.       which should be set to the constant for the next page of 
  914.       the help, or set to 0 for the last page (or if there is 
  915.       only one page). 
  916.  
  917.       A help procedure is automatically called with the current 
  918.       help number (global variable HelpNum) whenever F1 is 
  919.       pressed. 
  920.       
  921.       Below is the record which is stored on disk for each help 
  922.       message. 
  923.  
  924.       HelpMessType = record
  925.             {NextRec = 0 if last, else}
  926.             {NextRec = Seek Number of Next "Page" of Message}
  927.             NextRec  :integer;
  928.             Str      :array[1..MaxHelpLines] 
  929.                       of string[HelpLineWidth];
  930.       end;
  931.       
  932.       Usage for Creating help in pps_help.pas:
  933.       const
  934.           MainHeader = 1;
  935.       begin
  936.           HelpVar[MainHeader].NextRec := 0;
  937.           HelpVar[MainHeader].str[1] := 'Welcome to the ...';
  938.           HelpVar[MainHeader].str[2] := 'This Help utili...';
  939.           HelpVar[MainHeader].str[3] := 'current choices...';
  940.           HelpVar[MainHeader].str[4] := 'Select an item,...';
  941.       ...
  942.       end;
  943.  
  944.       Help Usage, tp4menu.pas 
  945.       
  946.       const {constants may defined anywhere like pps_glob.pas}
  947.           MainHeader = 1;
  948.       begin
  949.           HelpNum := MainHeader;
  950.       ...
  951.       end.
  952.  
  953.       Now whenever <F1> is pressed the preceding message is 
  954.       displayed in the "help window."
  955.       
  956.       
  957.       
  958.                                                                   17
  959.       Error Messages
  960.  
  961.       Contrary to Help messages, Error messages are stored in 
  962.       memory.  This gives an example of each so the user can 
  963.       decide which method is best for their application. 
  964.  
  965.       There is an array defined ErrorMessStr which contains the 
  966.       messages that will be popped up when an error occurs.  The 
  967.       user should define constants that initialize the error 
  968.       message array, and set the global variable ErrorNum equal 
  969.       to that number when the error occurs.  The main routine 
  970.       checks for a non-zero condition of the ErrorNum and reports 
  971.       the error when it occurs. 
  972.       
  973.       Define Error constants in pps_glob.pas
  974.  
  975.       const
  976.       {Error Codes}
  977.            xyzError            = 1;
  978.  
  979.       Define the string that is to be displayed with the error
  980.  
  981.       ErrorNum := NoError; {initialize to no error}
  982.       ErrorMessStr[xyzError]    := 'xyz Error Occurred...';
  983.  
  984.       Have procedure set up error number
  985.       
  986.       procedure User_Proc;
  987.       begin
  988.           if xyz then ErrorNum := xyzError;
  989.       end;
  990.  
  991.       Usage in tp4menu.pas, when an error occurs
  992.       begin
  993.           User_Proc;
  994.           if ErrorNum <> NoError then ErrorMessage
  995.           else HunkyDory;
  996.       ...
  997.       end;
  998.       
  999.       
  1000.       
  1001.                                                                   18
  1002.       General Windows
  1003.  
  1004.       The error window is an example of a "general window."  
  1005.       Other examples are given in the pps_user.pas file as User1 
  1006.       and User2.  One general window defined is called IoList. 
  1007.  
  1008.       Example:
  1009.            OpenIoWindow(IoList);
  1010.                 do whatever you want
  1011.            CloseIoWindow(IoList); restores screen and returns
  1012.       
  1013.  
  1014.       
  1015.                                                                   19
  1016.       Advanced Features
  1017.  
  1018.       Saving/Restoring Menus (reduces code size significantly)
  1019.  
  1020.       There are two additional procedures included for this exact 
  1021.       purpose.  Edit the code in the pps_init.pas to run 
  1022.       SaveMenus after the initialization code has run.  Running 
  1023.       the program now will create a file with containing all the 
  1024.       menu information.  Next, comment out all the initialization 
  1025.       code (except for pointers which must be defined at run 
  1026.       time), and insert the RecallMenus procedure call.  The 
  1027.       pointer variables must be defined AFTER RecallMenus, 
  1028.       because pointers will be destroyed when RecallMenus is run. 
  1029.       
  1030.       In the demo program the savings are minimal because there are
  1031.       only 5 pull down menus, about 1500 bytes are cut off of the
  1032.       executable file, 5%.  The savings will become much more 
  1033.       substantial if the program is large.
  1034.  
  1035.  
  1036.       Setting up HotKeys
  1037.  
  1038.       Hot Keys are setup by editing the source code for the 
  1039.       BeepKey4 procedure (included with registration).  There is 
  1040.       one routine used for all keyboard entry (and mouse entry 
  1041.       for that matter), the hot key routines should be called 
  1042.       from here.  F1 is considered a hot key for help.  Whenever 
  1043.       F1 is pressed, the help procedure is called and the program 
  1044.       resumes where it left off.  The user may set up their own 
  1045.       hot key procedures in the same manner.  
  1046.