home *** CD-ROM | disk | FTP | other *** search
/ Phoenix CD 2.0 / Phoenix_CD.cdr / 02a / pull55.zip / PULL55.DOC < prev    next >
Text File  |  1989-08-24  |  175KB  |  3,882 lines

  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.                                    MULTI-LEVEL PULL-DOWN MENUS
  20.                                           USER'S GUIDE
  21.  
  22.                                            Version 5.5
  23.                                          August 24, 1989
  24.  
  25.  
  26.                        Copyright (C) 1987-1989 Eagle Performance Software
  27.                                       All Rights Reserved.
  28.  
  29.  
  30.  
  31.                                        _______
  32.                                   ____|__     |               (tm)
  33.                                --|       |    |-------------------
  34.                                  |   ____|__  |  Association of
  35.                                  |  |       |_|  Shareware
  36.                                  |__|   o   |    Professionals
  37.                                -----|   |   |---------------------
  38.                                     |___|___|    MEMBER
  39.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  40.  
  41.  
  42.  
  43.                                T A B L E   O F   C O N T E N T S
  44.  
  45.                 1. INTRODUCTION  . . . . . . . . . . . . . . . . . . . . . 4
  46.                      Features .  . . . . . . . . . . . . . . . . . . . . . 4
  47.                      Using the Manuals . . . . . . . . . . . . . . . . . . 4
  48.                      Licensing . . . . . . . . . . . . . . . . . . . . . . 5
  49.                      Customer Service  . . . . . . . . . . . . . . . . . . 5
  50.                      ASP . . . . . . . . . . . . . . . . . . . . . . . . . 6
  51.  
  52.                 2. GETTING STARTED . . . . . . . . . . . . . . . . . . . . 7
  53.                      Distribution Files  . . . . . . . . . . . . . . . . . 7
  54.                      Demonstration . . . . . . . . . . . . . . . . . . . . 7
  55.  
  56.                 3. PROGRAMMING MENUS . . . . . . . . . . . . . . . . . . . 11
  57.                      Using the Shell . . . . . . . . . . . . . . . . . . . 11
  58.                      Menu Modes  . . . . . . . . . . . . . . . . . . . . . 11
  59.                      Line Modes  . . . . . . . . . . . . . . . . . . . . . 14
  60.                      HiLite Control  . . . . . . . . . . . . . . . . . . . 15
  61.                      Adding Lines  . . . . . . . . . . . . . . . . . . . . 16
  62.                      Adding Menus  . . . . . . . . . . . . . . . . . . . . 17
  63.                      Adding Submenus . . . . . . . . . . . . . . . . . . . 18
  64.                      Help Messages . . . . . . . . . . . . . . . . . . . . 20
  65.                      Help Windows  . . . . . . . . . . . . . . . . . . . . 21
  66.                      Default Attributes  . . . . . . . . . . . . . . . . . 23
  67.                      Standard Borders  . . . . . . . . . . . . . . . . . . 24
  68.                      Control Flags . . . . . . . . . . . . . . . . . . . . 24
  69.                      Summary . . . . . . . . . . . . . . . . . . . . . . . 26
  70.  
  71.                 4. SCREEN DESIGN . . . . . . . . . . . . . . . . . . . . . 27
  72.                      Status Line . . . . . . . . . . . . . . . . . . . . . 27
  73.                      Top Line Menu . . . . . . . . . . . . . . . . . . . . 27
  74.                      Main Menu Row . . . . . . . . . . . . . . . . . . . . 27
  75.                      Submenu Row . . . . . . . . . . . . . . . . . . . . . 28
  76.                      Work Windows  . . . . . . . . . . . . . . . . . . . . 28
  77.                      Message Line  . . . . . . . . . . . . . . . . . . . . 28
  78.                      Help Windows  . . . . . . . . . . . . . . . . . . . . 29
  79.                      Start-Up Menu . . . . . . . . . . . . . . . . . . . . 29
  80.                      Overriding Defaults . . . . . . . . . . . . . . . . . 30
  81.                      Summary . . . . . . . . . . . . . . . . . . . . . . . 30
  82.  
  83.                 5. DATA WINDOWS  . . . . . . . . . . . . . . . . . . . . . 32
  84.                      Data Window Parts . . . . . . . . . . . . . . . . . . 32
  85.                      Data Window Record  . . . . . . . . . . . . . . . . . 32
  86.                      Data Window Variable  . . . . . . . . . . . . . . . . 33
  87.                      Fields  . . . . . . . . . . . . . . . . . . . . . . . 34
  88.                      Titles  . . . . . . . . . . . . . . . . . . . . . . . 35
  89.                      Editing Keys  . . . . . . . . . . . . . . . . . . . . 36
  90.                      Key Sets  . . . . . . . . . . . . . . . . . . . . . . 36
  91.                      Key Translation . . . . . . . . . . . . . . . . . . . 37
  92.                      Range Checking  . . . . . . . . . . . . . . . . . . . 38
  93.                      Help Messages . . . . . . . . . . . . . . . . . . . . 40
  94.                      Help Windows  . . . . . . . . . . . . . . . . . . . . 40
  95.                      Default Attributes and Border . . . . . . . . . . . . 40
  96.                      Default Location  . . . . . . . . . . . . . . . . . . 41
  97.  
  98.  
  99.                                                2
  100.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  101.  
  102.  
  103.                      Summary . . . . . . . . . . . . . . . . . . . . . . . 41
  104.  
  105.                 6. DATA ENTRY  . . . . . . . . . . . . . . . . . . . . . . 42
  106.                      Data Entry vs. Data Windows . . . . . . . . . . . . . 42
  107.                      Data Entry Record . . . . . . . . . . . . . . . . . . 42
  108.                      Adding Entries  . . . . . . . . . . . . . . . . . . . 43
  109.                      Displaying Fields . . . . . . . . . . . . . . . . . . 43
  110.                      Sequential Entry  . . . . . . . . . . . . . . . . . . 44
  111.                      Edit Mode . . . . . . . . . . . . . . . . . . . . . . 46
  112.                      Field Attributes  . . . . . . . . . . . . . . . . . . 47
  113.                      Single Entry  . . . . . . . . . . . . . . . . . . . . 47
  114.                      Summary . . . . . . . . . . . . . . . . . . . . . . . 47
  115.  
  116.                 7. WORK WINDOWS  . . . . . . . . . . . . . . . . . . . . . 48
  117.                      Making Steps  . . . . . . . . . . . . . . . . . . . . 48
  118.                      Reading the Keyboard  . . . . . . . . . . . . . . . . 49
  119.                      Multi-Level Windows . . . . . . . . . . . . . . . . . 51
  120.                      Managing Winddows . . . . . . . . . . . . . . . . . . 52
  121.  
  122.                 8. USER WINDOWS  . . . . . . . . . . . . . . . . . . . . . 54
  123.                      Pull-Down Directory . . . . . . . . . . . . . . . . . 54
  124.                      Interface . . . . . . . . . . . . . . . . . . . . . . 55
  125.  
  126.                 9. CONDITIONAL COMPILATION . . . . . . . . . . . . . . . . 57
  127.                      Define Symbols  . . . . . . . . . . . . . . . . . . . 57
  128.                      Recompiling . . . . . . . . . . . . . . . . . . . . . 57
  129.  
  130.                10. TROUBLE SHOOTING  . . . . . . . . . . . . . . . . . . . 58
  131.                      Goof Unit . . . . . . . . . . . . . . . . . . . . . . 58
  132.                      Far Addresses . . . . . . . . . . . . . . . . . . . . 58
  133.                      Multi-tasking . . . . . . . . . . . . . . . . . . . . 59
  134.                      Customer Service  . . . . . . . . . . . . . . . . . . 59
  135.  
  136.                 APPENDIX A: Other Products . . . . . . . . . . . . . . . . 60
  137.  
  138.                 APPENDIX B: Revision History . . . . . . . . . . . . . . . 62
  139.  
  140.                 APPENDIX C: Credits  . . . . . . . . . . . . . . . . . . . 63
  141.  
  142.                 APPENDIX D: Glossary . . . . . . . . . . . . . . . . . . . 64
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.                                                3
  161.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  162.  
  163.  
  164.            1.  I N T R O D U C T I O N
  165.  
  166.  
  167.            FEATURES
  168.  
  169.            Welcome to PULL multi-level pull-down menus!
  170.  
  171.            You have just obtained a copy of the highest performance pull-down menu
  172.            utilities available today for Turbo Pascal 5.5 (TP5).  Both novice and
  173.            professional programmers will appreciate these simple and very powerful
  174.            utilities that are fully featured and fully configurable.  They work on any
  175.            all IBM compatibles, including PS/2 and 3270 PC on any video page or any
  176.            text mode.
  177.  
  178.            Here are some of the features you will discover:
  179.  
  180.              - Uses the powerful routines of QWIK and WNDW.
  181.              - Work window(s) and complete interface for menus
  182.              - Pull-down menus with 3 menu modes and 8 line modes
  183.              - Pull-down file directory
  184.              - Highlighted command letters
  185.              - Unlimited levels of submenus
  186.              - Unlimited data entry windows for 9 types of data
  187.              - Data entry for the work window(s)
  188.                  Free field entry with either fixed column or flexible
  189.                  column length.
  190.                  Full editing capability including insert cursor mode
  191.                  Fields are easily selected with the cursor keys
  192.                  Automatic NumLock for numerical data entry
  193.                  Right or left justification for data entry output
  194.                  Error messages for invalid data entries
  195.                  Error messages for data entries out of range
  196.              - Automatic sizes and locations for menus
  197.              - Operation by cursor keys or command keys
  198.              - Pull/Pop between work window and nested submenu(s)
  199.              - Programmable control of pull and pop sequences
  200.              - Context-sensitive help windows
  201.              - Message lines for prompts and processing
  202.              - Writes direct to multi-tasking video buffers (MTVB).
  203.              - Full working shell for user development
  204.  
  205.            PULL has been designed with a fill-in-the-blank concept.  To get your
  206.            application up and running, you only need to fill in the appropriate
  207.            records or variables.
  208.  
  209.            TP4 - The units provided in this distributed file only work under TP5.
  210.            However, the source code, provided with registration, compiles equally well
  211.            under TP4.
  212.  
  213.  
  214.            USING THE MANUALS
  215.  
  216.            Disk Based Guides - The manuals for PULL are on disk so that you can
  217.            conveniently scan for the topic you are seeking.  You can do this with any
  218.            list or search utility with a search function.  You can also make a printed
  219.  
  220.  
  221.            Chapter 1, Introduction                                             Page 4
  222.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  223.  
  224.  
  225.            copy.  If you have not already printed this manual, refer to the READ.ME
  226.            file for instructions.  At the present time, no bound manuals are being
  227.            offered with registration.
  228.  
  229.            User's Guide - This manual, the one your are reading now, assumes that as a
  230.            programmer you are already familiar with Turbo Pascal 5.5, and that you
  231.            have a working knowledge of your disk operating system (DOS).  It also
  232.            assumes that you are familiar with QWIK screen utilities in QWIK55.ARC and
  233.            WNDW55.ARC.  This manual will provide the basic instructions for creating
  234.            and managing multi-level pull-down menus.  It also contains a tutorial to
  235.            guide you step-by-step to create your own application.
  236.  
  237.            Reference Guide - This manual describes in detail all procedures, functions
  238.            and variables used in PULL.  It is a alphabetically arranged for easy
  239.            access in a format similar to the TP5 manual.  Use this manual when you
  240.            have become familiar with the basic principles in the User's guide.
  241.  
  242.  
  243.            LICENSING
  244.  
  245.            Registration - These routines and the documentation have been released for
  246.            distribution as Shareware.  You have been given the chance to sample the
  247.            full capability of PULL without risk!  If you find that PULL is a valuable
  248.            tool, then you are expected to register.  You will find a reasonable
  249.            licensing schedule found in LICENSE.ARC to meet private or commercial
  250.            needs.  When registering, be sure to specify the version for Turbo Pascal
  251.            (such as TP4 or TP5) you wish to receive.
  252.  
  253.            Source Code - All registered users will receive source code when the signed
  254.            license agreement is returned with the registration.  All source code
  255.            compiles under TP4 as well as TP5.  The compiled units in the distributed
  256.            file were compiled with TP5 and only work in TP5.
  257.  
  258.  
  259.            CUSTOMER SERVICE
  260.  
  261.            If you have questions, comments, or suggestions, the Eagle can be contacted
  262.            by four means - (1) CompuServe, (2) telephone, (3) The Eagle BBS, or
  263.            (4) mail.
  264.  
  265.            CompuServe - The most dependable way to contact the Eagle is through
  266.            CompuServe.  James (Jim) H. LeMay has written the TP5 version of QWIK, but
  267.            the person to contact is Jordan Gallagher who can be reached on the Borland
  268.            Forum by typing GO BPROGA from the CompuServe main menu.  You will enter
  269.            the Forum for Turbo Pascal.  You can contact Jordan with his PPN number of
  270.            73557,2342.  Messages can also be left through EasyPlex.
  271.  
  272.            Telephone - Jordan can also be reached by phone at (214) 539-7855 on
  273.            weekdays and Saturday from 9:00 a.m. to 8:00 p.m CST.
  274.  
  275.            The Eagle BBS - You can also contact us on our 24-hour BBS at (214) 539-
  276.            9878, 1200/2400 N81.
  277.  
  278.            Mail - For registration or problems, please write:
  279.  
  280.  
  281.  
  282.            Chapter 1, Introduction                                             Page 5
  283.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  284.  
  285.  
  286.                Eagle Performance Software
  287.                P.O. Box 292786
  288.                Lewisville, TX  75029-2786
  289.  
  290.            In your written request for resolving problems, be sure to include:
  291.  
  292.              . A 5 1/4 inch diskette of compilable source code of the problem.
  293.              . The Eagle product and version number.
  294.              . The computer make and model.
  295.              . The type of video card, video monitor and keyboard.
  296.  
  297.  
  298.            ASP
  299.  
  300.            PULL is a Shareware program conforming to the standards of the Association
  301.            of Shareware Professionals (ASP).  You can get more information about ASP
  302.            by writing to:
  303.  
  304.              Association of Shareware Professionals
  305.              P.O. Box 5786
  306.              Bellevue,WA 98006
  307.  
  308.            This program is produced by a member of the Association of Shareware
  309.            Professionals (ASP).  ASP wants to make sure that the shareware principle
  310.            works for you.  If you are unable to resolve a shareware-related problem
  311.            with an ASP member by contacting the member directly, ASP may be able to
  312.            help.  The ASP Ombudsman can help you resolve a dispute or problem with an
  313.            ASP member, but does not provide technical support for member's products.
  314.            Please write to:
  315.  
  316.              ASP Ombudsman
  317.              P.O. Box 5786
  318.              Bellevue,WA 98006
  319.  
  320.            or send a CompuServe message via EasyPlex to ASP Ombudsman 7007,3536.
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.            Chapter 1, Introduction                                             Page 6
  344.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  345.  
  346.  
  347.            2.  G E T T I N G   S T A R T E D
  348.  
  349.            This section will acquaint you with the files on distribution disk and show
  350.            you a couple of demonstrations to quickly see what PULL can accomplish.
  351.  
  352.  
  353.            DISTRIBUTION FILES
  354.  
  355.            In this version, PULL55.ARC contains:
  356.  
  357.              Read.   .me:   Note of printing instructions for manual.
  358.              Pull55  .doc:  This document - a user's guide to PULL.
  359.              PullRef .doc:  PULL Reference Guide document covering each
  360.                             routine and variable in detail.
  361.              Pull55  .tpu:  This unit has the full power of all of its
  362.                             capabilities.  Please note that because PULL55.TPU
  363.                             uses P55-VAR.INC all constants have been assigned.
  364.                             In order to make any changes in the data
  365.                             requirements, the complete source code will be
  366.                             required.
  367.              Pull55- .pas:  Shows the interface portion of PULL55.
  368.              P55-var .inc:  This file is the actual source code which lists
  369.                             all of the types, constants, and variables used
  370.                             for PULL55.TPU.
  371.              PullDemo.pas:  Fully functional working demo.
  372.              PullWork.pas:  Procedures for the main work window(s).
  373.              PullStat.pas:  Stats to configure the menus including global
  374.                             keys.
  375.              PullData.pas:  Data to configure data entry windows and fields.
  376.              PullDir-.pas:  Just interface for PULLDIR.PAS.
  377.              PullDir .tpu:  Unit for a pull-down file directory.
  378.              PullShel.arc:  Contains shell files to develop your own
  379.                             application.
  380.              Qwik55  .tpu:  Unit for quick screen writing.
  381.              Strs    .tpu:  Unit from QWIK55 for number-to-string conversions.
  382.              WndwP55 .tpu:  Multi-level virtual window unit for PULL.TPU.
  383.              Wutil   .tpu:  Independent utilities unit used in WNDW.TPU.
  384.              Goof    .pas:  Unit to display errors.
  385.              License .arc:  ARC file containing license agreement and ordering
  386.                             details.
  387.  
  388.  
  389.            DEMONSTRATION
  390.  
  391.            To get the feeling of the speed and features of PULL, let's run the
  392.            demonstration program that comes with the utilities.  Do the following
  393.            steps:
  394.  
  395.              1. Copy QWIK55.TPU to QWIK.TPU.
  396.              2. Copy WNDWp55.TPU (not WNDW55.TPU) to WNDW.TPU.  !!!
  397.              3. Copy PULL55.TPU to PULL.TPU.
  398.              4. Make, compile and run PULLDEMO.PAS.  (If you get an ERROR
  399.                 15 or 70, then steps 1-3 were not done carefully.)
  400.              5. Follow along in the overview below.
  401.  
  402.  
  403.  
  404.            Chapter 2, Getting Started                                          Page 7
  405.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  406.  
  407.  
  408.            Familiar Environment - You will probably feel right at home with the
  409.            environment created with PULL as it appears very similar to the TP5 editor.
  410.            It is interesting to note that PULL was developed with TP3 before TP4 was
  411.            ever released.  However, you should find the operation quite similar.
  412.            While you are running the demo, let's get familiar with the format and
  413.            operation of the environment and follow along with this overview:
  414.  
  415.              . Status Line - Row 1 just holds the title of this program.  It is
  416.                optional.
  417.  
  418.              . Top Line Menu - Row2 has been optionally assigned to be the top
  419.                line menu.  Press F10 at any time to access it.
  420.  
  421.              . Work Window - For this demo, Rows 4 to 23 has a 20x78 window for
  422.                the major part of your input/output.  You can also have multi-
  423.                level work windows.
  424.  
  425.              . Main Menu - To access a main menu, press RETURN or a command
  426.                letter (LTR) while the top line menu is highlighted on any
  427.                selection.  Or, you can use a combination of the ALT key and a
  428.                letter, such as Alt-F to get to the File menu.
  429.  
  430.              . Submenu - A submenu is a menu under a Main Menu.  To access a
  431.                submenu, press RETURN when the HiLite is at a menu line with the
  432.                three-bar symbol (which looks like a menu).  You can see three
  433.                levels of menus by pressing Alt-A/Tires/Brands.
  434.  
  435.            Local Keys and Letter Commands - While a window is shown, several keys
  436.            operate for just that window.  These keys can be listed in the message line
  437.            or they can be assumed to be the command letters highlighted on each menu
  438.            line.
  439.  
  440.              . Help Windows (F1) - While the Brands menu is still showing,
  441.                press F1 to get context-sensitive help.  A help window is
  442.                assigned to every window and menu.
  443.  
  444.              . Keys on Message Line - The bottom line of the CRT, being closest
  445.                to the keyboard, indicates the available keys that can be used
  446.                for the current context.  It is also used for help or error
  447.                messages.  While the help window is displayed, the next key
  448.                pressed will also pass through as a command.  For instance, press
  449.                RETURN now and see the help window removed and Firestone will
  450.                also become flagged.
  451.  
  452.              . Pop and Pull (F2) - F2 is a pop-and-pull key that toggles between
  453.                the pull-down menus and the work window.  Press F2 twice and you
  454.                will see that it remembers the last menu that was pulled.
  455.  
  456.              . Command Letters (LTR) - If you wanted to select WeatherGuard on
  457.                the Brands menu, just type the letter "W" which is highlighted.
  458.                These letters will work in any menu.
  459.  
  460.              . Cursor Keys - All of the cursor keys like the arrows, Home and
  461.                End keys, have assigned functions as well as the control-shifted
  462.                cursor keys.  You can discover what they do by experimenting with
  463.  
  464.  
  465.            Chapter 2, Getting Started                                          Page 8
  466.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  467.  
  468.  
  469.                them in a menu.
  470.  
  471.              . ESC Key - The ESC key always backs out of the current menu/window.
  472.  
  473.            Global Keys - Extended key combinations can be used to access any part of
  474.            the program.  In this demo, some have been assigned with the ALT key.
  475.            Press down ALT for a half second and see the available global keys listed
  476.            on the message line.
  477.  
  478.              . Directory (Alt-D) - Press Alt-D now to get a directory of your
  479.                disk.  If you would like to continue testing the directory, press
  480.                F1 for instructions.
  481.  
  482.              . Exit (Alt-X) -  To exit the program, one alternative is to use
  483.                Alt-X, but don't do it now.
  484.  
  485.              . Top Line Menu (F10) - As mentioned before, to get to the top line
  486.                menu, press F10 at any time.
  487.  
  488.            Data Entry Windows - Each menu can additionally pull down a data entry
  489.            window which is indicated with a small dot symbol on the menu line.  These
  490.            windows are fully configurable and have full editing capability.  They have
  491.            a free-field entry concept where a entire string is typed and edited before
  492.            entering.  Let's try a few fields.
  493.  
  494.              . Data Entry Types - Press Alt-E to see a menu of all the data
  495.                entry types available.  Press RETURN when the HiLite is at a menu
  496.                line with a small dot symbol.  Pressing RETURN again will exit
  497.                the window entering the data shown.  You can clear any data
  498.                entered by pressing ESC which also removes the window.
  499.  
  500.              . Editing - Press "I" while the main menu is still shown and enter
  501.                a value for the integer.  The virgin entry is highlighted until
  502.                you press a key.  The entry has full edit capability using the
  503.                cursor keys and some familiar WordStar control keys.  Press F1
  504.                for a list.  Even the insert mode is indicated with a half-block
  505.                cursor.
  506.  
  507.              . Options - All sorts of options are available for these windows
  508.                including range checking, fixed and flex fields, character
  509.                control and translation, automatic NumLock, justification,
  510.                titles, and attributes.
  511.  
  512.            Work Window Data Entry - The same procedures used for the data entry
  513.            windows can be used for entering data in the work windows.  In addition,
  514.            PULL has a smart algorithm that knows where several fields are on the
  515.            screen.  So moving from field to field with all the cursor keys is
  516.            intuitive.
  517.  
  518.              . Moving the HiLite - Press F2 to get back to the work window with
  519.                all of the data entry fields.  One field will be highlighted
  520.                which means it can be moved to select another field.  All of the
  521.                cursor keys move the HiLite including the control-shifted keys
  522.                and the Tab and Shift-Tab keys.  Move the HiLite to the Integer
  523.                field.
  524.  
  525.  
  526.            Chapter 2, Getting Started                                          Page 9
  527.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  528.  
  529.  
  530.  
  531.              . New Values - To enter a new value for the integer, simply start
  532.                typing some numbers and the HiLite will change colors.  You can
  533.                see that only numbers and the sign can be entered.  Press RETURN
  534.                to enter the new value or press ESC to restore the old value.
  535.  
  536.              . Editing - To edit the value currently shown in a field, press
  537.                RETURN or any WordStar control key.
  538.  
  539.            Other Features - There are many other features in the menus which will be
  540.            covered later including menu and line modes, and direct menu control.  You
  541.            may continue to discover other features in the demo if you want.  When
  542.            finished, press Alt-X to quit.
  543.  
  544.            Multi-tasking - This demo is already set to work in multi-tasking
  545.            environments compatible to DESQview, TaskView, and IBM 3270 PC.
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.            Chapter 2, Getting Started                                          Page 10
  588.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  589.  
  590.  
  591.            3.  P R O G R A M M I N G   M E N U S
  592.  
  593.            This section will get you familiar with the basics of window programming
  594.            by starting with very basic menus and then taking you step-by-step through
  595.            the full variety of options and modes available.
  596.  
  597.  
  598.            USING THE SHELL
  599.  
  600.            Shell Program - Let's experiment will PULL by developing our own
  601.            application to see how powerful it can be.  A shell program, which is a
  602.            bare bones application, has been provided with PULL in the file
  603.            PULLSHEL.ARC.  These files will help you get started for any application.
  604.            But for now, it can be an excellent learning tool.  To keep these files
  605.            separate from the PULLDEMO files, create another working directory and
  606.            unarchive the files in PULLSHEL.ARC.  The files to be extracted are:
  607.  
  608.              PullShel.pas
  609.              PullData.pas
  610.              PullStat.pas
  611.              PullWork.pas
  612.  
  613.            In addition, the follow files need to be on you unit path or copied into
  614.            the same directory:
  615.  
  616.              Qwik.tpu
  617.              Wndw.tpu
  618.              Wutil.tpu
  619.              Strs.tpu
  620.              Pull.tpu
  621.              Goof.pas
  622.  
  623.            Running the Shell - To make sure we have everything available, load
  624.            PULLSHEL.PAS, make, and run the program.  You should be able to operate
  625.            this program the same as PULLDEMO.PAS.  There are only two menus - First
  626.            and Quit.  To Quit, you can either use the Quit menu or use the global key
  627.            Alt-X.
  628.  
  629.            Features Available - The shell has every feature available.  They can be
  630.            added or eliminated.  However, some code cannot be entirely eliminated or
  631.            altered unless you are registered with the source code.  But let's continue
  632.            to see what the program can really do.
  633.  
  634.  
  635.            MENU MODES
  636.  
  637.            In this section, we will delve right into the menus and see how they
  638.            function and what changes can be made.  PULL has three menu modes for every
  639.            menu - ExecChoice, SingleChoice, and MultipleChoice.  These modes determine
  640.            how all the lines in the menu can interact as a whole.
  641.  
  642.            SingleChoice - You probably noticed that the First menu had one flag on it
  643.            because it was a SingleChoice menu.  One and only one item could be flagged
  644.            by pressing return on any one line.  Let's examine the data record of menu
  645.            and see how it was made to be single choice.
  646.  
  647.  
  648.            Chapter 3, Programming Menus                                        Page 11
  649.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  650.  
  651.  
  652.  
  653.              1. Load the file PULLSTAT.PAS into the TP editor.
  654.              2. Set PULLSHEL.PAS to be the Primary file.
  655.              3. Search for "with TopMenu".
  656.              4. See the following code:
  657.  
  658.                  GetMainMenu (FirstMenu);
  659.                  MenuMode := SingleChoice;
  660.                  SingleFlagLine := 3;
  661.                  Title   := 'First';
  662.                  Line[1] := 'A line';
  663.                  Line[2] := 'B line';
  664.                  Line[3] := 'C line';
  665.                  Line[4] := 'D line';
  666.                  DefaultLine := 2;
  667.                  MsgLineNum  := ord(MainML);
  668.                  HelpWndwNum := ord(MainMenuHW);
  669.                  SaveMainMenu;
  670.  
  671.            TopMenu - All these variables are fields in the current menu record called
  672.            TopMenu.  Notice that MenuMode is set to SingleChoice.  And that's how it
  673.            is done!  That's all it takes to tell PULL that all items on the menu are
  674.            single choice.  The program simply takes care of any selection.  So how do
  675.            you know which line has been selected?  Just get the value of
  676.            TopMenu.SingleFlagLine.  But also notice that SingleFlagLine has been
  677.            initially assigned to line 3.  Now you know why the "C line" is flagged
  678.            when the program first starts.  Setting SingleFlagLine is only needed for
  679.            the SingleChoice mode.  So how do you make it multiple choice?
  680.  
  681.            MultipleChoice - Let's change MenuMode to MultipleChoice and run the
  682.            program again.  Do it now.  This time you won't see any flags initially,
  683.            but each line can be toggled on and off by selecting any line with RETURN.
  684.            Ok, how do we know which line has been flagged now?  There are several more
  685.            variables in the menu record other than shown here.  Each Line has an
  686.            associated boolean variable called Flagged.  For example, if you want to
  687.            see if Line[3] has been flagged, just test and see if Flagged[3] is true.
  688.            But suppose we want some of those lines to be initially flagged?
  689.  
  690.            Flags - All the code we have seen is within a procedure called
  691.            GetUserPullStats which initializes all the menus from InitPull.  The
  692.            procedure GetMainMenu simply grabs a copy of the current menu record from
  693.            the heap which happens to be cleared with all zeros at this time.  That
  694.            means everything is a default value of zero unless we change it.  So, the
  695.            value of Flagged for each line is false.  Let's see if we can set a couple
  696.            of lines to be initially true by modifying the code to:
  697.  
  698.              ...
  699.              MenuMode := MultipleChoice;
  700.              SingleFlagLine := 3;
  701.              Title   := 'First';
  702.              Line[1] := 'A line';  Flagged[1] := true;
  703.              Line[2] := 'B line';  Flagged[2] := true;
  704.              ...
  705.  
  706.            Run the code again and verify that the first two lines are initially
  707.  
  708.  
  709.            Chapter 3, Programming Menus                                        Page 12
  710.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  711.  
  712.  
  713.            flagged.  If they are, then you are already getting the hang of how to
  714.            program pull-down menus!  PULL is based on a fill-in-the-blank concept
  715.            where you supply the data and the program takes care of the rest.
  716.  
  717.            Changed Flags - If there are several flags in the menu and just one is
  718.            changed, how can you know?  Anytime a flag is altered in the menu, the
  719.            variable "Changed" in the menu record is set to true which gives a quick
  720.            survey for any action that may be needed.  This value remains true until
  721.            your application program manually sets it false.
  722.  
  723.            Executing Procedures - But having a simple flag may not be enough for your
  724.            application.  Suppose you may also want to DO something as well.  So how
  725.            can we execute a procedure along with the selection?  Again, each line has
  726.            an associated execution pointer ProcPtr.  Simply assign any valid procedure
  727.            address to it and it executes it!  Try the following code:
  728.  
  729.              ...
  730.              MenuMode := MultipleChoice;
  731.              SingleFlagLine := 3;
  732.              Title   := 'First';
  733.              Line[1] := 'A line';  Flagged[1] := true;  ProcPtr[1] := @DummyProc;
  734.              Line[2] := 'B line';  Flagged[2] := true;  ProcPtr[2] := @DummyProc;
  735.              ...
  736.  
  737.            Run this code and you will find that every time line 1 or 2 is toggled, the
  738.            message "Processing ..." is displayed briefly on the message line which is
  739.            all this dummy procedure was supposed to do.  After it is processed, the
  740.            line is then flagged.  The procedure DummyProc is actually back a few lines
  741.            in the code just before GetUserPullStats.  This makes it very convenient to
  742.            have these procedures in the same file, but they don't have to be.  Since
  743.            the pointer is FAR, these procedures, which have been forced to FAR, can be
  744.            called from other units as well.
  745.  
  746.            Nil Pointer - So how come procedures were not executed before the pointers
  747.            were assigned?  Again, all values are zero until changed.  So, the pointer
  748.            was Nil.  The program simply ignores nil pointers and therefore does not
  749.            execute anything.
  750.  
  751.            ExecChoice - This mode only executes procedures with ProcPtr and just
  752.            ignores all flagging.  This is also the default mode.  Let's try this by
  753.            adding the following braces:
  754.  
  755.              ...
  756.            { MenuMode := MultipleChoice;
  757.              SingleFlagLine := 3; }
  758.              Title   := 'First';
  759.              Line[1] := 'A line';  Flagged[1] := true;  ProcPtr[1] := @DummyProc;
  760.              Line[2] := 'B line';  Flagged[2] := true;  ProcPtr[2] := @DummyProc;
  761.              ...
  762.  
  763.            Run it again.  You found that both line 1 and 2 executed the dummy
  764.            process, but the flags weren't toggled.  ExecChoice just ignores flagging.
  765.            Flags are usually not useful with ExecChoice mode and they can remain
  766.            false.  Lines 3 and 4 did absolutely nothing since the pointers were nil.
  767.  
  768.  
  769.  
  770.            Chapter 3, Programming Menus                                        Page 13
  771.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  772.  
  773.  
  774.            Default Mode - How come MenuMode was not assigned to ExecChoice and instead
  775.            was commented out with braces?  We could have if we wanted, but ExecChoice
  776.            is the default mode with an ordinal value of zero.  So, it saves code to
  777.            leave it out.
  778.  
  779.  
  780.            LINE MODES
  781.  
  782.            In this section, we will discover how each line in the menu can have one of
  783.            several different modes and then test each one to see its effect.
  784.  
  785.            Seven Line Modes - Not only does the whole menu have a mode, but each line
  786.            can have one of eight different modes:
  787.  
  788.              Choice     - permits flagging with Single- or MultipleChoice and
  789.                           executes the ProcPtr.
  790.              ExecOnly   - executes the ProcPtr without flagging.
  791.              NoChoice   - disabled by the your program.
  792.              Comment    - bypassed by the highlight.
  793.              Partition  - mid-menu horizontal border.
  794.              ToDataWndw - to pull a data entry window.
  795.              ToSubMenu  - to pull next submenu level.
  796.              ToUserWndw - like ExecOnly, and adds a Submenu symbol.
  797.  
  798.            These names are the actual identifiers used in LineModeType.  Each line has
  799.            an associated line mode saved in the variable LineMode.  For example, to
  800.            see what mode is on line 3, just check the value of LineMode[3].
  801.  
  802.            Choice - This is the default and, as you would guess, its ordinal value is
  803.            zero, so we never have to set it.  With this line mode and a menu mode of
  804.            SingleChoice or MultipleChoice, the line can be flagged like we have seen
  805.            in the previous examples.  But it is rare that any menu would have only
  806.            flags.  So, what other alternatives are there?
  807.  
  808.            ExecOnly - Let's suppose that just one of the lines on our First menu
  809.            should never be flagged, but all the others can.  How can we isolate it?
  810.            Back to the current example, revise the menu to be MultipleChoice with the
  811.            following changes:
  812.  
  813.              ...
  814.              MenuMode := MultipleChoice;
  815.            { SingleFlagLine := 3; }
  816.              Title   := 'First';
  817.              Line[1] := 'A line';  Flagged[1] := true;       ProcPtr[1] := @DummyProc;
  818.              Line[2] := 'B line';  LineMode[2] := ExecOnly;  ProcPtr[2] := @DummyProc;
  819.              ...
  820.  
  821.            Run it again and see that we can't toggle the flag on line 2 since it was
  822.            assigned as ExecOnly.  All it does is execute DummyProc even though the
  823.            menu mode is MultipleChoice.
  824.  
  825.            Comment - Suppose we wanted a title or some type of comment or help message
  826.            inside the menu itself.  That line should not be considered as a valid
  827.            choice.  In fact, the line should never be highlighted.  Try changing line
  828.            3 to the following:
  829.  
  830.  
  831.            Chapter 3, Programming Menus                                        Page 14
  832.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  833.  
  834.  
  835.  
  836.              ...
  837.              Line[2] := 'B line';  LineMode[2] := ExecOnly;  ProcPtr[2] := @DummyProc;
  838.              Line[3] := 'My comment'; LineMode[3] := Comment;
  839.              ...
  840.  
  841.            Run it and move the HiLite up and down.  You can see that the HiLite passes
  842.            right over line 3 and never accesses it.  By the way, notice also that the
  843.            first letter of "My comment" was not highlighted as a command letter.  In
  844.            fact, the entire line is a different attribute.  Also notice that the menu
  845.            has automatically increased in width to accommodate the new longest line.
  846.  
  847.            Partition - Sometimes it is easier to understand a menu when it is divided
  848.            into separate sections.  This can be done with the line mode of Partition.
  849.            Change LineMode[3] as follows:
  850.  
  851.              ...
  852.              Line[2] := 'B line';  LineMode[2] := ExecOnly;  ProcPtr[2] := @DummyProc;
  853.            { Line[3] := 'My comment'; }  LineMode[3] := Partition;
  854.              ...
  855.  
  856.            When you pull down the menu, you will see that line 3 has become an
  857.            extension of the border with the same style and attribute.  Moving the
  858.            highlight up and down will also show that the partition is passed over just
  859.            like a Comment.  Since Line[3] was unecessary and was commented out with
  860.            braces.
  861.  
  862.            NoChoice - Suppose you want a line to be temporarily unavailable because it
  863.            didn't apply at a given stage in your program.  You can overwrite the menu
  864.            record with a line mode of NoChoice which has the same effect as a Comment,
  865.            except you can enable it again by changing the line mode back to what it
  866.            was.  The command letter will again become available for that line.  In
  867.            contrast, Partition and Comment never have a command letter.
  868.  
  869.            Other Line Modes - There are three remaining modes, ToDataWndw, ToSubMenu,
  870.            and ToUserWndw, which will pull down another level of a menu or a window.
  871.            These can also be assigned to LineMode which will be covered in more detail
  872.            later.
  873.  
  874.  
  875.            HILITE CONTROL
  876.  
  877.            Highlight Line - The menu highlight bar is tracked by a variable called
  878.            HiLiteLine which is also in TopMenu.  Any time the highlight (also called
  879.            HiLite) is moved, this value is updated to the current line number and
  880.            saved.  So, upon re-entering the menu, the HiLite will still be on the same
  881.            line before as before.
  882.  
  883.            Default Line - The HiLite has to start somewhere.  In our current example,
  884.            the variable DefaultLine controls the initial line for the HiLite.  When
  885.            you run it, you can see that the first time the menu is pulled, line 2 is
  886.            highlighted.  Now move the HiLite down to line 4.  If you exit and re-enter
  887.            the menu, the HiLite is still on line 4.  So, we know that it always
  888.            remembers the current line.  But what is the default for DefaultLine?
  889.            Let's find out.  Comment out the following line:
  890.  
  891.  
  892.            Chapter 3, Programming Menus                                        Page 15
  893.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  894.  
  895.  
  896.  
  897.              ...
  898.              Line[4] := 'D line';
  899.            { DefaultLine := 2; }
  900.              MsgLineNum  := ord(MainML);
  901.              ...
  902.  
  903.            Run the program and you will find that the HiLite starts on line 1 and not
  904.            zero.  InitPull takes a second look at all menu records and makes sure that
  905.            all DefaultLines have been set.  If not, it sets DefaultLine to line 1.
  906.            But suppose we want the HiLite to start on the same line every time the
  907.            menu is pulled?
  908.  
  909.            Back To Default Line - You can force the HiLite to same initial line by
  910.            setting BackToDefault to true.  Let's try it on our current example:
  911.  
  912.              ...
  913.              Line[4] := 'D line';
  914.              DefaultLine := 2;
  915.              BackToDefault := true;
  916.              MsgLineNum  := ord(MainML);
  917.              ...
  918.  
  919.            When you pull-down the menu this time, the default line is 2.  But move the
  920.            HiLite to line 4 and exit the menu.  When the menu is pulled again, the
  921.            HiLite goes back to line 2.  Looking at the code, the Quit menu record is a
  922.            few lines down from the First menu.  There you can see that BackToDefault
  923.            is set to true for that menu as well which would keep a user from
  924.            inadvertently exiting the program.
  925.  
  926.  
  927.            ADDING LINES
  928.  
  929.            Adding Lines - To add more lines to a menu is a snap - just add a line.
  930.            Try the following modification on the First menu.
  931.  
  932.              ...
  933.              Line[4] := 'D line';
  934.              Line[5] := 'E line';   { add this line }
  935.              DefaultLine := 2;
  936.              ...
  937.  
  938.            The program automatically knows how many lines are in the menu so that it
  939.            is sized correctly and the HiLite knows how far to extend.  How many lines
  940.            can be added?
  941.  
  942.            Maximum Lines - To control the size of the menu record, the maximum number
  943.            of lines per menu is set by MaxMenuLines.  Go to a file called P55-VAR.INC
  944.            and you will find it to be the very first constant in the file and it has
  945.            been arbitrarily set to 15 lines.  This is one of several configuration
  946.            constants preset in PULL.  To be able to change these values, you must have
  947.            the source code to PULL which includes the file P55-VAR.INC.
  948.  
  949.            Maximum Characters - Each menu line is also limited to a maximum length.
  950.            You can discover this by testing this code:
  951.  
  952.  
  953.            Chapter 3, Programming Menus                                        Page 16
  954.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  955.  
  956.  
  957.  
  958.              ...
  959.              Line[4] := 'D line';
  960.              Line[5] := 'E line is longer than 20 characters';
  961.              DefaultLine := 2;
  962.              ...
  963.  
  964.            The menu is only wide enough to accommodate 20 characters which is also
  965.            preset with the constant MaxCharsPerLine.
  966.  
  967.  
  968.            ADDING MENUS
  969.  
  970.            Now that you are familiar with the scope of a single menu, you can take the
  971.            next step and learn how to include additional menus.
  972.  
  973.  
  974.            Main Menu Name - The first thing needed is a name for a new main menu.  On
  975.            the first page of PULLSTAT.PAS, find an enumerated type called
  976.            MainMenuNames and insert a new name called SecondMenu:
  977.  
  978.              MainMenuNames = (NoMainMenu,FirstMenu,SecondMenu,QuitMenu);
  979.  
  980.            It is important that these names are in order so that InitPull will
  981.            arrange them correctly.
  982.  
  983.            Main Menu Record - Now the record of SecondMenu can be added.  Between the
  984.            FirstMenu and QuitMenu records add the following code:
  985.  
  986.              GetMainMenu (SecondMenu);
  987.              MenuMode := MultipleChoice;
  988.              Title   := 'Second';
  989.              Line[1] := 'A2 line';
  990.              Line[2] := 'B2 line';
  991.              Line[3] := 'C2 line';
  992.              Line[4] := 'D2 line';
  993.              MsgLineNum  := ord(MainML);
  994.              HelpWndwNum := ord(MainMenuHW);
  995.              SaveMainMenu;
  996.  
  997.            Now run the program.  You can see that there are now three menus that can
  998.            be pulled down.  They are arranged in the order of the MainMenuNames.  Just
  999.            for fun, let's reverse the names in MainMenuNames and see what happens:
  1000.  
  1001.              MainMenuNames = (NoMainMenu,SecondMenu,FirstMenu,QuitMenu);
  1002.  
  1003.            When you test this, you will find the two menus in different positions.
  1004.            This makes rearranging a snap.  We didn't even have to change anything
  1005.            about the MainMenu records themselves.
  1006.  
  1007.            Title - For a main menu, the title is required.  By default, the first
  1008.            letter is used for command letter after pressing F10.  Press F10 now and
  1009.            then press "S".  This will pull down the SecondMenu.  But what about the
  1010.            global key Alt-S?  Press F2 to get back to the work window and try Alt-S.
  1011.            Nothing happens.
  1012.  
  1013.  
  1014.            Chapter 3, Programming Menus                                        Page 17
  1015.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1016.  
  1017.  
  1018.  
  1019.            Global Key - To assign an extended key combination to this menu, go to the
  1020.            bottom of the file to the section called Check Global Keys.  In this code,
  1021.            an assignment can be made for this menu.  Insert the following line into
  1022.            the code:
  1023.  
  1024.              ...
  1025.              AltF: SetCmdSeq ('F');
  1026.              AltS: SetCmdSeq ('S');   { insert this line }
  1027.              AltQ: SetCmdSeq ('Q');
  1028.              ...
  1029.  
  1030.            This is part of a case statement, so the order is not important.  In
  1031.            addition, a value must be assigned to the constant AltS.  Back up a few
  1032.            lines and add:
  1033.  
  1034.              ...
  1035.              AltF = #33;
  1036.              AltS = #31;  { insert this line }
  1037.              AltQ = #45;
  1038.              ...
  1039.  
  1040.            Now run the code and try Alt-S again to find that it now works.  But what
  1041.            did we just do?  Any time an extended key is pressed at the keyboard, the
  1042.            program always passes through the procedure called CheckGlobalKeys.  If the
  1043.            extended keycode matches one in the case statement, the program sets a
  1044.            sequence of normal key codes that would be pressed just as if pressing F10
  1045.            and then "S".  The keycode constant can be referenced in Appendix C of the
  1046.            TP5 reference manual.
  1047.  
  1048.  
  1049.            ADDING SUBMENUS
  1050.  
  1051.            Every menu can pull down another submenu.  This section will show how to
  1052.            include one.  The method is much the same as with main menus.
  1053.  
  1054.  
  1055.            Submenu Name - Also at the beginning of PULLSTAT.PAS is an enumerated type
  1056.            called SubMenuNames which looks like:
  1057.  
  1058.              SubMenuNames = (NoSubMenu,MySubMenu);
  1059.  
  1060.            Let's go ahead and use the name MySubMenu.
  1061.  
  1062.            Submenu Record - Just after the main menu record QuitMenu is an area for
  1063.            submenus.  There is already a record made for MySubMenu and looks like the
  1064.            following:
  1065.  
  1066.              GetSubMenu (MySubMenu);
  1067.              MenuMode := SingleChoice;
  1068.              SingleFlagLine := 5;
  1069.              Line[1] := '1 line';
  1070.              Line[2] := '2 line';
  1071.              Line[3] := '3 line';
  1072.              Line[4] := '4 line';
  1073.  
  1074.  
  1075.            Chapter 3, Programming Menus                                        Page 18
  1076.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1077.  
  1078.  
  1079.              MsgLineNum  := ord(SubML);
  1080.              HelpWndwNum := ord(SubMenuHW);
  1081.              SaveSubMenu;
  1082.  
  1083.            It is exactly like the main menu record, except to get and save it,
  1084.            GetSubMenu and SaveSubMenu are used.  A title is not required for a
  1085.            submenu as InitPull automatically gives it the name of the parent menu.
  1086.            Now let's link the submenu to a main menu.
  1087.  
  1088.            Linking Menus - Choose SecondMenu line 2 for the line where MySubMenu is to
  1089.            be linked.  In the SecondMenu (not the submenu) record, modify line 2 to
  1090.            the following code:
  1091.  
  1092.              ...
  1093.              Title   := 'Second';
  1094.              Line[1] := 'A2 line';
  1095.              Line[2] := 'B2 line';  LineMode[2] := ToSubMenu;
  1096.                                     LinkNum [2] := ord(MySubMenu);
  1097.              ...
  1098.  
  1099.            Run the code and see that the submenu is pulled down when you press RETURN
  1100.            on line 2 of SecondMenu.  This is probably simpler than you thought!  You
  1101.            can also see a three-bar symbol on this line which indicates the line is
  1102.            linked to a submenu.  By setting the line mode to ToSubMenu, the program is
  1103.            prepared to pull-down another menu.  LinkNum identifies the record to be
  1104.            pulled which is MySubMenu.  LinkNum is a byte type so using Ord is
  1105.            required.
  1106.  
  1107.            Linking Configuration - The submenus link in a slide-up rather than a
  1108.            slide-under configuration.  Menus grow vertically as the list expands.  If
  1109.            the list gets too long, it can slide up when it hits the bottom of the
  1110.            screen.  This leaves both the main menu and submenu in full view.  In
  1111.            contrast, the data windows, which are covered later, use the slide-under
  1112.            configuration.
  1113.  
  1114.            Default Linking Direction - Most Submenu are linked to the main menu in a
  1115.            right-preferred arrangement.  When menus get crowded to the right, InitPull
  1116.            will automatically reverse to the left and all dot and 3-bar symbols will
  1117.            also appear on the left.  Each subequent Submenu will continue to link in
  1118.            the same direction as its parent as far as it can.
  1119.  
  1120.            Manual Linking Direction - As long as LinkDir is not specified like in our
  1121.            example, InitPull will configure it for you.  However, this may not be
  1122.            preferred in all cases.  To specify it manually, set the value of LinkDir
  1123.            in that menu record to Left or Right which forces all submenus to be linked
  1124.            in that direction.
  1125.  
  1126.            Global Key - Suppose this is a frequently used submenu and we want to
  1127.            assign an extended key, say Alt-M, to access it.  To do this, it is much
  1128.            the same as with a main menu, except there is an additional keystroke.  Add
  1129.            the following line to CheckGlobalKeys:
  1130.  
  1131.              AltM: SetCmdSeq ('SB');
  1132.  
  1133.            and include a value for the constant Alt-M:
  1134.  
  1135.  
  1136.            Chapter 3, Programming Menus                                        Page 19
  1137.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1138.  
  1139.  
  1140.  
  1141.              AltM = #50;  { the Alt-M  extended key code }
  1142.  
  1143.            When you run the program, pressing Alt-M will pull down both SecondMenu and
  1144.            MySubMenu just as if you had sequentially pressed F10, "S" and "B".
  1145.  
  1146.            SetCmdSeq - PULL saves the sequence of keystrokes for the current menu
  1147.            level in a global string variable called CmdSeq.  SetCmdSeq compares the
  1148.            current location of CmdSeq with the new destination and sets two variables
  1149.            for the shortest path - MoreCmdSeq and PopLevels.  This will be covered
  1150.            later in detail under the Control Flags section.
  1151.  
  1152.            SubSubmenus - SubSubmenus can be added in just the same way as submenus.
  1153.            In fact you could nest them as deep as you want.  InitPull expects the
  1154.            record names in SubMenuNames to be in a certain order so it can properly
  1155.            locate each one on the CRT.  Just be sure that the order is all Submenus
  1156.            first, all SubSub-menus second, all SubSubSubmenus third, etc.
  1157.  
  1158.  
  1159.            HELP MESSAGES
  1160.  
  1161.            Each menu has a help message that is displayed on the last line of the CRT
  1162.            where the application can indicate valid keys and status or error messages.
  1163.            In this section, you will discover how these messages can be linked to any
  1164.            menu while it is displayed.
  1165.  
  1166.  
  1167.            Reserved Messages - PULL has already included some predefined messages for
  1168.            several contexts including those for main menus and submenus.  In
  1169.            PULLSTAT.PAS, just below the last submenu record, you can find an array of
  1170.            MsgLines.  The ones reserved for main menus and submenus are MainML and
  1171.            SubML, respectively:
  1172.  
  1173.              MsgLine[ord(MainML)]:=' F1-help  F2-pop   LTR-cmd  ESC-return  '+
  1174.                                    '        '^[^Z' menus  '^X^Y'-hilight  CR-select';
  1175.              MsgLine[ord(SubML)] :=' F1-help  F2-pop   LTR-cmd  ESC-return  '+
  1176.                                    '                  '^X^Y'-hilight  CR-select';
  1177.  
  1178.            The concatenation is just so that it will fit within an 80 column width in
  1179.            the source code.  Back at the top of the file, you can find the enumerated
  1180.            type MsgLineNames that helps identify each message.  All the messages up to
  1181.            HelpML are reserved as PULL expects them to be in that order.  But new ones
  1182.            can be added.
  1183.  
  1184.            New Messages - To create a new message, just append a name in the
  1185.            MsgLineNames type and write out your new message.  Let's try it on the Quit
  1186.            menu by changing MsgLineNum in its menu record as follows:
  1187.  
  1188.              ...
  1189.              Line[2] := 'Quit';      ProcPtr[2] := @SetQuit;
  1190.              BackToDefault := true;
  1191.              MsgLineNum := ord(QuitML);
  1192.              ...
  1193.  
  1194.            Then append the name QuitML to the end of MsgLineNames:
  1195.  
  1196.  
  1197.            Chapter 3, Programming Menus                                        Page 20
  1198.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1199.  
  1200.  
  1201.  
  1202.              MsgLineNames = (NoML,WorkML,TopML,AltML,MainML,SubML,DW_ML,DE_ML,
  1203.                              SeqML,HelpML,ProcML,QuitML);
  1204.  
  1205.            And finally, let's create the message itself:
  1206.  
  1207.              MsgLine[ord(QuitML)] := ' Press "Q" if you are sure you want to quit.';
  1208.  
  1209.            Short messages are no problem, because PULL will clear the rest of the
  1210.            message line.  Run the program now and see that the new message appears
  1211.            when the Quit menu is pulled.  By now, you are seeing that pull-down menus
  1212.            can link other menus and messages quite easily.
  1213.  
  1214.            Alt Key Message - You may have noticed when you hold down the Alt for more
  1215.            than a half second, a message appears for the possible combinations.  When
  1216.            we created a submenu with global key access, it is not likely a first-time
  1217.            user would know the key was available.  The AltML message is reserved for
  1218.            this purpose.  Let's alter the line to:
  1219.  
  1220.              MsgLine[ord(AltML)] :=' Alt: F-First  M-MySubMenu              '+
  1221.                                    '                                 X-Exit';
  1222.  
  1223.            Run the program and hold down the Alt key to test the new message.
  1224.  
  1225.  
  1226.            HELP WINDOWS
  1227.  
  1228.            Many times the help message is not enough to fully explain the options
  1229.            available for the context.  In this section, you will discover how to
  1230.            create context-sensitive help windows and apply them to the menus.
  1231.  
  1232.  
  1233.            Help Window Record - Just as each menu has its own record, each Help Window
  1234.            also has one called HelpWndw.  There are only a couple of variables that
  1235.            need adjustment, to link in the number of lines to be included in the
  1236.            window.  Let's try creating a help window for a main menu.
  1237.  
  1238.            Example Window - Run the current example program again and test the F1
  1239.            key while the SecondMenu is pulled down.  You should see a two-line help
  1240.            window with the message "Main menu help message".  So, some help window is
  1241.            already there, but the message is just bare bones.  Let's find out how the
  1242.            message got there and alter it.
  1243.  
  1244.            Help Lines - In PULLSTAT.PAS after the MsgLine messages, there is another
  1245.            section for setting HelpLines.  You should be able to see the code:
  1246.  
  1247.              HelpLine[ord(HLm1)]:='Main menu help message';
  1248.              HelpLine[ord(HLmL)]:='';
  1249.  
  1250.            These are the actual messages you saw in the help window.  Each window can
  1251.            have a variable number of lines in the help window.  The program will
  1252.            automatically size the window to fit in all the lines.  Let's edit and add
  1253.            an extra line:
  1254.  
  1255.  
  1256.  
  1257.  
  1258.            Chapter 3, Programming Menus                                        Page 21
  1259.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1260.  
  1261.  
  1262.              HelpLine[ord(HLm1)]:='Main menu help message';
  1263.              HelpLine[ord(HLm2)]:='Press RETURN on the highlighted line to make';
  1264.              HelpLine[ord(HLmL)]:='your selection.';
  1265.  
  1266.            Since a new HelpLine name, HLm2, has been added, it must be inserted in the
  1267.            enumerated type HelpLineNames at the top of the file:
  1268.  
  1269.              ...
  1270.              HLt1,HLtL,        { Top Line Menu }
  1271.              HLm1,HLm2,HLmL,   { Main menu }        { Modify this line. }
  1272.              HLs1,HLsL         { Submenu }
  1273.              ...
  1274.  
  1275.            Now run the program and test the modified help window.  This time you
  1276.            should see the three lines.  With just a couple of changes, all help
  1277.            windows are still in order along with the contents because it is so easy to
  1278.            work with names instead of numbers.  How did the program know how many
  1279.            lines to display even though changes were made?
  1280.  
  1281.            Number of Help Lines - In the section just below the HelpLines, see the
  1282.            following code:
  1283.  
  1284.              ...
  1285.              HelpMsgLineNum := ord(HelpML);     { Standard message for a Help window }
  1286.              SetHelpLines (WorkWndwHW,HLw1,HLwL);
  1287.              SetHelpLines (TopMenuHW ,HLt1,HLtL);
  1288.              SetHelpLines (MainMenuHW,HLm1,HLmL);
  1289.              ...
  1290.  
  1291.            The call to SetHelpLines is a trivial procedure listed earlier in the code
  1292.            that simply sets the first and last line number into the help window record
  1293.            by using HelpLineNames.  Notice that the first and last line names end with
  1294.            1 and L respectively.  This makes it handy so these statements never need
  1295.            to be altered when new lines are added or inserted.
  1296.  
  1297.            Help Window Names - The window name is MainMenuHW which in listed the
  1298.            enumerated type HelpWndwNames at the beginning of PULLSTAT.PAS:
  1299.  
  1300.              HelpWndwNames = (NoHW,WorkWndwHW,TopMenuHW,MainMenuHW,SubMenuHW,
  1301.                               DataWndwHW);
  1302.  
  1303.            Help Window Record - A help window record is assigned to each one of these
  1304.            names.  In the SecondMenu record, we can find the window record name by
  1305.            examining the following:
  1306.  
  1307.              ...
  1308.              MsgLineNum  := ord(MainML);
  1309.              HelpWndwNum := ord(MainMenuHW);
  1310.              SaveMainMenu;
  1311.              ...
  1312.  
  1313.            So now we can finally see how this help window was assigned to the main
  1314.            menu.  Rather than having a standardized help window for each main menu as
  1315.            a whole, you can even create new ones just as new message lines were
  1316.            created:
  1317.  
  1318.  
  1319.            Chapter 3, Programming Menus                                        Page 22
  1320.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1321.  
  1322.  
  1323.  
  1324.              1. Append HelpWndwNames.
  1325.              2. Append HelpLineNames.
  1326.              3. Make HelpLine assignments.
  1327.              4. Use SetHelpLines to identify the first and last help lines.
  1328.              5. Assign the HelpWndwNum to the menu record.
  1329.  
  1330.            Help Message - Even the help window needs a help message.  One has already
  1331.            been standardized for you called HelpML.  InitPull will initialize all help
  1332.            windows to be assigned the message number in HelpMsgLineNum.
  1333.  
  1334.            Window Width - All help windows have a standard width which is set by a
  1335.            configuration constant in P55-VAR.INC called HelpCharsPerLine currently set
  1336.            at 50.  The program adds 2 to this value to leave a space between the left
  1337.            and right borders.  The value can only be changed with the source code.
  1338.  
  1339.            No Help Window - If there are selected records where a help window is not
  1340.            wanted, just set:
  1341.  
  1342.              HelpWndwNum := NoHW;
  1343.  
  1344.            Integrated Help Windows - This system will integrate the help windows into
  1345.            the EXE file.  With enumerated names, up to 255 lines can be included.  If
  1346.            you need more, it is suggested that you develop a disk-based help system
  1347.            which is currently beyond the scope of the this utility.
  1348.  
  1349.  
  1350.            DEFAULT ATTRIBUTES
  1351.  
  1352.            This section will show the variables used to create default attributes for
  1353.            menus, windows and messages.
  1354.  
  1355.  
  1356.            InitPull - At the very first of the procedure GetUserPullStats, several
  1357.            default attribute variables can be given assignments.  For instance,
  1358.            MainMenuWattr will be used by InitPull to give all main menus the same
  1359.            window attribute for Wattr in the menu record.  This saves you from having
  1360.            to make the same assignment to every menu record.
  1361.  
  1362.            Attributes - As a personal preference, many users prefer the screen to have
  1363.            different attribute when possible.  The following is the list of default
  1364.            attributes and what they affect:
  1365.  
  1366.                                Record
  1367.              Default variable  Variable   Description
  1368.              ----------------  ---------  ------------------------------------------
  1369.              TopLineMenuAttr   n/a        Full length of the top line menu.
  1370.              TopLineMenuHattr  n/a        Top line menu HiLite.
  1371.              TopLineMenuLattr  n/a        Top line menu command Letter.
  1372.  
  1373.              MainMenuWattr     Wattr      Main menu Window.
  1374.              MainMenuBattr     Battr      Main menu Border.
  1375.              MainMenuHattr     Hattr      Main menu HiLite.
  1376.              MainMenuLattr     Lattr      Main menu command Letter.
  1377.              MainMenuCattr     Cattr      Main menu Comment line.
  1378.  
  1379.  
  1380.            Chapter 3, Programming Menus                                        Page 23
  1381.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1382.  
  1383.  
  1384.  
  1385.              SubMenuWattr      Wattr      Sub menu Window.
  1386.              SubMenuBattr      Battr      Sub menu Border.
  1387.              SubMenuHattr      Hattr      Sub menu HiLite.
  1388.              SubMenuLattr      Lattr      Sub menu command Letter.
  1389.              SubMenuCattr      Cattr      Sub menu Comment line.
  1390.  
  1391.              HelpWndwWattr     Wattr      Help Window Window.
  1392.              HelpWndwBattr     Battr      Help Window Border.
  1393.  
  1394.              MsgLineAttr       n/a        Message line full length.
  1395.              ErrMsgAttr        n/a        Error messages.
  1396.              KeyStatusAttr     n/a        Key status of NumLock, Caps, and ScrollLock.
  1397.  
  1398.            Find the variable MainMenuBattr and modify it to inverse video:
  1399.  
  1400.              MainMenuBattr := LightGrayBG;
  1401.  
  1402.            When you run the program, you will find that every main menu has this new
  1403.            attribute.  All the other variables work similarly.
  1404.  
  1405.            Mono vs. Color - You probably noticed an "if" statement in the code testing
  1406.            the current video mode.  The results of this test allows you to configure
  1407.            the menus for either Monochrome or color monitors.  Refer to your technical
  1408.            reference manual for the effects of one attribute on either monitor.
  1409.  
  1410.  
  1411.            DEFAULT BORDERS
  1412.  
  1413.            This section will show the variables used to create default border styles
  1414.            for the menus and windows just like the attributes mentioned above.
  1415.  
  1416.  
  1417.            Border Styles - The following is a list of default border style variables
  1418.            and what they affect:
  1419.  
  1420.                                Record
  1421.              Default variable  Variable   Description
  1422.              ----------------  ---------  -----------------
  1423.              MainMenuBrdr      Border     All main menus.
  1424.              SubMenuBrdr       Border     All submenus.
  1425.              HelpWndwBrdr      Border     All help windows.
  1426.  
  1427.            The shell program has assigned MainMenuBrdr to a custom border UserBrdr1.
  1428.            Let's modify this to SingleBrdr:
  1429.  
  1430.              MainMenuBrdr := SingleBrdr;
  1431.  
  1432.            In addition, you can optionally comment out the assignment of UserBrdr1 in
  1433.            the previous line since it is no longer needed.  When the program is run,
  1434.            all main menus will now have a single-line border style including the
  1435.            partitions.
  1436.  
  1437.  
  1438.            CONTROL FLAGS
  1439.  
  1440.  
  1441.            Chapter 3, Programming Menus                                        Page 24
  1442.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1443.  
  1444.  
  1445.  
  1446.            The pull-down menus can be programmably controlled in your program by
  1447.            toggling various pull-down control flags.  This helps direct the users to
  1448.            the needed menus automatically instead of manually pressing a key sequence.
  1449.            In this section, you will discover these flags and what they control.  Save
  1450.            the shell program now for later use and get back to PULLDEMO for this
  1451.            section.
  1452.  
  1453.            Control Variables - Here is the list of variables that control the menus:
  1454.  
  1455.              PopToWorkWndw - (Type: boolean) if true, all menus are removed and
  1456.                              control is returned to the work window.
  1457.              PopToTop      - (Type: boolean) if true, control is set to the Top Line
  1458.                              menu.
  1459.              PopLevels     - (Type: byte) number of levels (or menus) to pop.
  1460.              Popped        - (function) pops all menus before execution of ExecPtr.
  1461.              MoreCmdSeq    - (Type: string) series of command letters to do after
  1462.                              popping.
  1463.              PullDown      - (Type: boolean) if true, the menus will be pulled down
  1464.                              according to MoreCmdSeq.
  1465.  
  1466.            Examples - Run PULLDEMO and access Alt-I/Update.  In the Update menu, there
  1467.            are six examples of how the menus can be controlled in combination with
  1468.            executing a ProcPtr.  Execute each of those six lines to see what they do.
  1469.            In PULLSTAT.PAS, search for "GetSubMenu (UpdateMenu)" and see that each
  1470.            line is executing ProcPtr in the menu, so let's find out what those
  1471.            procedures are doing.
  1472.  
  1473.            Process Then Pop - Back up until you find the ProcessThenPop procedure.
  1474.            Very simply, the program first executed DummyProc and then set
  1475.            PopToWorkWndw true.  When the flow of execution passes back through the key
  1476.            dispatcher, PULL will immediately pop all menus and return to the top work
  1477.            window.
  1478.  
  1479.            Pop Then Process - But suppose we want to do the reverse.  Anytime ProcPtr
  1480.            is used for execution, a copy of it is kept in the global variable ExecPtr.
  1481.            By using Popped, the function sets the appropriate flags to pop the menus.
  1482.            The first time Popped is tested, it is false.  So, DummyProc is not
  1483.            executed.  Once the menus are popped back to the work window, PULL executes
  1484.            ProcPtr again via ExecPtr.  This time Popped will be true and DummyProc
  1485.            will be executed.
  1486.  
  1487.            Pop, Process, and Pull - Let's go one step further and pull the same menus
  1488.            back down that were popped.  Looking few lines down further in the
  1489.            PopProcessAndPull procedure, the new line that was added is setting
  1490.            PullDown to true.  But how does the program know what menus to pull?  PULL
  1491.            keeps a copy of the last command sequence in the string MoreCmdSeq.  When
  1492.            PullDown is true, the menus are pulled down by MoreCmdSeq.  This is useful
  1493.            when there is something under the menus that needs to be changed like
  1494.            accessing another work window.
  1495.  
  1496.            Popping Levels - Or, if you just want to back up a number of menu levels,
  1497.            just specify the number of levels to pop with PopLevels.  In the procedure
  1498.            PopNumOfLevels, rather than making the menu completely disappear only to
  1499.            needlessly pull them back down again, this procedure pops back as far as it
  1500.  
  1501.  
  1502.            Chapter 3, Programming Menus                                        Page 25
  1503.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1504.  
  1505.  
  1506.            needs to go and then additionally pulls down another submenu (or data
  1507.            window).  This sequence is useful when you know exactly where you are and
  1508.            where you are going.
  1509.  
  1510.            Popping to New Menus - If you need to go to a new menu, you can use the
  1511.            flag PopToTop which will pop the menus up to the Top Line.  By setting
  1512.            PullDown true and MoreCmdSeq to the desired menu, you can get to the new
  1513.            destination like the procedure PopToNewMenu.
  1514.  
  1515.            Smart Pop and Pull - But suppose the menus will execute the same ProcPtr
  1516.            from three different locations in the menus, and still want it to appear
  1517.            smart like PopNumOfLevels does?  PULL has a procedure called SetCmdSeq that
  1518.            compares the current location, CmdSeq, with your destination.  It sets
  1519.            MoreCmdSeq and PopLevels to the shortest path.  In fact, PopNumOfLevels
  1520.            could have looked like:
  1521.  
  1522.              procedure PopNumOfLevels;
  1523.              begin
  1524.                PullDown := true;
  1525.                SetCmdSeq ('IY');
  1526.              end;
  1527.  
  1528.            The parameter for SetCmdSeq is the full sequence of command letters to be
  1529.            pressed from the Top Line.
  1530.  
  1531.            Sequential Data Windows - One application of these control flags may be
  1532.            sequential entry for data windows.  Access Alt-I/Date and press RETURN a
  1533.            few times to see how the menus are cycled in a loop for the date.  To see
  1534.            how it was done, follow the ProcPtrs in the DateMenu and see what flags
  1535.            were set.
  1536.  
  1537.  
  1538.            SUMMARY
  1539.  
  1540.            At this point in the tutorial, you've been able to master the configuration
  1541.            of the top line, main, and sub menus with all the menu modes and most of
  1542.            the line modes.  In addition, you found how to add menus and submenus
  1543.            and assign help messages and help windows.  You changed the appearance of
  1544.            the menus with attributes and borders.  You could even programmably control
  1545.            the sequence of menus that were pulled down.  These were all accomplished
  1546.            by just filling out the appropriate variables.
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.            Chapter 3, Programming Menus                                        Page 26
  1564.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1565.  
  1566.  
  1567.            4.  S C R E E N   D E S I G N
  1568.  
  1569.            You are now at a point where you understand most of the fundamental
  1570.            features in PULL.  In this section, you will discover how to control the
  1571.            arrangement of the major components of full screen design.  You will be
  1572.            able to relocate the Status line, Top Line menu, Main menus, Work
  1573.            window(s), and Message line.  Arrangement of the components will depend on
  1574.            the human factors needed for your application.
  1575.  
  1576.  
  1577.            STATUS LINE
  1578.  
  1579.            The Status line is a row that you can reserve for pertinent information.
  1580.            In the shell program, the status line is assumed to be row 1 where a
  1581.            program name, title, and copyright were placed.  In the TP5 environment,
  1582.            row 2 is the status line for line, column, and insert status.  Actually,
  1583.            PULL does nothing to program this line, but PULL was designed to work
  1584.            around it.
  1585.  
  1586.  
  1587.            TOP LINE MENU
  1588.  
  1589.            Showing the Top Line - The top line menu is automatically created by
  1590.            assembling the titles from each main menu.  So, the string is already
  1591.            created for you in the string variable TopLineStr.  To write this string to
  1592.            the screen, simply call ShowTopLine.  But where is it placed?
  1593.  
  1594.            Top Line Placement - Back in GetPullUserStat, search for the variable
  1595.            TopLineRow.  It is found in a section called Top Line Defaults.  This is
  1596.            the variable that determines where the top line is placed:
  1597.  
  1598.              TopLineRow := 2;     { Top Line menu to appear on row 2. }
  1599.  
  1600.            Let's try reversing the Status line and the Top line menu in the shell
  1601.            program.  Set TopLineRow to 1 and then look in PULLSHEL.PAS and modify the
  1602.            row of the Status line to 2:
  1603.  
  1604.              WWrite ( 2, 1,'PULLSHELL v5.5            Multi-level Pu'+
  1605.                            'll-down Menus       Copr 1989  J H LeMay');
  1606.  
  1607.            Now run the program and see both lines reversed, but when the main menus
  1608.            are pulled, they are still on row 3.  How can they be moved?
  1609.  
  1610.  
  1611.            MAIN MENU ROW
  1612.  
  1613.            Main Menu Row - The row on which the main menus appear is controlled by
  1614.            the value of MainMenuRow.  The Main menus do not have to be attached to Top
  1615.            Line menu and can appear on any row provided they do not interfere with
  1616.            the Message line.
  1617.  
  1618.            Moving the Row - Let's shift the Main menus back up so they will appear
  1619.            to be attached to the Top Line menu.  In PULLSTAT.PAS, search for:
  1620.  
  1621.              MainMenuRow := 3;  { First row of main menus to appear on row 3 }
  1622.  
  1623.  
  1624.            Chapter 4, Screen Design                                            Page 27
  1625.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1626.  
  1627.  
  1628.  
  1629.            and change it to 2.  Run the program again to see that the main menus pull-
  1630.            down now on row 2.  But also check the submenu by pressing Alt-M.  Even the
  1631.            submenu is correctly placed!  InitPull accommodates the changes.
  1632.  
  1633.  
  1634.            SUBMENU ROW
  1635.  
  1636.            SubMenu Row - Try to arrange the lines in your menus that link submenus so
  1637.            that they are as high in the menu as practical.  Otherwise, long menus will
  1638.            bottom out on the CRT and PULL will be sliding up the menus to keep them in
  1639.            view.  PULL handles this well by using the slide-up configuration, but the
  1640.            menus will not appear to have much foresight in your design.  The
  1641.            Alt-A/Tires/Brands menu is a good example of keeping menus high.
  1642.  
  1643.  
  1644.            WORK WINDOWS
  1645.  
  1646.            Window Modes - The major portion of the screen is intended to be the work
  1647.            window for your application.  This area can have one or more windows and
  1648.            they can be in any window mode that you chose - even virtual.  Usually one
  1649.            of the modes can be PermMode since there is no data to save under the
  1650.            screen, but with a TSR, you may need to save the screen, too.
  1651.  
  1652.            Window Size - The example in the shell program uses a 22x80 PermMode window
  1653.            with border.  Let's get rid of the Status line, make the window larger, and
  1654.            at the same time, take off the double border.  In PULLSHEL.PAS, comment out
  1655.            the Status line with braces and modify the MakeWindow statement to the
  1656.            following:
  1657.  
  1658.            { WWrite ( 1, 1,'PULLSHELL v5.5            Multi-level Pu'+
  1659.                            'll-down Menus       Copr 1989  J H LeMay'); }
  1660.              ShowTopLine;
  1661.              SetWindowModes (PermMode);
  1662.              MakeWindow (2,1,CRTrows-2,CRTcols,White+BlueBG,White+BlueBG,NoBrdr,
  1663.                          Window1);
  1664.  
  1665.            Running the program, you will see the work window took up all but the Top
  1666.            Line menu in Row 1 and the Message line on the last row.  Notice also that
  1667.            the contents of the window also moved because they have window-relative
  1668.            coordinates.  This shows you the flexibility of your screen design.
  1669.  
  1670.  
  1671.            MESSAGE LINE
  1672.  
  1673.            Message Line - This is the line on which all messages will appear and is
  1674.            usually in reference to CRTrows to accommodate different video modes.  If
  1675.            the message line is intended to list key commands, for human factor
  1676.            reasons, it is best to keep it near the bottom row.
  1677.  
  1678.            Location - The location of the line is set by the variable MsgLineRow in
  1679.            GetUserPullStats.  To whatever line it is assigned, be sure that there is
  1680.            no possibility that it may be covered by other windows.  You may need to
  1681.            set the window margins to do this.
  1682.  
  1683.  
  1684.  
  1685.            Chapter 4, Screen Design                                            Page 28
  1686.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1687.  
  1688.  
  1689.  
  1690.            HELP WINDOWS
  1691.  
  1692.            There are two defaults that can be set for the Help windows - the bottom
  1693.            row and the window modes.  This section shows how these can be modified.
  1694.  
  1695.            Bottom Row - All help windows are centered column-wise on the CRT.
  1696.            However, the default bottom row of the window is assigned to HelpBottomRow
  1697.            and is allowed to grow upward.  This variable is used to calculate the
  1698.            upper left corner of the window and sets the Row and Col for each help
  1699.            window record.
  1700.  
  1701.            Window Modes - The current example program uses a shadow with zoom effect
  1702.            when the help window appears.  The cursor mode is also turned off.  This
  1703.            default is assigned to HelpWndwModes which in turn assigns it to HWmodes in
  1704.            each help window record.
  1705.  
  1706.            Example - In the shell program, search for HelpWndwModes and modify the
  1707.            code to the following:
  1708.  
  1709.              ...
  1710.              HelpWndwModes := CursorOffMode;
  1711.              HelpBottomRow := CRTrows-10;
  1712.              ...
  1713.  
  1714.            When you test any help window this time, the window will appear instantly
  1715.            without the zoom effect and is placed higher from the bottom.
  1716.  
  1717.  
  1718.            START-UP MENU
  1719.  
  1720.            Control Variables - When the program first starts, you can also have the
  1721.            program pull down any menu using the Top Line variables MPulled, PullDown,
  1722.            and MoreCmdSeq.  Search again for TopMenuRow and see this code:
  1723.  
  1724.              TopMenuRow := 1;
  1725.              MPulled    := ord(FirstMenu);
  1726.              MoreCmdSeq := 'F';
  1727.              PullDown   := false;
  1728.  
  1729.            MPulled - This is initial assignment for the main menu title that would be
  1730.            highlighted when pressing F10 for the first time.
  1731.  
  1732.            MoreCmdSeq - This is the actual variable that is set by the global key
  1733.            routine SetCmdSeq.  When F2 is pressed for the first time, it would emulate
  1734.            pressing F10 and "F" from the keyboard as if it remembered the last
  1735.            sequence of keystrokes.  MoreCmdSeq can have as many characters as needed
  1736.            to get down to the desired menu or window.  It is a good practice to make
  1737.            sure the first character matches the MPulled menu.
  1738.  
  1739.            PullDown - If this is true, the program will pull-down the menus just as if
  1740.            F2 had been pressed so that the menus pulled match the sequence in
  1741.            MoreCmdSeq.  Try setting PullDown to true and see if FirstMenu is indeed
  1742.            pulled.
  1743.  
  1744.  
  1745.  
  1746.            Chapter 4, Screen Design                                            Page 29
  1747.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1748.  
  1749.  
  1750.  
  1751.            OVERRIDING DEFAULTS
  1752.  
  1753.            PULL configures almost everything automatically, but sometimes things don't
  1754.            always fit the mold.  This section will show you how to override the
  1755.            settings before and after PULL has configured them.
  1756.  
  1757.  
  1758.            GetUserPullStats - Row/Col locations for submenus are located by default at
  1759.            run time with the slide-up configuration when these values remain zero, and
  1760.            likewise DWrow/DWcol for data windows for slide-under.  You can override
  1761.            PULL and locate them absolutely by giving them non-zero values in the
  1762.            procedure GetUserPullStats.
  1763.  
  1764.            Submenu Location - If submenus are unusually wide and will not fit in the
  1765.            slide-up configuration, PULL will terminate the program with a warning
  1766.            message to let you know of the problem.  If you set the variable
  1767.            LocationWarning false in GetUserPullStats, you can go ahead and test all
  1768.            submenus to see the one not fitting the slide-up configuration.  PULL will
  1769.            attempt slide-under as a second best.  If it still doesn't fit, then you
  1770.            need an override for the Row and Col setting.  If you are satisfied with
  1771.            the menu locations, you can optionally set LocationWarning false.  But be
  1772.            sure to check all the menus on the CRT to make sure they have been properly
  1773.            placed.
  1774.  
  1775.            GetOverrideStats - This procedure in PULLSTAT is executed after all the
  1776.            automatic configuration has been done.  If there are exceptions in your
  1777.            program, you can assign them inside this procedure.  For just a few
  1778.            changes, you can edit the records right in the heap.  Take a look at this
  1779.            procedure in PULLSTAT for PULLDEMO.  What kind of things would you
  1780.            typically change?
  1781.  
  1782.            Menu Command Letters - Not all menus use the first letter for the command
  1783.            letter.  What happens when two lines start with the same one?  Only the
  1784.            first one will ever be reached.  So, the command letters must be changed.
  1785.            The variable in the menu record that contains these letter is CmdLtrs.  For
  1786.            instance, the command letters for FirstMenu are 'ABCD' where character one
  1787.            corresponds to line 1, etc.  They are always upper case in this string, but
  1788.            can be lower case in the menu.  So, you can edit this string to whatever
  1789.            your command letters need to be.  In addition, that letter will also be
  1790.            highlighted in the menu.  Inaccessible line modes like Comment and
  1791.            Partition replace the command letter with #00.
  1792.  
  1793.            Top Line Command Letters - You can also do the same with the Top Line
  1794.            command letters which are kept in a global variable called TopCmdLtrs.
  1795.  
  1796.            Attributes and Borders - Sometimes the default attributes and borders need
  1797.            to be changed in a place or two.  GetOverrideStats is the place to make
  1798.            those changes.
  1799.  
  1800.  
  1801.            SUMMARY
  1802.  
  1803.            If you have completed the tutorial with the shell program up to this point,
  1804.            you should now have enough confidence with the major components of screen
  1805.  
  1806.  
  1807.            Chapter 4, Screen Design                                            Page 30
  1808.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1809.  
  1810.  
  1811.            design.  You can now develop a concept for your application that can best
  1812.            be suited the needs of your users.  If you would like to stop now, save the
  1813.            shell program so that it can to be used later in the following sections.
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828.  
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.  
  1859.  
  1860.  
  1861.  
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.            Chapter 4, Screen Design                                            Page 31
  1869.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1870.  
  1871.  
  1872.            5.  D A T A   W I N D O W S
  1873.  
  1874.            Often when a menu line is selected from a menu, a means is needed to enter
  1875.            data into the application such as numbers or file names.  PULL already has
  1876.            powerful utilities to do this for free-field data entry including flex
  1877.            fields, set checking, key translation, and range checking for nine types of
  1878.            data.
  1879.  
  1880.  
  1881.            DATA WINDOW PARTS
  1882.  
  1883.            There are two parts to a data entry window - the data entry field and the
  1884.            window.
  1885.  
  1886.            Data Entry Field - As the name implies, this is the place where characters
  1887.            are allowed to be entered for the data.  This is also called entry or field
  1888.            for short.
  1889.  
  1890.            Data Window - The window is the border and spacing surrounding the field.
  1891.            Using the term data window loosely refers to both the field and the window
  1892.            together.
  1893.  
  1894.  
  1895.            DATA WINDOW RECORD
  1896.  
  1897.            The arrangement of the records for data windows is very similar to the way
  1898.            menu records have been done.  So, the same concept of fill-in-the-blank is
  1899.            used.  In this section, you will find how these records can be filled out
  1900.            in the program.
  1901.  
  1902.  
  1903.            Top Data Window - Let's find the data window record and see what it
  1904.            contains:
  1905.  
  1906.              1. Load the file PULLDATA.PAS into the TP editor.
  1907.              2. Set PULLSHEL.PAS to be the Primary file.
  1908.              3. Search for "with TopDataWndw"
  1909.              4. See the following code:
  1910.  
  1911.                  GetDataWndw (ord(aByteDW));         { Just gets cleared DataWndw }
  1912.                  VarAddr       := @aByte;
  1913.                { TypeOfData    := Bytes; }           { This is the default }
  1914.                  Field         := 3;
  1915.                { MsgLineNum    := ord(DW_ML); }      { This is the default }
  1916.                { HelpWndwNum   := ord(DataWndwHW); } { This is the default }
  1917.                  SaveDataWndw;                       { Saves it in the heap }
  1918.  
  1919.            In the tutorial program of PULLSHEL.PAS, the program does not have any data
  1920.            windows linked to the menus yet, but this record has already been written
  1921.            to speed things along.  As you can see, only four lines were needed to be
  1922.            set in the Data Window record which is named aByteDW.  Let's go ahead and
  1923.            link this record into one of the menus.
  1924.  
  1925.            Linking Data Windows - Go back to PULLSTAT.PAS to find the FirstMenu record
  1926.            and revise it to add this data window to line 3:
  1927.  
  1928.  
  1929.            Chapter 5, Data Windows                                             Page 32
  1930.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1931.  
  1932.  
  1933.  
  1934.              GetMainMenu (FirstMenu);
  1935.              ...
  1936.              Line[1] := 'A line';
  1937.              Line[2] := 'B line';
  1938.              Line[3] := 'Enter Byte';  LineMode[3] := ToDataWndw;
  1939.                                        LinkNum [3] := ord(aByteDW);
  1940.              Line[4] := 'D line';
  1941.              ...
  1942.  
  1943.            When the program is run, pressing RETURN on line 3 will pull-down the data
  1944.            entry window.  The variable is a byte type which it was assigned by default
  1945.            in the data window record.  Go ahead and experiment with the entry by
  1946.            making mistakes such as a number over 255.  When you get an error message,
  1947.            just press ESC.  For the full list of editing keys, press F1 for the help
  1948.            window.
  1949.  
  1950.            Window Location - Notice that the location of the window is immediately
  1951.            underneath the HiLite and shifted slightly to the right.  This is called a
  1952.            slide-under configuration.  Since there is only one row in a Data Window,
  1953.            they tend to grow horizontally.   Should the window be too long for the
  1954.            right side of the screen, the window would then slide under the HiLite to
  1955.            the left until it fit.  This location is determined at run time.
  1956.  
  1957.            Justification - The entry is always left justified since it is an input-
  1958.            only window.
  1959.  
  1960.            Line Mode - If you remember about line modes, we did not get a chance to
  1961.            test ToDataWndw.  So, now you can see that this instructs PULL that a Data
  1962.            Window is linked to the menu and it then uses the named data window record
  1963.            for the window.
  1964.  
  1965.            Link Number - The number of the Data Window record linked is of course the
  1966.            value of the name aByteDW.  Again, names are used to easily arrange and
  1967.            identify the contents of the record.  So, how is the name assigned?
  1968.  
  1969.            Data Window Names - At the top of the file PULLSTAT.PAS (not PULLDATA.PAS),
  1970.            the enumerated type DataWndwNames has the following list:
  1971.  
  1972.              DataWndwNames = (NoDW,aByteDW);
  1973.  
  1974.            Only one window name has been assigned and that is the one being tested.
  1975.            There are no reserved names except NoDW since the window numbers are 1-
  1976.            based.  Notice that PULLDATA uses PULLSTAT.  Since DataWndwNames is in the
  1977.            interface, the names can also be used in PULLDATA.  Ok, the data is plugged
  1978.            into the window, but where is it being stored?
  1979.  
  1980.  
  1981.            DATA WINDOW VARIABLE
  1982.  
  1983.            Variable Address - To know where the variable is located, the record uses a
  1984.            pointer to the variable location.  The variable used in this window is
  1985.            aByte which is a typed constant declared at the beginning of PULLDATA.PAS
  1986.            and given a value of 100.  To get the address of the variable, you just
  1987.            place the "@" operator in front of the variable and it returns its FAR
  1988.  
  1989.  
  1990.            Chapter 5, Data Windows                                             Page 33
  1991.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  1992.  
  1993.  
  1994.            address.
  1995.  
  1996.            Type of Data - Because a pointer is being used instead of the variable
  1997.            itself, it is not known how many bytes the variable uses in memory and
  1998.            neither is the type of data.  So, PULL must be instructed what type of data
  1999.            is being accessed.  PULL can handle nine types of data which is enumerated
  2000.            in P55-VAR.INC:
  2001.  
  2002.              TypeOfDataType = (Bytes,Words,ShortInts,Integers,LongInts,Reals,UserNums,
  2003.                                Chars,Strings);
  2004.  
  2005.            The associated data types should be intuitive.  A special case is UserNums
  2006.            which are really strings, but are meant to be displayed as numbers like hex
  2007.            for example.  Remembering that all zero values in the record are the
  2008.            default, now you can see why TypeOfData defaulted to Bytes when nothing was
  2009.            assigned - good ol' fill-in-the-blank again.
  2010.  
  2011.            Matching the Type - Pascal has strong type checking and it can spoil you
  2012.            easily.  This arrangement of splitting the variable into a type and a
  2013.            pointer is most convenient for the Data Window.  However, it is up to your
  2014.            skills as a programmer to ensure that the type truly matches the data at
  2015.            that destination as PULL both reads and writes to it.
  2016.  
  2017.            Validity Check - All numeric types are given a validity check by using the
  2018.            Val procedure.  If the data entry can successfully be converted to the
  2019.            specified numeric type and without overflow, the data is considered valid.
  2020.            If not, the error message "Invalid entry." is displayed.  For now, here is
  2021.            a hint about error messages.  You can see the string for this message
  2022.            earlier in the file:
  2023.  
  2024.              ErrMsgLine[ord(InvalidEM)]:=' Invalid entry.           ESC-acknowledge';
  2025.  
  2026.  
  2027.            FIELDS
  2028.  
  2029.            This section gives instructions on how to adjust the field sizes for the
  2030.            data entry window.
  2031.  
  2032.            Field - Let's see how easy it to add a new data window on our own for
  2033.            strings and adjust the field sizes.  Right after the aByteDW record, add
  2034.            the following new record:
  2035.  
  2036.              GetDataWndw (ord(MyStringDW));
  2037.              VarAddr       := @MyString;
  2038.              TypeOfData    := Strings;
  2039.              Field         := 25;
  2040.              SaveDataWndw;
  2041.  
  2042.            At the top of the file, declare the constant MyString:
  2043.  
  2044.              ...
  2045.              aByte2: byte = 200;
  2046.              MyString: string[25] = 'This is my string.';
  2047.  
  2048.            Now let's link it into line 4 of the FirstMenu.  So, in PULLSTAT, modify
  2049.  
  2050.  
  2051.            Chapter 5, Data Windows                                             Page 34
  2052.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2053.  
  2054.  
  2055.            the FirstMenu record to:
  2056.  
  2057.              GetMainMenu (FirstMenu);
  2058.              ...
  2059.              Line[1] := 'A line';
  2060.              Line[2] := 'B line';
  2061.              Line[3] := 'Enter Byte';  LineMode[3] := ToDataWndw;
  2062.                                        LinkNum [3] := ord(aByteDW);
  2063.              Line[4] := 'My string';   LineMode[4] := ToDataWndw;
  2064.                                        LinkNum [4] := ord(MyStringDW);
  2065.              ...
  2066.  
  2067.            And let's not forget to add MyStringDW to the DataWndwNames type:
  2068.  
  2069.              DataWndwNames = (NoDW,aByteDW,MyStringDW);
  2070.  
  2071.            Run the program and test the data window.  Since Field was set to 25, the
  2072.            window was expanded to allow a 25 character entry with a space on either
  2073.            side.  So, whatever the field width is, that is how many characters can be
  2074.            entered in the string.  Notice that we were careful not to make Field
  2075.            larger than the string size so it would not overwrite too many characters
  2076.            at MyString's address.  But what if the string can have up to 100
  2077.            characters?  How can that be made to fit?
  2078.  
  2079.            Maximum Field - There are actually two variables to adjust the size of the
  2080.            entry field, one is Field and the other is MaxField.  Rather than
  2081.            explaining it, let's see what it can do.  First change the constant to:
  2082.  
  2083.              MyString: string[100] = 'This is my string.';
  2084.  
  2085.            and then add the variable setting of MaxField in the Data Window record:
  2086.  
  2087.              ...
  2088.              Field         := 25;
  2089.              MaxField      := pred(sizeof(MyString));      { = 100 }
  2090.              SaveDataWndw;
  2091.  
  2092.            Now when you run it, the field is flexible.  You can now enter up to 100
  2093.            characters even though the field only displays 25.  These fields are called
  2094.            flex fields.
  2095.  
  2096.            Default Field - By default, program sets MaxField equal to Field.  Anytime
  2097.            MaxField has been set and is not the equal to Field, the flex field becomes
  2098.            active.  So, this can be used with any type of data and not just strings.
  2099.  
  2100.  
  2101.            TITLES
  2102.  
  2103.            If your field is wide enough, you can easily add a title.  Try adding the
  2104.            following code to the MyStringDW record:
  2105.  
  2106.              GetDataWndw (ord(MyStringDW));
  2107.              Title         := 'Enter File Name';
  2108.              VarAddr       := @MyString;
  2109.              ...
  2110.  
  2111.  
  2112.            Chapter 5, Data Windows                                             Page 35
  2113.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2114.  
  2115.  
  2116.  
  2117.            Pulling down this data window, the title will be centered on the top row of
  2118.            the window.  Titles are optional and will be truncated if necessary to fit
  2119.            within the window.
  2120.  
  2121.  
  2122.            EDITING KEYS
  2123.  
  2124.            If you didn't get a chance to try out the full editing keys, here's the
  2125.            list and their function:
  2126.  
  2127.              Keys                          Movement
  2128.              ----------------------------  -----------------------------------------
  2129.              Left Arrow / ^S               Character Left/Right
  2130.              Right Arrow / ^D              Character Left/Right
  2131.              Home / Ctrl Left  Arrow / ^A  First character
  2132.              End  / Ctrl Right Arrow / ^F  Last character
  2133.              Del / ^G                      Deletes character under cursor
  2134.              Backspace / ^H                Deletes character to left of cursor
  2135.              Ins / ^V                      Toggles between insert and overwrite mode
  2136.              ^R/^U                         Restores original contents
  2137.              ^Y                            Deletes entire contents
  2138.  
  2139.            Insert Toggle - PULL allows you to use both insert and overwrite mode.  You
  2140.            can tell the status by the shape of the cursor.  The half-block cursor
  2141.            indicates the insert mode which appears correctly in any video mode.
  2142.  
  2143.            Cursor Handling - In flex fields, some special cursor handling has also
  2144.            been included that you will appreciate when the cursor is at either end.
  2145.            When adding characters to the far right there is always one space open
  2146.            until the maximum character is reached.  It helps identify the last
  2147.            character and shows the character when the Del key is used.  The same
  2148.            principle is used when backspacing - at least one character is always shown
  2149.            until the last one is deleted.  The cursor always remains confined inside
  2150.            the Field width on a flex field.
  2151.  
  2152.            One-Column Field - A special case is considered when Field is 1 column in
  2153.            width.  The cursor does not move and any valid character typed in will
  2154.            overwrite the contents.  Del or Backspace also deletes the contents.
  2155.            Please do not consider using flex fields for this case.
  2156.  
  2157.            AutoNumLock - On machines with enhanced keyboards, it may be an advantage
  2158.            to automatically turn on the NumLock when in Edit mode.  If so, by setting
  2159.            AutoNumLock true, numeric key pad will be have the NumLock turned on when
  2160.            you start editing.  After the edit, PULL will restore it to its original
  2161.            mode, on or off.  Please note that even though the "NUM" message appears on
  2162.            the message line to show the true internal status of NumLock, many machines
  2163.            do not have a smart enough BIOS to also toggle the NumLock LED on the
  2164.            keyboard itself.  Pressing the key can put it back in sync, but the "NUM"
  2165.            message is the thing to watch.
  2166.  
  2167.  
  2168.            KEY SETS
  2169.  
  2170.            This section gives instructions on how to use TP's powerful sets to screen
  2171.  
  2172.  
  2173.            Chapter 5, Data Windows                                             Page 36
  2174.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2175.  
  2176.  
  2177.            for valid keystrokes into the data entry.
  2178.  
  2179.  
  2180.            Entry Sets - As a preventative measure, each keystroke is checked against a
  2181.            set to see if it is valid before it is allowed into the field.  If it is
  2182.            not, the keystroke is simply ignored.  Several set have included and a
  2183.            default is given to each of the nine types of data:
  2184.  
  2185.              SetNames = (NoSet,UnsignedSet,SignedSet,RealSet,CharSet,
  2186.                          HexSet,FileNameSet,PathSet,MaskSet);
  2187.  
  2188.            where the following types are given the following sets:
  2189.  
  2190.              Type       Set
  2191.              ---------  -----------
  2192.              Bytes      UnsignedSet
  2193.              Words      UnsignedSet
  2194.              ShortInts  SignedSet
  2195.              Integer    SignedSet
  2196.              LongInts   SignedSet
  2197.              Reals      RealSet
  2198.              UserNums   CharSet
  2199.              Chars      CharSet
  2200.              Strings    CharSet
  2201.  
  2202.            Four more practical sets have also been included for your use.  To examine
  2203.            the contents of the sets, they are located in P55-VAR.INC in an array
  2204.            called EntrySet.  Since it is in the include file for PULL, these can only
  2205.            be modified when you have the complete source code.
  2206.  
  2207.            Assigning Sets - Most of your work can be done by default, but once in a
  2208.            while, a custom set will be required.  Let's change MyString to be a file
  2209.            name with only valid DOS characters by changing the MyStringDW record to:
  2210.  
  2211.              ...
  2212.              Field         := 25;
  2213.              MaxField      := pred(sizeof(MyString));      { = 100 }
  2214.              SetName       := FileNameSet;
  2215.              SaveDataWndw;
  2216.  
  2217.            Try entering a string into the window and find that invalid characters like
  2218.            the space, "\", and "*" can not be entered.  This gives the user immediate
  2219.            cues about the validity of the entry before it is completely entered.
  2220.  
  2221.  
  2222.            KEY TRANSLATION
  2223.  
  2224.            As each key is entered, it is possible to intercept the keystroke before it
  2225.            reaches the data entry editor.  This section will show how it is done.
  2226.  
  2227.  
  2228.            Translation Pointer - Each data window record has a translation pointer
  2229.            called TranslateProc.  You probably know by now, that the default is nil.
  2230.            If a valid FAR procedure is assigned to this pointer, it will be executed.
  2231.            Suppose you prefer to have the file name entries in upper case.  Modify
  2232.  
  2233.  
  2234.            Chapter 5, Data Windows                                             Page 37
  2235.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2236.  
  2237.  
  2238.            MyStringDW to:
  2239.  
  2240.              ...
  2241.              Field         := 25;
  2242.              MaxField      := pred(sizeof(MyString));      { = 100 }
  2243.              SetName       := FileNameSet;
  2244.              TranslateProc := @TranslateCase;
  2245.              SaveDataWndw;
  2246.  
  2247.            Back up a few lines to find this procedure and you will see:
  2248.  
  2249.              procedure TranslateCase;
  2250.              begin
  2251.                if not ExtKey then
  2252.                  Key := upcase(Key);        { Simple upper case translation }
  2253.              end;
  2254.  
  2255.            In PULL, Key is the character returned from ReadKey, and ExtKey is true if
  2256.            it is an extended key.  Notice that $F+ and $F- are used to force the
  2257.            procedure to FAR.  Run the program again and find that all keys typed in
  2258.            this data window are forced to upper case.
  2259.  
  2260.            Every Key - All keys can be translated with this procedure.  Even global
  2261.            or editing keys can be intercepted and translated to whatever is desired.
  2262.            It is also useful for foreign language translation.
  2263.  
  2264.  
  2265.            RANGE CHECKING
  2266.  
  2267.            After the entry is entered and checked as valid, there is one more option
  2268.            of checking the entry to make sure it is in the range or form that is
  2269.            acceptable to the program.  This section will show how to create range
  2270.            checking procedures and out of range error messages.
  2271.  
  2272.  
  2273.            Three Parts - Before setting up a range check, you need to understand how
  2274.            the data is transferred between the entry and the variable.  There are
  2275.            three parts to performing the data entry transfer - the data entry string,
  2276.            data pad, and destination variable.
  2277.  
  2278.            Data Entry String - The data entry string is the string that is seen and
  2279.            edited on the CRT.  This string is held in DataStr of type DataStrType and
  2280.            is declared in P55-VAR.INC.
  2281.  
  2282.            Reading - The data pad, called DataPad, is a two-way messenger that
  2283.            transfers data between the variable and DataStr.  When the data window is
  2284.            initially displayed, the data pad reads the contents of the variable and
  2285.            makes an exact copy of the value onto itself.  Then the program converts
  2286.            this value over to DataStr into a string form which the user can easily
  2287.            read and edit.
  2288.  
  2289.            Storing - As mentioned before, pressing RETURN after editing is completed,
  2290.            the program attempts to store the entry to the variable.  First, numeric
  2291.            data must pass a validity check by converting DataStr to a value.  If it
  2292.            passes, a copy of the converted data is now on the data pad.  Now is the
  2293.  
  2294.  
  2295.            Chapter 5, Data Windows                                             Page 38
  2296.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2297.  
  2298.  
  2299.            time to do a data range check.  By default, there is no check and the data
  2300.            would continue to be stored from the data pad to the destination variable
  2301.            as is.  But to do the range check, you need to know the identifiers that
  2302.            are used on the data pad.
  2303.  
  2304.            Data Pad Identifiers - The data pad is completely generic.  Any type of
  2305.            data occupies the exact same address.  So all you need to do is select the
  2306.            right identifier to match the type of data for your variable.  You can look
  2307.            at the data pad record in P55-VAR.INC for the field list, but here is a
  2308.            list of those identifiers:
  2309.  
  2310.              Type       Identifier
  2311.              ---------  ----------
  2312.              Bytes      Bdata
  2313.              Words      Wdata
  2314.              ShortInts  SIdata
  2315.              Integers   Idata
  2316.              LongInts   Ldata
  2317.              Reals      Rdata
  2318.              UserNums   UNdata
  2319.              Chars      Cdata
  2320.              Strings    Sdata
  2321.  
  2322.            Example - Let's set up a range check for aByteDW.  Modify its data window
  2323.            record to:
  2324.  
  2325.              GetDataWndw (ord(aByteDW));         { Just gets cleared DataWndw }
  2326.              ...
  2327.              Field         := 3;
  2328.              CheckRangeProc := @CheckAbyte;      { add this line. }
  2329.              SaveDataWndw;                       { Saves it in the heap }
  2330.  
  2331.            Arbitrarily, let the range for aByte be between 20 and 50 inclusive.  Now
  2332.            back up a few lines before the TranslateCase procedure and the following
  2333.            procedure has already been added for you:
  2334.  
  2335.              procedure CheckAbyte;
  2336.              begin
  2337.                with DataPad do
  2338.                  if ((Bdata<20) or (Bdata>50)) then
  2339.                    MakeErrMsg (20,50);
  2340.              end;
  2341.  
  2342.            Since aByte is byte type, Bdata is used for the comparison.  For the range
  2343.            check, any values under 20 or over 50 will run the MakeErrMsg procedure.
  2344.            Try it and see if you can produce the error message.
  2345.  
  2346.            Error Messages - How does PULL know if an error is found?  It tests the
  2347.            value of ErrMsg in DataPad.  If the value remains zero, then the range
  2348.            check is passed.  Otherwise, it has failed.  And, it uses this same value
  2349.            as the error message name.  The ErrMsgLines are much like the MsgLines
  2350.            using names for indexes.  Right after the implementation you can see the
  2351.            error message names:
  2352.  
  2353.              ErrMsgNames = (NoEM,UserEM,InvalidEM,MyEM);
  2354.  
  2355.  
  2356.            Chapter 5, Data Windows                                             Page 39
  2357.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2358.  
  2359.  
  2360.  
  2361.            The names up to InvalidEM are reserved.  The name UserEM is of most
  2362.            interest.  ErrMsgLine[ord(UserEM)] is meant to be customized by creating a
  2363.            message at run-time.  This saves you from making several hard-coded
  2364.            messages.  The example used MakeErrMsg, located a few lines back.  It is a
  2365.            good simple example how to set both ErrMsg and create a custom message on
  2366.            the UserEM.  But the important value is the change of ErrMsg.
  2367.  
  2368.            Message Length - Error messages tend to be short, so there is no need to
  2369.            allocate a full screen width for the message.  The maximum length of a
  2370.            message is set by MaxErrStrLength in P55-VAR.INC.  The program will
  2371.            automatically clear the remaining part of the line and takes special care
  2372.            not to do a needless full-line clear and thereby preventing a flicker
  2373.            effect.
  2374.  
  2375.            Maximum Message - Similarly, the maximum number of ErrMsgLines is set by
  2376.            NumOfErrMsgLines in P55-VAR.INC.
  2377.  
  2378.            Summary - The outcome of the range check is determined by the value of
  2379.            DataPad.ErrMsg.  PULL sets it to zero.  Compare your range with the DataPad
  2380.            identifiers in any fashion.  Only if it is out of range, set ErrMsg to the
  2381.            ErrMsgLine you want to show.
  2382.  
  2383.  
  2384.            HELP MESSAGES
  2385.  
  2386.            A help message can be assigned to the Data Window record exactly the same
  2387.            as the menus.  One name has already been reserved for the Data Window
  2388.            called DW_ML and is the default.  But you can also assign new ones.  The
  2389.            MsgLines and names are in PULLSTAT.PAS.
  2390.  
  2391.  
  2392.            HELP WINDOWS
  2393.  
  2394.            Again, just like the menus, help windows can be assigned to the Data
  2395.            Window.  The record name reserved for Data Window records is called
  2396.            DataWndwHW and is the default.  If you have not seen this window, run the
  2397.            program with a Data Window pulled and press F1.  The Help Window records
  2398.            and Help Lines are in PULLSTAT.PAS.
  2399.  
  2400.  
  2401.            DEFAULT ATTRIBUTES AND BORDER
  2402.  
  2403.            This section will show the variables used to create default attributes and
  2404.            border for the Data Window.
  2405.  
  2406.  
  2407.            Initialization - PULLDATA is self-initialized when it is included in the
  2408.            USES list.  There are two procedures that set up the colors and border:
  2409.  
  2410.              SetDefaultColors - assigns colors and border to the default variables.
  2411.              InitDataColors   - assigns the defaults to the Data Window record.
  2412.  
  2413.            SetDefaultColors - In PULLDATA, search for SetDefaultColors and see the
  2414.            following code:
  2415.  
  2416.  
  2417.            Chapter 5, Data Windows                                             Page 40
  2418.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2419.  
  2420.  
  2421.  
  2422.              DataWndwIattr  := Black+BrownBG;
  2423.              DataWndwOattr  := Yellow+BlackBG;
  2424.              DataWndwBattr  := Black+BrownBG;
  2425.              DataWndwBrdr   := HdoubleBrdr;
  2426.  
  2427.            InitDataColors - These variables in turn are assigned to the following
  2428.            record variables in DataWndw:
  2429.  
  2430.                                Record
  2431.              Default variable  Variable   Description
  2432.              ----------------  ---------  ----------------------------
  2433.              DataWndwIattr     Iattr      Attribute for Input
  2434.              DataWndwOattr     Oattr      Attribute for Output
  2435.              DataWndwBattr     Battr      Attribute of the Border
  2436.              DataWndwBrdr      Border     Border of the window
  2437.  
  2438.            Just like the menus, this saves you from having to make the same assignment
  2439.            to every menu record.  Try experimenting with the colors and border in the
  2440.            shell program and see the results.  Although NoBrdr is permissible, it is
  2441.            not suggested.
  2442.  
  2443.  
  2444.            DEFAULT LOCATION
  2445.  
  2446.            The location of a data window is placed by PULL at run time.  With the
  2447.            slide-under configuration, the menu is placed underneath the HiLite and
  2448.            shifted to the right 2 columns.  If necessary, it is shifted to the left to
  2449.            prevent wraparound.  To alter this position manually, set Row and Col in
  2450.            the menu record to your desired location.
  2451.  
  2452.  
  2453.            SUMMARY
  2454.  
  2455.            In addition to mastering the menus, you can now link data windows into the
  2456.            menus by adding and linking data window records in PULLDATA.PAS.  You have
  2457.            been able to address the entry variable and create a window suitable for
  2458.            the data type including the field type and size, title, key set and
  2459.            translation, range checking, error and help messages, and help windows.
  2460.            With this environment in your application along with the power and speed of
  2461.            QWIK and WNDW, your programs can match and even better professional
  2462.            programs.
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.  
  2469.  
  2470.  
  2471.  
  2472.  
  2473.  
  2474.  
  2475.  
  2476.  
  2477.  
  2478.            Chapter 5, Data Windows                                             Page 41
  2479.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2480.  
  2481.  
  2482.            6.  D A T A   E N T R Y
  2483.  
  2484.            Data Windows in the pull-down menus are not the only place where data is
  2485.            needed to be entered.  The work windows themselves may need several data
  2486.            entry fields as well.  PULL simply uses a subset of Data Windows to handle
  2487.            the job very easily.  In addition, a smart HiLite automatically knows the
  2488.            location of each field in the window.
  2489.  
  2490.  
  2491.            DATA ENTRY vs. DATA WINDOW
  2492.  
  2493.            Data Windows have both a data entry field and a window surrounding it.  In
  2494.            work windows, all that is needed is the data entry field.  So, to
  2495.            distinguish between data entry in the pull-down menus and the work windows,
  2496.            the Data Windows are only in the menus, while Data Entry will be considered
  2497.            in this document to be in the work windows.
  2498.  
  2499.  
  2500.            DATA ENTRY RECORD
  2501.  
  2502.            One Data Entry field has already been included in the work window.  Let's
  2503.            take a look at its record.  In PULLDATA, find GetDataEntryStats and search
  2504.            for "with TopEntry" to see the following code:
  2505.  
  2506.              GetDataEntry (ord(aIntegerDE));
  2507.              VarAddr     := @aInteger;
  2508.              TypeOfData  := Integers;
  2509.              Row         := 2;
  2510.              Col         := 11;
  2511.              Field       := 4;
  2512.              MaxField    := 3;
  2513.              CheckRangeProc := @VerifyAinteger;
  2514.            { MsgLineNum  := ord(DE_ML); }      { This is the default }
  2515.            { HelpWndwNum := ord(DataWndwHW); } { This is the default }
  2516.              SaveDataEntry;
  2517.  
  2518.            The record identifiers should look quite familiar because they are the same
  2519.            ones use in a Data Window record.  The only differences are the Get and
  2520.            Save procedures, because the record is of type DataEntryRec rather than
  2521.            DataWndwRec.  If you examine these type declarations in P55-VAR.INC, you
  2522.            will find there is a DataEntryRec inside of DataWndwRec.  So, Data Entry is
  2523.            truly a subset of Data Windows.
  2524.  
  2525.            Variable - The variable is aInteger which is a constant declared early in
  2526.            the file and is of type Integers.
  2527.  
  2528.            Row/Col - This time, a row and column is specified where the left column of
  2529.            the field is to appear in the work window.  These coordinates are window
  2530.            relative.
  2531.  
  2532.            Default Helps - Both the help message and help window are set to a default
  2533.            so your program can be up and running without being concerned about
  2534.            details.  Being in a different part of the pull-down menu environment, the
  2535.            DE_ML is different from DW_ML because the function of F2 is the opposite to
  2536.            either case.
  2537.  
  2538.  
  2539.            Chapter 6, Data Entry                                               Page 42
  2540.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2541.  
  2542.  
  2543.  
  2544.            Other Variables - All the other variables in the record should be familiar
  2545.            to you from the explanations in the previous section on Data Windows.  So,
  2546.            there is no need to repeat them here.
  2547.  
  2548.  
  2549.            ADDING ENTRIES
  2550.  
  2551.            Entry Record - We have already seen how to add entries with the fill-in-
  2552.            the-blank concept, so let's try adding another entry to the work window.
  2553.            Just after the aInteger record, add the following code:
  2554.  
  2555.              GetDataEntry (ord(aRealDE));
  2556.              VarAddr     := @aReal;
  2557.              TypeOfData  := Reals;
  2558.              Row         := 3;
  2559.              Col         := 11;
  2560.              Field       := 12;
  2561.              Decimals    := 2;
  2562.              SaveDataEntry;
  2563.  
  2564.            Decimal - This variable is just for reals to format the number of decimals
  2565.            for the output display.  If the value is negative, then no decimal is used.
  2566.  
  2567.            aReal - Be sure to set up a default value for aReal.  At the beginning of
  2568.            PULLDATA, add the constant aReal:
  2569.  
  2570.              ...
  2571.              aInteger: integer = 200;
  2572.              aReal:    real    = 4.56e7;
  2573.  
  2574.            aRealDE - Now append the data entry record name to the DataEntryNames list
  2575.            at the beginning of the file:
  2576.  
  2577.              DataEntryNames = (NoDE,aIntegerDE,aRealDE);
  2578.  
  2579.            Now run the code and see if it appears in the Work Window.  When it runs,
  2580.            the field does not appear.  Why?
  2581.  
  2582.  
  2583.            DISPLAYING FIELDS
  2584.  
  2585.            Work Window - The Work Window controls what is to appear inside the window
  2586.            and this code is in the file PULLWORK.PAS.  Note that PULLWORK uses
  2587.            PULLDATA.  Take a look at it and search for "case WorkWndwStep" and see:
  2588.  
  2589.              ...
  2590.              WWrite (2,2,'Integer:');
  2591.              DisplayFields (ord(aIntegerDE),ord(aIntegerDE));
  2592.              WorkWndwStep := 1;
  2593.              ...
  2594.  
  2595.            DisplayFields - This is the code that displayed the Integer field.  The
  2596.            DisplayFields procedure displays a sequence of fields in order of the list
  2597.            of DataEntryNames.  It is declared in the interface of PULL as:
  2598.  
  2599.  
  2600.            Chapter 6, Data Entry                                               Page 43
  2601.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2602.  
  2603.  
  2604.  
  2605.              procedure DisplayFields (First,Last: word);
  2606.  
  2607.            So, what it does is display each field starting with the record First and
  2608.            ending with Last.  Looking back in PULLWORK again, it displayed records
  2609.            both beginning and ending with aIntegerDE.  So, it never reached aRealDE.
  2610.            Let's modify the parameter to include aRealDE as follows:
  2611.  
  2612.              DisplayFields (ord(aIntegerDE),ord(aRealDE));
  2613.  
  2614.            Field Label - Running it, the aRealDE will be displayed this time.  But it
  2615.            doesn't have a label, so add one to the window with:
  2616.  
  2617.              ...
  2618.              WWrite (2,2,'Integer:');
  2619.              WWrite (3,2,'Real:');
  2620.              DisplayFields (ord(aIntegerDE),ord(aRealDE));
  2621.              ...
  2622.  
  2623.            Justification - aReal now appears on the screen with the field right
  2624.            justified.  By default, numbers are justified to the right and strings to
  2625.            the left.  To alter this, just include your setting in the Data Entry
  2626.            record.  Let's try left justifying aReal by adding the following code in
  2627.            PULLDATA:
  2628.  
  2629.              GetDataEntry (ord(aRealDE));
  2630.              ...
  2631.              Decimals    := 2;
  2632.              JustifyOutput := Left;           { Add this line. }
  2633.              SaveDataEntry;
  2634.  
  2635.            Everything appears correctly on the screen.  But when we try to move the
  2636.            HiLite, it just stays on the Integer field.  How can we make it select the
  2637.            other field?  Real easy - keep reading.
  2638.  
  2639.  
  2640.            SEQUENTIAL ENTRY
  2641.  
  2642.            With sequential entries of several fields, PULL gives you the advantage of
  2643.            using not just one movement with the HiLite, but both relative and
  2644.            sequential movement.
  2645.  
  2646.  
  2647.            EnterSeq - PULL makes sequential entry as natural as can be.  In PULLWORK,
  2648.            search for EnterSeq and see:
  2649.  
  2650.              EnterSeq (ord(aIntegerDE),ord(aIntegerDE),Start1);
  2651.  
  2652.            This procedure is also in the interface of PULL.PAS and is declared as:
  2653.  
  2654.              procedure EnterSeq (First,Last: word; VAR Start: word);
  2655.  
  2656.            EnterSeq allows you to enter a whole block of entries in the DataEntry
  2657.            array of records where First and Last are the first and last records in the
  2658.            block.  The aRealDE was not included in this block.  So let's modify the
  2659.  
  2660.  
  2661.            Chapter 6, Data Entry                                               Page 44
  2662.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2663.  
  2664.  
  2665.            code to:
  2666.  
  2667.              EnterSeq (ord(aIntegerDE),ord(aRealDE),Start1);
  2668.  
  2669.            Now run the code and find that the highlight can now move freely between
  2670.            the two fields.  That all there is to do!  PULL handles the rest, now.
  2671.  
  2672.            Start - Start is the record where the highlight is to begin.  At the bottom
  2673.            of the file, Start1 is initialized to aIntegerDE.  Or, Start1 could be made
  2674.            into a typed constant with a default value.  This lets EnterSeq remember
  2675.            where the HiLite is after using the menus.
  2676.  
  2677.            Smart HiLite Algorithms - Take a break from PULLSHEL and go back to
  2678.            PULLDEMO.  Run the program and take a look at the work window with several
  2679.            entries.  PULL has smart algorithms that know where all the fields are
  2680.            located on the screen.  The HiLite can be moved freely to select any field
  2681.            with the following keys:
  2682.  
  2683.              Keys                     Movement                   Type of Movement
  2684.              -----------------------  -------------------------  ----------------
  2685.              Left/Right Arrow         Left/Right                 Relative
  2686.              Up/Down Arrow            Up/Down nearest cursor     Relative
  2687.              Home / Ctrl Left  Arrow  First one on the row       Relative
  2688.              End  / Ctrl Right Arrow  Last one on the row        Relative
  2689.              PgUp / Ctrl Home         First in sequence          Sequential
  2690.              PgDn / Ctrl End          Last  in sequence          Sequential
  2691.              Tab / Shift Tab          Next/Previous in sequence  Sequential
  2692.  
  2693.            Relative Movement - PULL checks the block of entries to see where to move
  2694.            the HiLite relative to the current field.  If the field is already at its
  2695.            limit, say to the far left with the left arrow key, it does not wrap around
  2696.            to the far right.  When the HiLite is moved up or down, PULL looks for the
  2697.            field nearest the cursor, not the full width of the field, and also does
  2698.            not wrap.
  2699.  
  2700.            Sequential Movement - Primarily, the Tab key is used for sequential
  2701.            movement.  If you reach the end of the sequence, the next Tab will wrap
  2702.            back to the first.  What determines sequential movement?  It's the order of
  2703.            the DataEntryNames.  So, changing the sequence is as simple as reorganizing
  2704.            the names - no interlinks between fields are necessary!  Now you can insert
  2705.            a new field without fretting over links.
  2706.  
  2707.            Auto Tab - The value of sequential entry is the order in which you want to
  2708.            enter fields.  After entering one field, the program should be smart enough
  2709.            to go the next one.  With AutoTab set true, PULL will jump to the next
  2710.            field in sequence automatically after each entry.  Let's try it again on
  2711.            the PULLDEMO program.
  2712.  
  2713.              1. Get into the work window.
  2714.              2. Press PgUp to get to the "Byte" entry field.
  2715.              3. Enter any value in range and press RETURN.
  2716.              4. See that the HiLite is now on "Integer".
  2717.  
  2718.            To prove the point of relative and sequential movement, let's move one of
  2719.            the fields to a different location.  In PULLDATA, search for the data entry
  2720.  
  2721.  
  2722.            Chapter 6, Data Entry                                               Page 45
  2723.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2724.  
  2725.  
  2726.            record for aChar2DE, and change the location to:
  2727.  
  2728.              GetDataEntry (ord(aChar2DE));
  2729.              VarAddr     := @aChar2;
  2730.              TypeOfData  := Chars;
  2731.              Row         := 5;            { Change the row (was 15) }
  2732.              Col         := 5;            { Change the column (was 55) }
  2733.              ...
  2734.  
  2735.            Run PULLDEMO and see the field moved to (5,5).  Moving the up arrow as far
  2736.            as it will go, the HiLite will end up on aChar2DE.  But when you press Tab,
  2737.            the next field is String.  Now, suppose we want aChar2DE to be first in
  2738.            sequence.  How easy is it?  Look for DataEntryNames at the top of the file
  2739.            and see:
  2740.  
  2741.              DataEntryNames = (
  2742.                NoDE,aByte2DE,aWord2DE,aShortInt2DE,aInteger2DE,aLongInt2DE,aReal2DE,
  2743.                aHex2DE,aChar2DE,aString2DE,FileNameDE);
  2744.  
  2745.            There is a bunch of names here, but all we are interested in is moving
  2746.            aChar2DE.  Move the name to be right after NoDE.  But now we have changed
  2747.            the beginning name of the block from aByte2DE to aChar2DE.  So, go into
  2748.            PULLWORK and do a global search and replace of aByte2DE with aChar2DE.
  2749.            Three familiar lines will be changed.  Run the program now and see that
  2750.            PgUp will now move the HiLite to the top and a subsequent tab will move it
  2751.            to Byte.  This makes organizing your screen very easy.
  2752.  
  2753.            Setting AutoTab - In PULLDATA, search for AutoTab which is right at the
  2754.            beginning of the Data Entry records.  The current value is true.  If this
  2755.            value is set false, then the HiLite would stay in the same field after
  2756.            entry.
  2757.  
  2758.  
  2759.            EDIT MODE
  2760.  
  2761.            When the HiLite moves from field to field, it is in Select Mode.  But when
  2762.            your are editing a field, it is in Edit Mode.  What exactly makes it change
  2763.            from Select to Edit mode?
  2764.  
  2765.  
  2766.            Overwrite vs. Edit - To overwrite the contents, just start typing the new
  2767.            entry.  To edit the contents, the suggested key to use is the Return key.
  2768.            When pressed, the HiLite changes color and the cursor is set past the last
  2769.            character.
  2770.  
  2771.            Non-Extended Keys - In addition to the Return key, any non-extended key
  2772.            will work as well and will also apply that key to the field.  For example,
  2773.            while in select mode, if ^A is pressed, the HiLite would change into Edit
  2774.            mode and, in addition, the cursor would be moved to the first character.
  2775.  
  2776.            Invalid Characters - If the key pressed is not a member of the entry key
  2777.            set, it acts the same as return on the first key, but is otherwise ignored.
  2778.  
  2779.            Escape - To escape Edit mode and restore the original contents, just press
  2780.            ESC and the HiLite will return to Select Mode.  If ESC is pressed again,
  2781.  
  2782.  
  2783.            Chapter 6, Data Entry                                               Page 46
  2784.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2785.  
  2786.  
  2787.            the program would escape the entire sequence of entry and would return
  2788.            control to the WorkWindow procedure.
  2789.  
  2790.  
  2791.            FIELD ATTRIBUTES
  2792.  
  2793.            There are three attributes that can be modified for the Data Entry fields -
  2794.            the display, the edit, and the HiLite attributes.
  2795.  
  2796.  
  2797.            Default Attributes - Data Entry fields have default attributes for each
  2798.            record just like the Data Windows.  These variables are also set in
  2799.            SetDefaultColors and InitDataColors.
  2800.  
  2801.            SetDefaultColors - In PULLDATA, search for SetDefaultColors and see the
  2802.            following code:
  2803.  
  2804.              DataEntryIattr  := Yellow+MagentaBG;
  2805.              DataEntryOattr  := Black+LightGrayBG;
  2806.  
  2807.            InitDataColors - These variables in turn are assigned to the following
  2808.            record variables in DataEntry:
  2809.  
  2810.                                Record
  2811.              Default variable  Variable   Description
  2812.              ----------------  ---------  --------------------
  2813.              DataEntryIattr    Iattr      Attribute for Input
  2814.              DataEntryOattr    Oattr      Attribute for Output
  2815.  
  2816.            HiLite Bar - The HiLite attribute is set by the color on the data pad
  2817.            called DataPad.Hattr.  This variable is right next to AutoTab in PULLDATA.
  2818.            Rather than having both the cursor and the HiLite, the HiLite can be turned
  2819.            off by assigning Hattr the value of SameAttr.  Then each field will appear
  2820.            in its own display attribute.
  2821.  
  2822.  
  2823.            SINGLE ENTRY
  2824.  
  2825.            If you prefer to customize your own procedures, you can use the procedure
  2826.            Enter in lieu of EnterSeq.  The procedure is declared in PULL as:
  2827.  
  2828.              procedure Enter (RecNum: word);
  2829.  
  2830.            This accesses the same powerful editing features as EnterSeq, but only
  2831.            works on the one field indicated in the parameter.  It does not display the
  2832.            fields before or after editing which must be done with DisplayFields.
  2833.  
  2834.  
  2835.            SUMMARY
  2836.  
  2837.            You have just covered enough features to master data entry in the work
  2838.            windows or user windows.  You can enter the records, display and locate the
  2839.            fields, control the sequence of entry, and adjust the appearance with the
  2840.            justification and attributes.  You also learned how to direct PULL's built
  2841.            in HiLite bar for field selection.
  2842.  
  2843.  
  2844.            Chapter 6, Data Entry                                               Page 47
  2845.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2846.  
  2847.  
  2848.            7.  W O R K   W I N D O W S
  2849.  
  2850.            The bulk of your application needs to be displayed somewhere, and the Work
  2851.            Windows are used for this purpose.  In this section, you will discover how
  2852.            to integrate your work window procedures in a pull-down menu environment so
  2853.            the program can randomly access any procedure.  In addition, you can create
  2854.            a sophisticated multi-level window environment.
  2855.  
  2856.  
  2857.            MAKING STEPS
  2858.  
  2859.            In this section, you will find how to break down procedures into individual
  2860.            steps and still allow the flow of execution to cycle through the Key
  2861.            dispatcher.
  2862.  
  2863.  
  2864.            Requirements - When procedures are broken down into steps, your procedures
  2865.            can do most anything.  But each step must exit with two settings:
  2866.  
  2867.              1. Assignment made for the next WorkWndwStep.
  2868.              2. Assignment made for Key and ExtKey.
  2869.  
  2870.            Example - Let's do an example to understand the flow of execution.  Get the
  2871.            original files for PULLDEMO.PAS - PULLWORK and PULLDATA.  Now take a look
  2872.            at the last of PULLWORK and see:
  2873.  
  2874.              procedure WorkWndw;
  2875.              begin
  2876.                ...
  2877.                case WorkWndwStep of
  2878.                  0:  ShowFields;
  2879.                  1:  EditFields;
  2880.                end;
  2881.              end;
  2882.  
  2883.            With this construct, your work can be separated into different steps.  To
  2884.            add a new step, just insert one.  To demonstrate how to create a new step,
  2885.            let's separate the left and right columns of the data entry fields into two
  2886.            separate steps.  So, let's add step 2:
  2887.  
  2888.                ...
  2889.                  0:  ShowFields;
  2890.                  1:  EditFields;
  2891.                  2:  EditFields2;
  2892.                end;
  2893.  
  2894.            and change EditFields to:
  2895.  
  2896.              procedure EditFields;
  2897.              begin
  2898.                DisplayFields (ord(FileNameDE),ord(FileNameDE));
  2899.                EnterSeq (ord(aByte2DE),ord(aReal2DE),Start1);    { Change this line. }
  2900.                if Key=EscKey then                                { Add this line. }
  2901.                  WorkWndwStep := 2;                              { Add this line. }
  2902.              end;
  2903.  
  2904.  
  2905.            Chapter 7, Work Windows                                             Page 48
  2906.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2907.  
  2908.  
  2909.  
  2910.            This will isolate the sequence to the left column of fields.  And now add
  2911.            EditFields2:
  2912.  
  2913.              procedure EditFields2;
  2914.              begin
  2915.                DisplayFields (ord(FileNameDE),ord(FileNameDE));
  2916.                EnterSeq (ord(aHex2DE),ord(FileNameDE),Start2);
  2917.                if Key=EscKey then
  2918.                  WorkWndwStep := 1;
  2919.              end;
  2920.  
  2921.            Start2 has already been added for you.  Set the TP primary file to be
  2922.            PULLDEMO.PAS.  Now try the program and see that you can only access the
  2923.            left or right sequence of fields.  If you want to swap between the left and
  2924.            right columns, just press ESC.
  2925.  
  2926.            Flow of Execution - ESC has been assigned inside EnterSeq as the key that
  2927.            is used to exit the procedure.  This is called a gated exit.  Once it
  2928.            exits, it also exits WorkWndw and goes back into PULL to analyze the
  2929.            keystroke in a key dispatcher.  If no key combinations are used to access
  2930.            the menus, execution will return right back to WorkWndw and into the right
  2931.            step.  You can catch the execution flow, by testing for the Esc key right
  2932.            after EnterSeq.  If so, then change the step as we did in the example.
  2933.  
  2934.            Menu Access - Why even bother to test the key if ESC exits EnterSeq?  The
  2935.            Esc key is not the only key that would exit this procedure.  Any menu key
  2936.            like F10 will also exit the same way.  So, the "if" statement is needed to
  2937.            confirm the correct key before changing the step.
  2938.  
  2939.            Updating the Window - Did you notice that DisplayFields was used twice for
  2940.            just one field?  Any time you exit a menu and re-enter the window, there is
  2941.            a possibility that something may need to be updated.  And this time the
  2942.            File name field is a possibility because it was linked to the output of the
  2943.            file directory.  If you haven't had a chance, press Alt-D to get the
  2944.            directory and pick a file by pressing RETURN.  The selected file name will
  2945.            appear in the File name field.  The other link is that the file name data
  2946.            entry field also preselects the initial file name when the directory is
  2947.            pulled again.  But there are other alternatives than using DisplayFields
  2948.            twice.
  2949.  
  2950.            Changing Steps - This example was quite simple.  When step 1 was complete,
  2951.            WorkWndwStep was incremented to step 2.  When step 2 was done, it was
  2952.            cycled back to step 1.  It continues to stay in this loop until the program
  2953.            is terminated, or until some other procedure changes the step number.  In
  2954.            step 0, if we had failed to assign a new step at the end of the step, the
  2955.            program would have been locked in an infinite loop, because it never
  2956.            accesses any keyboard input.
  2957.  
  2958.  
  2959.            READING THE KEYBOARD
  2960.  
  2961.            In some steps, the program may need keyboard input while others do not.  In
  2962.            this section you will find out how to read the keyboard within each step.
  2963.  
  2964.  
  2965.  
  2966.            Chapter 7, Work Windows                                             Page 49
  2967.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  2968.  
  2969.  
  2970.            Output-Only Step - Step 0 in the example, is an output-only step that
  2971.            displays the fields in the window.  No keyboard input was required.  So, at
  2972.            the end of the step, we needed to emulate a keystroke of some kind to meet
  2973.            the Step requirements.  By setting Key to NullKey (#00), the key dispatcher
  2974.            and will bypass a call to the menus and ignore the key.  This guarantees
  2975.            that the flow of execution will return to back WorkWndw.  ExtKey should
  2976.            also be set properly if a valid combination is needed.  Some keys do not
  2977.            require it such as NullKey, EscKey, and RetKey.  See your reference book
  2978.            for more details.
  2979.  
  2980.            Input and Output Step - Most steps will require both input and output.
  2981.            Step 1 called EnterSeq which has a keyboard reading routine built in.  So,
  2982.            no keystroke emulation is needed.  However, the last line in the step still
  2983.            needs to check for a change of step.
  2984.  
  2985.            Custom Input - There will be several occasions where you will want to have
  2986.            your own procedures that read the key board.  If you have the source code,
  2987.            look at PULLDENT.INC for the construct of EnterSeq which looks like:
  2988.  
  2989.              repeat
  2990.                ...
  2991.                CheckForPullDown (ord(SeqML));
  2992.                ...
  2993.                CheckForPop;
  2994.              until (Key=EscKey) or Pop or PullDown;
  2995.  
  2996.            CheckForPullDown is a procedure available to you to read the key board.
  2997.            Its parameter, MsgLineNum, will show this message while the program pauses
  2998.            for entry.  A subroutine in CheckForPullDown is ReadKbd which can be used
  2999.            instead.  It just reads the keyboard and does not show a message.
  3000.  
  3001.            CheckForPop - This procedure is also available to you to check if any menu
  3002.            control flags have been set and regulates them.  If the flags indicate a
  3003.            pop it needed, then Pop will be set true.
  3004.  
  3005.            Gated Exit - Now you can see two more possible reasons that would cause the
  3006.            program to exit EnterSeq - Pop and PullDown.  These are the very same flags
  3007.            used for controlling the menus.  By gating the exit, the flow of execution
  3008.            is confined with the repeat/until construct until a control flag permits
  3009.            the exit.  Using these two flags allow EnterSeq to be used in either the
  3010.            Work Window or a User Window in the menus.  If the procedure is only going
  3011.            to be used in the Work Window, then Pop is not necessary.
  3012.  
  3013.            Non-Gated Exit - The step doesn't have to be gated at all.  You can use
  3014.            CheckForPullDown by itself if the flow of execution can continue through
  3015.            the dispatcher every time a key is pressed.  For EnterSeq, this would not
  3016.            work, because the HiLite would flash with each keystroke.  The next section
  3017.            shows an example where a non-gated Exit works perfectly fine.
  3018.  
  3019.            Idle Keyboard - Rather than just letting the program just sit there and
  3020.            wait for keyboard input, you could be letting the program do other
  3021.            background processing.  An indirect call from PULL inside ReadKbd
  3022.            continually runs the contents of the FAR procedure KbdIdle while no key is
  3023.            pressed.  Although KbdIdle is seen here in PULLWORK, it can be placed in
  3024.            any file, but it MUST be included somewhere, even if the procedure is
  3025.  
  3026.  
  3027.            Chapter 7, Work Windows                                             Page 50
  3028.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3029.  
  3030.  
  3031.            empty.  The variable AddKbdIdle declares its address.
  3032.  
  3033.  
  3034.            MULTI-LEVEL WINDOWS
  3035.  
  3036.            One work window may not be enough for your application and others may be
  3037.            needed.  The following example shows how to add a simple hidden Work
  3038.            Window.
  3039.  
  3040.            Making the Step - Add step 3 to WorkWindow:
  3041.  
  3042.                ...
  3043.                  2:  EditFields2;
  3044.                  3:  EditWorkWndw2;   { Add this line. }
  3045.                end;
  3046.  
  3047.            Now, create this editing step to just put ASCII keys into the window.  A
  3048.            non-gated procedure will work fine:
  3049.  
  3050.              procedure EditWorkWndw2;
  3051.              begin
  3052.                CheckForPullDown (ord(WorkML));
  3053.                if not ExtKey then
  3054.                  case Key of
  3055.                    #32..#126: write (Key);
  3056.                    RetKey:    writeln;
  3057.                    EscKey:    HideWorkWndw;
  3058.                  end;
  3059.              end;     { Non-gated exit }
  3060.  
  3061.  
  3062.            The key chosen to hide the window is ESC although any key could be assigned
  3063.            to do this.  But we also need to initialize the second work window to be
  3064.            available to the program.  So, add the following line to InitWorkWndws:
  3065.  
  3066.              procedure InitWorkWndws;
  3067.              begin
  3068.                ShowFields;
  3069.                MakeWorkWndw2;   { Add this line. }
  3070.                ...
  3071.              end;
  3072.  
  3073.            and then code the procedure to make a hidden window and place it just after
  3074.            the ShowFields procedure.  (The code is already there.  Just remove the
  3075.            braces for this example.)
  3076.  
  3077.              procedure MakeWorkWndw2;
  3078.              begin
  3079.                SetWindowModes (HiddenMode);
  3080.                MakeWindow ( 8,21,10,40,LightBlue+LightGrayBG,LightBlue+LightGrayBG,
  3081.                             DoubleBrdr,Window2);
  3082.                SetWindowModes (0);
  3083.                WriteToHidden (Window2);
  3084.                TitleWindow (Top,Left  ,SameAttr,'2');
  3085.                TitleWindow (Top,Center,SameAttr,' Press ESC to hide ');
  3086.  
  3087.  
  3088.            Chapter 7, Work Windows                                             Page 51
  3089.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3090.  
  3091.  
  3092.                TitleWindow (Top,Center,SameAttr,' Work Window 2 ');
  3093.                WWriteC (1,'Type in any input');
  3094.                WGotoRC (2,1);
  3095.                WriteToCRT;
  3096.              end;
  3097.  
  3098.            At the beginning of the file, let's also activate the multi-level work
  3099.            window code by placing the "$" code in front of the word "define" to look
  3100.            like:
  3101.  
  3102.              {$define MultiWorkWndws }
  3103.  
  3104.            This activates the AccessWorkWndw procedure which simply accesses the
  3105.            selected window set by TopWorkWndwName.  When TopWorkWndwName has changed,
  3106.            WorkWndwStep also needs to be reset.  In the procedure ResetWorkWndwStep,
  3107.            confirm that Window2 starts on the correct step:
  3108.  
  3109.              Window2:  WorkWndwStep := 3;
  3110.  
  3111.            Now we need some keys to get access to these windows.  Let Window1 and
  3112.            Window2 be assigned to the Alt-1 and Alt-2 keys.  To do this, go back to
  3113.            PULLSTAT.PAS and edit CheckGlobalKeys to the following:
  3114.  
  3115.                ...
  3116.                AltX:    SetQuit;
  3117.                Alt1:    SetWorkWndw (Window1);
  3118.                Alt2:    SetWorkWndw (Window2);
  3119.              else
  3120.              ...
  3121.  
  3122.            The constants for Alt1 and Alt2 have already been set for you.  SetWorkWndw
  3123.            is located just before CheckGlobalKeys and looks like:
  3124.  
  3125.              procedure SetWorkWndw (WN: WindowNames);
  3126.              begin
  3127.                PullDown        := false;
  3128.                PopToWorkWndw   := true;
  3129.                TopWorkWndwName := WN;
  3130.              end;
  3131.  
  3132.            This assigns a new Work Window name for the AccessWorkWndw procedure.  Now
  3133.            it is all set.  Give the program a run.  You will see that anytime you
  3134.            press Alt-1 or Alt-2, it immediately accesses that window even if you are
  3135.            in the menus!  And, when you get Window2, the contents are preserved.  If
  3136.            you were able to program this successfully, you have attained a highly
  3137.            sophisticated environment with little code.
  3138.  
  3139.  
  3140.            MANAGING WINDOWS
  3141.  
  3142.            We have just covered all the code necessary to have several work windows on
  3143.            the screen at once.  To randomly access any window, the Alt keys were
  3144.            assigned to a particular window number.  To hide a window, the Esc key was
  3145.            used and the contents were saved.
  3146.  
  3147.  
  3148.  
  3149.            Chapter 7, Work Windows                                             Page 52
  3150.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3151.  
  3152.  
  3153.            Should you decide to use temporary windows so that ESC would remove the
  3154.            window, just replace the two occurrences of HideWindow with RemoveWindow.
  3155.            Of course, you could make a combination of both.  You now have the tools
  3156.            for complete window management.
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.  
  3180.  
  3181.  
  3182.  
  3183.  
  3184.  
  3185.  
  3186.  
  3187.  
  3188.  
  3189.  
  3190.  
  3191.  
  3192.  
  3193.  
  3194.  
  3195.  
  3196.  
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.            Chapter 7, Work Windows                                             Page 53
  3211.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3212.  
  3213.  
  3214.            8.  U S E R   W I N D O W S
  3215.  
  3216.            While in the menus, you may have to create a window or a menu that differs
  3217.            from the ones in PULL.  This section will show you the pull-down directory
  3218.            included with the package and how to integrate any user window into the
  3219.            pull-down environment.
  3220.  
  3221.  
  3222.            PULL-DOWN DIRECTORY
  3223.  
  3224.            The pull-down directory unit has already been linked into the demo.  By
  3225.            now, you can probably figure out how the directory is accessed.  Looking in
  3226.            the FilesMenu, find the following code:
  3227.  
  3228.              Line[3]:='Directory';          LineMode[3]:=ToUserWndw;
  3229.                                             ProcPtr [3]:=@DoDir;
  3230.  
  3231.            To pull down a user window, the line mode is set to ToUserWndw which places
  3232.            a 3-bar symbol on that line.  Then, DoDir is the procedure that will access
  3233.            the directory and looks like:
  3234.  
  3235.              procedure DoDir;
  3236.              begin
  3237.                { Use (FileName,FileName) to initially Hilite a close match. }
  3238.                { Use (FileName,'') to start at default. }
  3239.                PullDirectory (FileName,FileName);
  3240.              end;
  3241.  
  3242.            PullDirectory handles every thing once inside the procedure.  A particular
  3243.            emphasis was made on end-user human factors in its development.
  3244.  
  3245.              . Single column - A single column, alphabetically sorted list is the
  3246.                easiest to visually scan quickly.  Multi-column lists such as the one
  3247.                provided in the TP5 environment require difficult zig-zag scanning.
  3248.  
  3249.              . Cursor key scanning - Cursor keys are the expected way to scan through
  3250.                the directory.  In addition, Home, ^Home, End, and ^End keys only move
  3251.                the HiLite while PgUp, ^PgUp, PgDn, and ^PgDn move only the page.
  3252.  
  3253.              . Letter key scanning - Any alpha-numeric key will scan for the first
  3254.                file name starting with the same first letter.  The page is moved and
  3255.                the cursor is centered as much as possible.
  3256.  
  3257.              . Lower-case text - Lower case text is more legible than the standard
  3258.                upper-case text provided by DOS.
  3259.  
  3260.              . Right justified extension - Visual searches for extensions are easier
  3261.                to read when aligned.  In addition, this also facilitates proper
  3262.                alphabetic sorting.
  3263.  
  3264.              . High speed sort - The sorting routine uses is a secondary-index quick
  3265.                sort which is the fastest kind for this application.  It is currently
  3266.                set at a limit of 250 file names are permitted, but it can be set to
  3267.                grow as much as your heap allows.
  3268.  
  3269.  
  3270.  
  3271.            Chapter 8, User Windows                                             Page 54
  3272.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3273.  
  3274.  
  3275.              . High speed scroll - The display is expected to be fast when scrolling
  3276.                and is.  Neither the HiLite nor the screen ever flicker.
  3277.  
  3278.              . Default HiLite - If a value file name is passed to the directory for
  3279.                the default other than '', the directory searches for a close match to
  3280.                HiLite.  In either case, the HiLite is centered as much as possible.
  3281.  
  3282.              . Picked file name - Pressing CR will replace the referenced file name
  3283.                passed to the directory.
  3284.  
  3285.  
  3286.            INTERFACE
  3287.  
  3288.            If you have the source code to PULLDIR.PAS, take a look at PullDirectory
  3289.            and see how the code interfaces the pull-down menus.  This is an excellent
  3290.            example of incorporating all the features to integrate with the menus:
  3291.  
  3292.              procedure PullDirectory; { (VAR NameToChange: FileNameStr;
  3293.                                              NameToHiLite: FileNameStr); }
  3294.              begin
  3295.                TurnArrows (On);                                         { 1 }
  3296.                with TopMenu do
  3297.                  CmdSeq := CmdSeq+CmdLtrs[HiLiteLine];                  { 2 }
  3298.                ShowDirMenu (NameToHiLite);                              { 3 }
  3299.                repeat
  3300.                  with DirectoryMenu do
  3301.                    begin
  3302.                      CheckForPullDown (DirectoryMenu.MsgLineNum);       { 4 }
  3303.                      if ExtKey then
  3304.                        begin
  3305.                          if HelpKeyPressed then
  3306.                            {$ifdef UseHelpWndwCode }
  3307.                            PullHelpWndw (HelpWndwNum)                   { 5 }
  3308.                            {$endif UseHelpWndwCode }
  3309.                          else ScanDirByCursor;
  3310.                        end
  3311.                      else
  3312.                        if Key<>RetKey then
  3313.                          ScanDirByLetter;
  3314.                      if (Key=RetKey) and (TotalFiles>0) then
  3315.                        begin
  3316.                          PopToWorkWndw := true;                         { 6 }
  3317.                          { ... }
  3318.                        end;
  3319.                      CheckForPop                                        { 7 }
  3320.                    end;  { with }
  3321.                until (Key=EscKey) or (Key=RetKey) or Pop;               { 8 }
  3322.                Key := NullKey;                                          { 9 }
  3323.                RemoveWindow;                                            { 10 }
  3324.                dec (CmdSeq[0]);                                         { 11 }
  3325.                TurnArrows (Off);                                        { 12 }
  3326.              end;
  3327.  
  3328.            Comments - Comments for the numbered lines follow.
  3329.  
  3330.  
  3331.  
  3332.            Chapter 8, User Windows                                             Page 55
  3333.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3334.  
  3335.  
  3336.              Line 1  - TurnArrows is a procedure that places arrow symbols on
  3337.                        the top menu to direct the user's attention to the new
  3338.                        menu.
  3339.              Line 2  - Append CmdSeq so that PULL can know how it got to this
  3340.                        menu.
  3341.              Line 3  - This procedure actually produces the window on the CRT
  3342.                        and it custom designed.
  3343.              Line 4  - CheckForPullDown monitors keyboard entry and displays a
  3344.                        message.
  3345.              Line 5  - You can include your custom help window here.
  3346.              Line 6  - Once the item was selected on the menu, this option
  3347.                        commands PULL to return to the top work window.  This is
  3348.                        optional.
  3349.              Line 7  - CheckForPop analyzes all the menu controls flags,
  3350.                        including PopToWorkWndw, to see if a request has been
  3351.                        made to pop out of the menu.  If so, Pop is set to true.
  3352.              Line 8  - The repeat/until construct provides a gated exit.
  3353.              Line 9  - Alter the value of Key so the next menu will ignore an
  3354.                        EscKey value.  ESC is meant to pop only one menu.  If the
  3355.                        key was not changed, the menus would continue to pop
  3356.                        until is was back into the work window.
  3357.              Line 10 - The exit has been confirmed and the window/menu needs to
  3358.                        be removed from the CRT.
  3359.              Line 11 - Adjust CmdSeq for one pop.
  3360.              Line 12 - Turn the arrows back off of the top menu.
  3361.  
  3362.            This same construct can be used for any user window/menu to be included
  3363.            with the pull-down menus.
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.  
  3378.  
  3379.  
  3380.  
  3381.  
  3382.  
  3383.  
  3384.  
  3385.  
  3386.  
  3387.  
  3388.  
  3389.  
  3390.  
  3391.  
  3392.  
  3393.            Chapter 8, User Windows                                             Page 56
  3394.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3395.  
  3396.  
  3397.            9.  C O N D I T I O N A L   C O M P I L A T I O N
  3398.  
  3399.            Many times your application may not need to use all of the features built
  3400.            into PULL.  Although most of the code is optimized out by the compiler,
  3401.            some of the code is nested and it would be helpful to eliminate some of
  3402.            that code.  This section will show you how easy it is to do this.
  3403.  
  3404.  
  3405.            DEFINE SYMBOLS
  3406.  
  3407.            Here is a complete list of the define symbols used in PULL:
  3408.  
  3409.              UseSubMenuCode   - to include submenus.
  3410.              UseHelpWndwCode  - to include help windows.
  3411.              UseDataEntryCode - to include data entry or data windows.
  3412.              UseMsgLineCode   - to include normal and error messages.
  3413.              MultiWorkWndws   - to include multi-level work windows.
  3414.  
  3415.            Location - You can find these directives defined on the first page of all
  3416.            *.PAS files.  Most files will not have every one of them, but only the ones
  3417.            that affect it.
  3418.  
  3419.            Definition - When you see the define directive, it will look like:
  3420.  
  3421.              {$define UseSubMenuCode }
  3422.  
  3423.            With the "$" in its place, UseSubMenuCode would be defined and would
  3424.            include all of the submenu code.  If you do not want the code, then
  3425.            undefine it by just removing the "$":
  3426.  
  3427.              { define UseSubMenuCode }
  3428.  
  3429.            Affected Files - Should you decide to undefine a symbol, you should
  3430.            undefine it in ALL affected files including PULL.  You can get away without
  3431.            changing PULL on all of them except UseMsgLineCode where you must change it
  3432.            in PULL as well.
  3433.  
  3434.  
  3435.            RECOMPILING
  3436.  
  3437.            Once you have changed all the needed directives, do a Make and the code
  3438.            will be ready for use.
  3439.  
  3440.  
  3441.  
  3442.  
  3443.  
  3444.  
  3445.  
  3446.  
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.            Chapter 9, Conditional Compilation                                  Page 57
  3455.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3456.  
  3457.  
  3458.            10.  T R O U B L E   S H O O T I N G
  3459.  
  3460.            PULL is a well thought out unit.  If you find that the program has not done
  3461.            what you expected, there may be something that you overlooked.  This
  3462.            section will try to help jog your memory as to what the problems may be.
  3463.  
  3464.  
  3465.            GOOF UNIT
  3466.  
  3467.            All programmers make mistakes, right?  So, what happens when you try to
  3468.            make more windows than there are records available?  Since WNDW and PULL
  3469.            are powerful tools and can even write in RAM, there is a good possibility
  3470.            that your mistake may not even show up on the screen.  How do you know if
  3471.            anything has gone wrong?  The GOOF unit was made especially for handling
  3472.            errors.
  3473.  
  3474.            Displaying Errors - When an error is found in your program, the ShowGoof
  3475.            procedure is called and the program is terminated.  The CRT will display an
  3476.            error message in a flashing window.  There are eight fatal errors that are
  3477.            listed in APPENDIX B in WNDWREF.DOC to identify problems before they
  3478.            happen.  Please refer to it for the error messages and their solutions.  If
  3479.            you do not have a copy of WNDW55.ARC, you can get one direct from the
  3480.            Eagle.
  3481.  
  3482.            Flexibility - ShowGoof is accessed indirectly with an indirect call.  This
  3483.            means that you can freely edit the GOOF unit without needing to recompile
  3484.            WNDW or PULL.  You can even edit it for use in your own applications.  The
  3485.            error message numbers 1-50 are reserved.  So, for your own applications, it
  3486.            is suggested that you start with number 51.  If you have thoroughly tested
  3487.            your program, some of the messages can be eliminated.
  3488.  
  3489.            Using GOOF - It is very important that GOOF be included in the USES list.
  3490.            You may find that it compiles without it, but if an error does occur, your
  3491.            system will surely crash.  Notice that GOOF is the last unit in the USES
  3492.            list in the main program.
  3493.  
  3494.  
  3495.            FAR ADDRESSES
  3496.  
  3497.            Because PULL uses several pointers for procedures and variables, it is
  3498.            quite possible to lock up your computer if these are not properly
  3499.            addressed.  A debugger is most helpful in these circumstances.  But if you
  3500.            do not have one, here is a check list of possible causes:
  3501.  
  3502.  
  3503.            Forcing FAR - The far pointers used by TranslateProc, CheckRangeProc, and
  3504.            ProcPtr must be calling FAR procedures.  All procedures that are not
  3505.            declared in the interface of a unit must be forced to FAR with the
  3506.            directive {$F+} when called by a pointer.
  3507.  
  3508.            Indirect Calls - PULL has several inline calls for indirect FAR calls
  3509.            outside of the calling unit.  The addresses for these units must be
  3510.            assigned in the destination unit with an Addr* variable and is usually done
  3511.            in the BEGIN/END for initialization.  Here is a list of those procedures
  3512.            and calling address variables:
  3513.  
  3514.  
  3515.            Chapter 10, Trouble Shooting                                        Page 58
  3516.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3517.  
  3518.  
  3519.  
  3520.               Procedure         Address Variable      Unit
  3521.               ----------------  --------------------  --------
  3522.               GetUserPullStats  AddrGetUserPullStats  PullStat
  3523.               GetOverrideStats  AddrGetOverrideStats  PullStat
  3524.               WorkWndw          AddrWorkWndw          PullWork
  3525.               CheckGlobalKeys   AddrCheckGlobalKeys   PullStat
  3526.               ShowGoof          AddrGoof              Goof
  3527.               KbdIdle           AddrKbdIdle           Any
  3528.  
  3529.            Using Units - Because of indirect calls, the compiler does not know that
  3530.            some units need to be linked.  PullStat, PullWork, and Goof are three units
  3531.            that MUST be in the USES list of the main program.
  3532.  
  3533.            KbdIdle - The far procedure KbdIdle must be used and can be located in any
  3534.            unit.  This procedure does background processing while the keyboard is
  3535.            idle.
  3536.  
  3537.            Data - The variable address and type of data in each data record must
  3538.            exactly match or risk possible data loss.  Strings lengths must not be
  3539.            longer than MaxField.
  3540.  
  3541.  
  3542.            MULTI-TASKING
  3543.  
  3544.            This demo has already been set to work in multi-tasking environments
  3545.            compatible to DESQview, TopView, and IBM 3270 PC Workstation.  It uses the
  3546.            multi-tasking video buffer (MTVB) whenever possible.  To always disable
  3547.            MTVB use, set PreferMultiTask to false in PULLSHEL.PAS.
  3548.  
  3549.            CUSTOMER SERVICE
  3550.  
  3551.            If you are still having problems, leave us a message or give us a call.
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.  
  3576.            Chapter 10, Trouble Shooting                                        Page 59
  3577.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3578.  
  3579.  
  3580.            A P P E N D I X   A :   O T H E R   P R O D U C T S
  3581.  
  3582.  
  3583.            Eagle Performance Software has developed identical products for both Turbo
  3584.            C and Turbo Pascal.  Our pledge is to provide you quality products with
  3585.            unparalleled performance and ease of use.
  3586.  
  3587.  
  3588.            QWIK
  3589.  
  3590.            QWIK - For direct screen video, QWIK is the highest performance screen
  3591.            writing tools available today for all text modes in any video
  3592.            configuration.  QWIK provides capabilities far beyond in the unit/library
  3593.            that comes with your compiler.   Here are some of the features:
  3594.  
  3595.              . Writes on all IBM compatible computers, displays and adapters
  3596.                including MDA, CGA, EGA, MCGA, VGA, 8514/A, Hercules and 3270
  3597.                PC.
  3598.              . Superior video detection routine.
  3599.              . Eliminates snow and flicker.
  3600.              . Writes directly to the screen in absolute rather than relative
  3601.                coordinates.
  3602.              . Writes in all text modes and column modes.
  3603.              . Writes on all video pages.
  3604.              . Writes on virtual screens in RAM.
  3605.              . Writes text and attribute, text only, or attribute only.
  3606.              . Reads strings, characters and attributes.
  3607.              . Uses End-Of-String (EOS) marker for quick string chaining.
  3608.              . Provides standardized cursor shapes for all adapters.
  3609.              . Enhanced cursor movement.
  3610.              . Compatible with DESQview and similar multitasking environments.
  3611.              . Over 650% faster than standard direct screen writing.
  3612.              . Only 2.7k bytes of code if all 43 utilities are used.
  3613.              . Writes direct to multi-tasking video buffers (MTVB).
  3614.              . Optimized by the compiler and drops unused code.
  3615.              . Used in all other Eagle products.
  3616.  
  3617.            Here are the product versions:
  3618.  
  3619.               File name    CIS name    Compiler  Release date
  3620.               -----------  ----------  --------  ------------
  3621.               QWIK55.ARC   QWIK55.ARC  TP4-5.5    08-24-89
  3622.               QWIKC21.ARC  QWKC21.ARC  TC2        07-06-89
  3623.  
  3624.  
  3625.            WNDW
  3626.  
  3627.            WNDW - For multi-level virtual windows, WNDW is the highest performance
  3628.            window utilities available today.  It offers very powerful utilities for
  3629.            full window control and management you probably never thought possible.
  3630.            They are simple and yet very powerful with high speed and tight code.  With
  3631.            WNDW, you can choose the absolute writing routines of QWIK, the window-
  3632.            relative writing routines of WNDW, and even customize your own.  Here are
  3633.            some of the features you will discover:
  3634.  
  3635.  
  3636.  
  3637.            Appendix A: Other Products                                          Page 60
  3638.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3639.  
  3640.  
  3641.            . Uses the powerful direct screen writing routines of QWIK.
  3642.            . Up to 254 fixed or virtual windows can be on the screen at one time.
  3643.            . Extremely high-speed virtual screens in RAM (up to 40 times faster).
  3644.            . Virtual windows are fully updated on screen, even if covered!
  3645.            . Virtual windows have virtual titles.
  3646.            . Fully supported hidden windows saved in RAM.
  3647.            . Fully supports all video pages.
  3648.            . Adjustable-rate moving, resizing, and scrolling.
  3649.            . All windows can be randomly accessed, not just stacked or tiled.
  3650.            . 28 window-relative writing routines.
  3651.            . 15 different border styles with shadow and zoom effects.
  3652.            . Full line drawing procedures.
  3653.            . Full cursor mode control for each window.
  3654.            . Writes in all text modes and column modes.
  3655.            . Writes direct to multi-tasking video buffers (MTVB).
  3656.            . Only 13k bytes of code if all 69 utilities are used.
  3657.            . Used in all other Eagle products.
  3658.  
  3659.            Here are the product versions:
  3660.  
  3661.               File name    CIS name    Compiler  Release date
  3662.               -----------  ----------  --------  ------------
  3663.               WNDW55.ARC   WNDW55.ARC  TP4-5.5    08-24-89
  3664.               WNDWC21.ARC  WNDC21.ARC  TC2        08-01-89
  3665.  
  3666.  
  3667.            PULL
  3668.  
  3669.            Here are the product versions:
  3670.  
  3671.               File name    CIS name    Compiler  Release date
  3672.               -----------  ----------  --------  ------------
  3673.               PULL55.ARC   PULL55.ARC  TP4-5.5    08-24-89
  3674.               PULLC21.ARC  PULC21.ARC  TC2        08-01-89
  3675.  
  3676.  
  3677.            ON-LINE SERVICES
  3678.  
  3679.            CompuServe - All updated files and later versions can be found on the
  3680.            CompuServe Borland Forums (GO BPROGA for TP and GO BPROGB for TC) or the
  3681.            IBM Programming Forum (GO IBMPRO).
  3682.  
  3683.  
  3684.            RELEASE DATES
  3685.  
  3686.            Please note that the release dates are only estimates.
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.            Appendix A: Other Products                                          Page 61
  3699.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3700.  
  3701.  
  3702.            A P P E N D I X   B :   R E V I S I O N   H I S T O R Y
  3703.  
  3704.            REVISIONS:
  3705.  
  3706.            Version 2.0 (01-12-88):
  3707.              . Converted to TP4 and incorporated QWIK40 and PULL40.
  3708.              . Added pull-down directory with path and mask.
  3709.              . Added global keys like Alt-F and Alt-X in PULLSTAT.PAS.
  3710.              . Eliminated PULLUSER.INC and instead allow access to user
  3711.                  windows direct through PullProc.Process.
  3712.              . Menu partitions now use Wndw.BrdrRec.
  3713.              . Added TypeOfDataTypes Word and LongInt.
  3714.              . Added "ClearScreen" option in InitPull.
  3715.              . Deleted i and j variables in PULL20.PAS.
  3716.              . Modified Pull.TempMsg; Deleted TempMsgArray.
  3717.              . Top menu record is available from TopMenuRecPtr^.
  3718.  
  3719.            Version 4.2 (01-03-89):
  3720.              . Incorporated QWIK42 and WNDW42.
  3721.              . Added excellent documentation.
  3722.              . Expanded the fill-in-the-blank concept.
  3723.              . Simplified work window data entry with sequential data entry
  3724.                routines.
  3725.              . Changed data windows to the slide-under configuration.
  3726.              . Added complete editing in data entry fields.
  3727.              . Added custom set control for data entry and deleted UserStrings.
  3728.              . Added key translation and range checking pointers.
  3729.              . Added multi-level window control.
  3730.              . Deleted PullProc.pas and the Process and Transfer procedures and
  3731.                replaced them with pointers.
  3732.              . Added automatic menu and line counting.
  3733.              . Simplified Menu Modes with execution pointers.
  3734.              . Changed menu records from global to dynamic data.
  3735.              . Improved submenu linking following the direction trend of the parent
  3736.                menu.
  3737.  
  3738.            Version 5.X (01-07-89):
  3739.              . Compiled PULL42 under TP5.  No other changes.
  3740.  
  3741.            Version 5.Xa (01-11-89):
  3742.              . Corrected right-arrow key problem in data entry (P5X-DATA.INC).
  3743.              . Improved cursor mode handling during dynamic updates.
  3744.  
  3745.            Version 5.Xb (03-04-89):
  3746.              . Incorporated QWIK5XA and WNDW5XB for multi-tasking.
  3747.              . Added new LineModeType of NoChoice for dynamic disabling of any line.
  3748.  
  3749.            Version 5.Xc (05-29-89):
  3750.              . Incorporated WNDW5XC.  No other changes.
  3751.  
  3752.            Version 5.5 (08-24-89):
  3753.              . Compiled PULL5XC under TP 5.5.  No other changes.
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.            Appendix B: Revision History                                        Page 62
  3760.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3761.  
  3762.  
  3763.            A P P E N D I X   C :   C R E D I T S
  3764.  
  3765.            Art Hill started some initial ideas on this with PullDown.arc
  3766.  
  3767.               Art Hill
  3768.               936 S. Kensington Ave.
  3769.               La Grange, IL 60525
  3770.               CIS 72307,3570
  3771.  
  3772.            Copyright (c) 1986-1989 by James H. LeMay for Eagle Performance Software.
  3773.            All Rights Reserved.  Protected by the United States Copyright Laws.
  3774.  
  3775.            Turbo Pascal is a trademark of Borland International.
  3776.            WordStar is a trademark of MicroPro International.
  3777.  
  3778.  
  3779.  
  3780.  
  3781.  
  3782.  
  3783.  
  3784.  
  3785.  
  3786.  
  3787.  
  3788.  
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.  
  3796.  
  3797.  
  3798.  
  3799.  
  3800.  
  3801.  
  3802.  
  3803.  
  3804.  
  3805.  
  3806.  
  3807.  
  3808.  
  3809.  
  3810.  
  3811.  
  3812.  
  3813.  
  3814.  
  3815.  
  3816.  
  3817.  
  3818.  
  3819.  
  3820.            Appendix C: Credits                                                 Page 63
  3821.            PULL Multi-level Pull-Down Menus                 User's Guide, Version 5.5
  3822.  
  3823.  
  3824.            A P P E N D I X   D :   G L O S S A R Y
  3825.  
  3826.            Command letter - A letter highlighted in a menu that executes that line.
  3827.            Command sequence - The sequence of command letters pressed to arrive at a
  3828.                            window or menu.
  3829.            Data entry    - Field for entering data into the application program in the
  3830.                            work windows or user windows.
  3831.            Data window   - Window for entering data into the application program from
  3832.                            the menus.
  3833.            Error message - A short message for data out of range.
  3834.            Field         - A highlighted area reserved for a data entry string to be
  3835.                            displayed.
  3836.            Flex field    - A field that allows more characters into the data entry
  3837.                            than what the field displays.
  3838.            Free field    - A field that allows a continuous string of characters to
  3839.                            expand in the field in any position.  This is in contrast
  3840.                            to formatted fields where each column is designated an
  3841.                            entry.
  3842.            Local key     - A key that only works within the menu or window.
  3843.            Gated exit    - A procedure that lets the flow of execution pass through
  3844.                            back to PULL's key dispatcher only on specific keystrokes.
  3845.            Global key    - A key that accesses a different part of the program at any
  3846.                            time.
  3847.            Help message  - A message appear on the message line for keyboard
  3848.                            instructions.
  3849.            Help window   - A window displayed by pressing F1 that provides context-
  3850.                            sensitive help.
  3851.            HiLited       - A highlighted bar pointed at in a menu.
  3852.            Level         - A window or menu where the program is operating.
  3853.            Line          - A row of text.
  3854.            Link          - A menu line showing a symbol (three-bar or dot) that pulls
  3855.                            another menu or window.  The symbol is also on the same
  3856.                            side where it is pulled.
  3857.            Main menu     - The first menu pulled from the Top Line menu.
  3858.            Menu          - A list of selectable lines.
  3859.            Message line  - The bottom row to display key helps or processing status.
  3860.            MTVB          - Multi-Tasking Video Buffer used in multi-tasking
  3861.                            environments.
  3862.            Pop           - removes menu and returns to the previous menu.
  3863.            PullDown      - pulls menus down to the previous level.
  3864.            Selection     - A line selected in a menu with a CR.
  3865.            Shell         - A bare bones program of pull-down menus to get you started
  3866.                            in your own application.
  3867.            Slide-under   - The configuration of data windows them to slide under the
  3868.                            HiLite if the field grows wider.
  3869.            Slide-up      - The configuration of submenus that allows them to slide
  3870.                            upward as the menu list grows.
  3871.            Status line   - A optional line reserved for status information pertinent
  3872.                            to your program.
  3873.            Submenu       - All subsequent menus pulled after a main menu.
  3874.            Top Line menu - The menu always shown (usually in row 1 or 2).
  3875.            Window        - Not a menu.
  3876.            Work window   - The window where the bulk of the application is shown.
  3877.  
  3878.  
  3879.  
  3880.  
  3881.            Appendix D: Glossary                                                Page 64
  3882.