home *** CD-ROM | disk | FTP | other *** search
/ Black Box 4 / BlackBox.cdr / batch / popup1_3.arj / POPUP.DOC < prev    next >
Text File  |  1991-01-10  |  15KB  |  404 lines
  1.  
  2.     POPUP.EXE  Batch File Menuing Utility.  Copyright Geoff Lane 1990
  3.  
  4.  
  5.  
  6.  1, System Requirements:
  7.     ~~~~~~~~~~~~~~~~~~~
  8.     1. IBM PC/XT or PC/AT or compatible with CGA or MDA display.
  9.  
  10.     2. Single or twin floppy disks with or without hard disk.
  11.  
  12.     3. The ANSI.SYS screen control driver must be installed.
  13.  
  14.        (to install ANSI.SYS place the file "ANSI.SYS" in the root
  15.        directory of your start-up disk and ensure that your
  16.        "CONFIG.SYS" file contains the line "DEVICE=ANSI.SYS")
  17.  
  18.  
  19.  2, Features:
  20.     ~~~~~~~~
  21.     1. POPUP.EXE is designed as a DOS external command for the
  22.        provision of menu systems from the batch language.
  23.  
  24.     2. The menus feature light bar and first character selection
  25.  
  26.     3. Menus may be nested as deeply as required and each menu
  27.        may contain up to 20 selections.
  28.  
  29.  
  30.  
  31.  3, File List
  32.     ~~~~~~~~~
  33.     You should have found the following files in the archive POPUP1-3.ZIP
  34.  
  35.     1. POPUP.EXE           The popup program
  36.     2. CURSORTO.EXE        An utility to place the cursor at any point on
  37.                            the screen and to display a message if required
  38.     3. POPUP.DOC           This documentation file
  39.     4. DEMO.BAT            A batch file to demonstrate the use of POPUP.EXE
  40.     5. DEMO.POP            A .POP configuration file for the main menu called
  41.                            by DEMO.BAT.
  42.  
  43.  4, Usage:
  44.     ~~~~~
  45.     POPUP.EXE is called from within a batch file either with all
  46.     the configuration information contained in the command line
  47.     entry or by passing the name of a configuration file to the
  48.     POPUP on the command line.
  49.  
  50.  
  51.     1. Calling with Configuration Data on the Command Line
  52.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  53.        POPUP is called in this mode by :
  54.  
  55.        POPUP Row Column HEADING Option_1 [Option_2 [Option...]]
  56.  
  57.        where Row and Column represent the location of the top,
  58.        left-hand corner of the menu box.
  59.  
  60.        1. NOTE Row 0 , Column 0 is the top left-hand corner of the
  61.           screen.
  62.  
  63.           HEADING represents the heading of your menu.
  64.  
  65.           Option_1 .. Option... are the choices available to the user.
  66.  
  67.           Note that spaces are used as delimeters in the command line
  68.           producing the menu. If you wish to include spaces in the
  69.           heading or any of the choices then the underscore should be
  70.           used. POPUP.EXE converts all underscores to spaces so that
  71.           "MAIN_MENU" would be converted to "MAIN MENU" by POPUP.EXE.
  72.  
  73.           So if you wished to call up a menu with HEADING = MAIN MENU,
  74.           positioned at Row 5, Column 20 and with choices :
  75.           Wordprocessing, Spreadsheets and Databases then the command
  76.           line producing this would be:
  77.  
  78.            POPUP 5 25 MAIN_MENU Wordprocessing Spreadsheets Databases
  79.  
  80.  
  81.  
  82.        2. Limitations:
  83.           ~~~~~~~~~~~
  84.           a. DOS only allows 127 characters in a command line so the
  85.              total length of your command line to call POPUP.EXE may
  86.              not exceed 127 characters. If you subtract the "POPUP Row
  87.              Column" part of the command line you will see that this
  88.              only allows 115 to 117 characters for your heading and
  89.              option list.
  90.  
  91.           b. Because allowing you to specify the background and
  92.              foreground colour would have taken a sizable chunk out of
  93.              the remaining 115 to 117 characters available I have
  94.              restricted the menu display to white on black. These
  95.              colours will also display properly on a mono display.
  96.  
  97.           c. POPUP.EXE produces the menu by sending ANSI control codes
  98.              to the screen. This means that the ANSI.SYS driver must
  99.              be installed. If it is not then the menu will display as
  100.              a heep of garbage but POPUP will still recognise your
  101.              keyboard input!
  102.  
  103.  
  104.  
  105.  
  106.     2. Calling with Configuration Data in a File
  107.        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  108.        1. You have the option of specifying a data file (ext .POP) to
  109.           configure the menu generated by POPUP.
  110.  
  111.           You just have to specify the filename (minus the extension)
  112.           as the argument on the command line.
  113.  
  114.  
  115.  
  116.  
  117.        2. SYNTAX
  118.           ~~~~~~
  119.                     POPUP <filename>
  120.  
  121.           so to call POPUP to display the menu detailed in EXAMPLE.POP
  122.           you would place the line:
  123.  
  124.                     POPUP EXAMPLE
  125.  
  126.           In your batch file.
  127.  
  128.  
  129.  
  130.        3. FORMAT FOR .POP FILE
  131.           ~~~~~~~~~~~~~~~~~~~~
  132.           The format for .POP files is shown below. The file "DEMO.POP"
  133.           is included and may be studied as an example.
  134.  
  135.           FORMAT
  136.           ~~~~~~
  137.           Row             {the row number of the top left corner}
  138.           Column          {the column number of the top left corner}
  139.           Foreground Colour
  140.           Background Colour
  141.           Menu Heading
  142.           Option 1
  143.           Option 2
  144.               "
  145.               "
  146.           Option n        {where n can be up to 20}
  147.  
  148.  
  149.           a. NOTE:
  150.              Leading and trailing spaces in the fields
  151.              {Row,Column,Foreground Colour,Background Colour} will
  152.              result in POPUP throwing a wobbly and telling you that
  153.              you have an input error.
  154.  
  155.              Leading and trailing spaces in the Menu Heading and
  156.              Option fields are permitted and these fields may be up to
  157.              64 characters long. If you give a line with greater than
  158.              64 characters then POPUP will truncate them to 64 chars.
  159.  
  160.              The colours may be any combination from the set
  161.              {black,blue,red,green,yellow,magenta,cyan,white} and
  162.              upper, lower or mixed cases are permitted.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  5, Constructing Batch Files to use POPUP.EXE
  169.     ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  170.     1. Below is the listing for DEMO.BAT which was written to use
  171.        POPUP.EXE. This file was written to demonstrate the nesting
  172.        of menus and to give you something of a reference to model
  173.        your menus on.
  174.  
  175.        Study the listing of DEMO.BAT to see how it has been used.
  176.        Note that braces "{" and "}" have been used to enclose
  177.        comments and that POPUP converts all underscores to spaces.
  178.  
  179.        NOTE That the Main Menu has been called using the
  180.        configuration file method of callimg and that all the
  181.        submenus have been called with all the data on the command
  182.        line.
  183.  
  184.  
  185.     2. Listing for DEMO.BAT
  186.        ~~~~~~~~~~~~~~~~~~~~
  187.        @echo off                     { turn off screen echo }
  188.        : start                       { label "start"}
  189.        cls                           { clear the screen }
  190.        popup demo                    { call POPUP.EXE with configuration }
  191.                                      { data in file DEMO.POP             }
  192.        if errorlevel 255 goto exit   { if ESC pressed goto label "exit" }
  193.        if errorlevel 5 goto exit     { if option 5 taken goto "exit" }
  194.        if errorlevel 4 goto 4        { if option 4 taken goto label "4" }
  195.        if errorlevel 3 goto 3        { if option 3 taken goto "3" }
  196.        if errorlevel 2 goto 2        { if option 2 taken goto "2" }
  197.        if errorlevel 1 goto 1        { if option 1 taken goto "1" }
  198.  
  199.        : 1                           {label "1" }
  200.        popup 7 15 WORD_PROCESSING Scrunge_Write Goof_Edit Zork_Word MyText
  201.        Main_Menu
  202.                                      { call POPUP.EXE with configuration }
  203.                                      { data on command line              }
  204.        if errorlevel 255 goto start
  205.        if errorlevel 5 goto start    { goto label as indicated by }
  206.        if errorlevel 4 goto mytext   { DOS Errorlevel returned by }
  207.        if errorlevel 3 goto zork     { POPUP.EXE                  }
  208.        if errorlevel 2 goto goof
  209.        if errorlevel 1 goto scrunge
  210.  
  211.        : scrunge
  212.        cursorto 23 5 ***** Scrunge Write now running ! *****
  213.        goto 1                        { call CURSORTO.EXE to display }
  214.                                      { a message on the screen      }
  215.                                      { NOTE : any DOS application   }
  216.                                      { could have been called here  }
  217.  
  218.        : goof
  219.        cursorto 23 5 ******* Goof Edit now running ! *******
  220.        goto 1
  221.  
  222.        : zork
  223.        cursorto 23 5 ******* Zork Word now running ! *******
  224.        goto 1
  225.  
  226.        : mytext
  227.        cursorto 23 5 ******** MyText now running ! *********
  228.        goto 1
  229.  
  230.  
  231.  
  232.        : 2
  233.        popup 8 30 DATABASES ScrungeBase File_Card_XI WhereIsIt Main_Menu
  234.        if errorlevel 255 goto start
  235.        if errorlevel 4 goto start
  236.        if errorlevel 3 goto whereisit
  237.        if errorlevel 2 goto filecard
  238.        if errorlevel 1 goto scrungeb
  239.  
  240.        : scrungeb
  241.        cursorto 23 15 ******** Scrunge Base now running ! ********
  242.        goto 2
  243.  
  244.        : filecard
  245.        cursorto 23 15 ******** File Card XI now running ! ********
  246.        goto 2
  247.  
  248.        : whereisit
  249.        cursorto 23 15 ********* WhereIsIt now running ! **********
  250.        goto 2
  251.  
  252.        : 3
  253.        popup 3 12 SPREADSHEETS GripeCalc Sheet_7_6_5 Main_Menu
  254.        if errorlevel 255 goto start
  255.        if errorlevel 3 goto start
  256.        if errorlevel 2 goto 765
  257.        if errorlevel 1 goto Gripe
  258.  
  259.        : Gripe
  260.        cursorto 23 25 ******* GripeCalc now running *******
  261.        goto 3
  262.  
  263.        : 765
  264.        cursorto 23 25 ****** Sheet 7 6 5 now running ******
  265.        goto 3
  266.  
  267.  
  268.        : 4
  269.        popup 10 20 GRAPHICS Draw_It Scrunge_Draw Paint_Bucket Main_Menu
  270.        if errorlevel 255 goto start
  271.        if errorlevel 4 goto start
  272.        if errorlevel 3 goto bucket
  273.        if errorlevel 2 goto scrunged
  274.        if errorlevel 1 goto drawit
  275.  
  276.        : drawit
  277.        cursorto 23 35 ******** Draw It now running ! ********
  278.        goto 4
  279.  
  280.        : scrunged
  281.        cursorto 23 35 ****** Scrunge Draw now running !******
  282.        goto 4
  283.  
  284.        : bucket
  285.        cursorto 23 35 ****** Paint Bucket now running !******
  286.        goto 4
  287.  
  288.        : exit
  289.        exit
  290.  
  291.  
  292.     3. Hints for using POPUP.EXE
  293.        ~~~~~~~~~~~~~~~~~~~~~~~~~
  294.        1. If you have a single (or twin) floppy machine and have a RAM
  295.           disk installed then you will find the batch file and
  296.           POPUP.EXE will execute quicker if you copy your menu batch
  297.           file and POPUP.EXE to the RAM disk and run the batch file
  298.           from there.
  299.  
  300.        2. Note that POPUP returns a DOS errorlevel to indicate which
  301.           option has been chosen. The errorlevel corresponds to the
  302.           position of the choice in the command line list of options,
  303.           so choosing the first option returns an errorlevel of 1, the
  304.           second an errorlevel of 2 and so on.
  305.  
  306.        3. Note that "ESC" is allways an allowable option and will
  307.           return an errorlevel of 255. This is useful because can
  308.           write your batch file in such a way that successive presses
  309.           of the ESC key will take the user back to the main menu. You
  310.           may write your batch file so that the user will be returned
  311.           to the main menu when the ESC key is pressed at any menu or
  312.           you may write your batch file so that pressing the ESC key
  313.           will bring up any menu (including the current one).
  314.  
  315.        4. Note that "if errorlevel x" really means "if the DOS
  316.           errorlevel is greater than or equal to x" so if the DOS
  317.           errorlevel is set to 5 then "errorlevel=x" is true for
  318.           x=1,x=2,x=3,x=4 and x=5. This means that the list of "if
  319.           errorlevel"'s in the batch file must be in decending order.
  320.  
  321.  
  322.  
  323.  
  324.  6, CURSORTO.EXE
  325.     ~~~~~~~~~~~~
  326.     CURSORTO.EXE was written as a "quick hack" to neaten up the screen
  327.     display from DEMO.BAT and to provide a DOS program to call from
  328.     DEMO.BAT.
  329.  
  330.     You are, of course, more than welcome to use it if you find it usefull.
  331.  
  332.     The usage for CURSORTO.EXE is :=
  333.  
  334.     CURSORTO <row> <column> [<print string>]
  335.  
  336.     Where <row> is a number representing the row and <column> is a number
  337.     representing the column that you wish to position the cursor on,
  338.     <print string> is the message (if any) you wish displayed at the new
  339.     cursor position.
  340.  
  341.     Please note that CURSORTO uses ANSI screen codes and, therefore, cannot
  342.     be used unless ANSI.SYS is installed.
  343.  
  344.  
  345.  7,                         IMPORTANT NOTICE
  346.                             ~~~~~~~~~~~~~~~~
  347.     1. You may use POPUP.EXE on any number of machines and may pass
  348.        copies on to friends and associates providing that no charge
  349.        is made for this and that copies of this documentation file,
  350.        CURSORTO.EXE, DEMO.POP and DEMO.BAT are passed together with
  351.        the copy of POPUP.EXE.
  352.  
  353.     2. POPUP.EXE and the accompanying files are not guaranteed
  354.        suitable for any purpose and are not guaranteed to be error
  355.        free. The author accepts no liability whatsoever for any
  356.        damage to machine(s) or data caused by the use of POPUP.EXE
  357.        or any of the accompanying files.
  358.  
  359.  
  360.  
  361.  8, REVISION HISTORY
  362.     ~~~~~~~~~~~~~~~~
  363.     1. Version 0.0          May 1990
  364.        Written as a small utility for myself and a couple of
  365.        friends.
  366.  
  367.     2. Version 1.0          September 1990
  368.        First character selection added. First publication.
  369.  
  370.     3. Version 1.1          September 1990
  371.        Bug fixed allowing the "Input Error" message to be displayed
  372.        for all possible errors of usage (That I'm aware of,
  373.        anyway!).
  374.  
  375.     4. Version 1.2          October 1990
  376.        Bug fixes If more that 10 options were entered then an error
  377.        message would be generated. POPUP now allows up to 20
  378.        selections (as promised in the instructions!) and now places
  379.        up to the first 20 choices in the menu. (The remainder are
  380.        lost).
  381.  
  382.     5. Version 1.3          December 1990
  383.        Ability to read menu configuration data from .POP file added
  384.        Colours supported via .POP file.
  385.  
  386.  
  387.  9, Contacting the Author
  388.     ~~~~~~~~~~~~~~~~~~~~~
  389.     If you wish to contact me about POPUP then I regularly use
  390.     the following UK BBSs and you are most welcome to leave a
  391.     message to me (Geoff Lane) there.
  392.  
  393.  
  394.         PHACS BBS
  395.         Plymouth (0752) 361291  N-8-1
  396.         FidoNet 2:255/28.0
  397.  
  398.  
  399.         TRANSWORLD BBS
  400.         Bristol (0272) 248447 / 248477   N-8-1
  401.  
  402.  
  403.  
  404.