home *** CD-ROM | disk | FTP | other *** search
/ Boston 2 / boston-2.iso / DOS / PROGRAM / BASIC / MENULIBR / EZWINDO.DOC < prev    next >
Text File  |  1993-12-01  |  20KB  |  394 lines
  1.  
  2.  
  3. ╔═══▒▒▒▒▒▒▒▒▒▒▒▒ Welcome to ▒▒▒▒▒▒▒▒▒▒▒▒▒════╗
  4. ║                                            ║
  5. ║    ┌──────────────────────────────────┐    ║▒▒
  6. ║    │ EZ-WINDOWS Pulldown Menu System  │    ║▒▒
  7. ║    └──────────────────────────────────┘    ║▒▒
  8. ║               Version 3.0                  ║▒▒
  9. ║                                            ║▒▒
  10. ║ A complete mouseable Pulldown Menu System  ║▒▒
  11. ║                                            ║▒▒
  12. ║                    ┌───────────────────────╨──────────────────┐
  13. ╚░░░░░░░▒░░░░░░░░░░░░│                                          │  
  14.    ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│                  For...                  │▒▒
  15.                      │                                          │▒▒
  16.                      │   Microsoft QuickBASIC 4.5               │▒▒
  17.                      │                                          │▒▒
  18.                      │   Microsoft Professional Development     │▒▒
  19.       ▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄│   System 7.0                             │▒▒
  20.       █              │                                          │▒▒
  21.       █              └──────────────────────────────────────────┘▒▒
  22.       █                 ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  23.       █  StrongSoft Engineering             █▒▒
  24.       █                                     █▒▒
  25.       █  3155 SW 178th Ave                  █▒▒
  26.       █  Aloha, OR 97006                    █▒▒
  27.       █  (503) 649-7251                     █▒▒
  28.       █                                     █▒▒
  29.       █  Documentation written and prepared █▒▒
  30.       █  by John C. Strong                  █▒▒
  31.       █                                     █▒▒
  32.       █                                     █▒▒ 
  33.       █▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄█▒▒
  34.          ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒
  35.  
  36.  
  37. ═══════════════════════════════════════════════════════════════════════════════
  38.  
  39. A few customer comments --
  40.  
  41.         "Terrific, a beautiful piece of programming!" - Duiven, Holland
  42.  
  43.     "I am very impressed with EZ-WINDOWS.  It is exactly what
  44.      I was looking for..."   -   Ontario, Canada
  45.  
  46.     "It's incredible, I just love your routines to death...I'm going
  47.          to impress the hell out of those smart 'C' programmers..."
  48.          - Houston, Texas
  49.  
  50. ═══════════════════════════════════════════════════════════════════════════════
  51.  
  52. OVERVIEW
  53.  
  54.      This routine is intended to allow a programmer to present the user
  55. with options in an organized and esthetic way.  The PullDown Menu System was
  56. indeed modeled after the very pulldown menu used in the QuickBASIC 4.x
  57. environment.  
  58.  
  59.      I wrote this routine out of frustration, actually.  I didn't want to
  60. take the time to write a pulldown menu routine, yet none of the commercially
  61. available libraries offered the options that I needed.  So I just sat down
  62. one day and wrote it (over several days), and here it is.
  63.  
  64.      The Pulldown Menu System is very easy to integrate in a QB program,
  65. yet offers all the options someone might expect in a commercial software
  66. package.  To use this routine in a program, all that is required is a few
  67. arrays containing formatting information for the pulldown menu and an array
  68. containing the actual text used.  Then a simple CALL statement will take care
  69. of the rest!  Don't worry -- loading the arrays required for the routine is
  70. very straightforward and uncomplicated, and the results are definitely worth
  71. it!
  72.  
  73.      The advantages of using this routine are both numerous and obvious, but
  74. there is one disadvantage:  the code size is rather large.  But the programs
  75. that need such a pulldown menu routine are the ones that need to present a
  76. multitude of options to the user -- such a program will naturally be large
  77. anyway, so the relative code size of the Pulldown Menu System shouldn't make
  78. a big difference.
  79.  
  80.  
  81. REQUIREMENTS
  82.  
  83.      The Pulldown Menu System requires QuickBASIC 4.5 compiler.  It will also
  84. work with QB40, but you'll need to purchase & recompile the source code in
  85. QB40.  I think the better investment would be to buy QB45!  But I don't
  86. know if it will work with versions earlier than 4.0.  I believe earlier
  87. versions of QuickBASIC modify the stack a bit differently when passing
  88. parameters to assembler routines, which would definitely cause problems.  So
  89. if you don't have version 4.0 or later, you would be doing yourself a great
  90. favor by upgrading if for no other reason than to enjoy the benefits of a
  91. superior programming environment provided by QB45 or PDS 7.0.
  92.  
  93.      You can use this routine inside the QB environment or in a compiled
  94. .EXE file.  Two Quick Libraries are provided for program development inside
  95. QB and two libraries are provided for compiled programs.    
  96.  
  97.  
  98. USING THE PULLDOWN MENU SYSTEM
  99.  
  100.     Using this routine requires the dimensioning and loading of several
  101. arrays and the actual call to the routine.  When calling the routine, several
  102. conventions must be observed:
  103.  
  104.      1)    All non-string variable arguments must be the integer type,
  105.            denoted by the percent sign %, i.e., ITEMSLCT%.  Alternativ-
  106.            ely, the DEFINT statement can be used at the beginning of
  107.            your program which will take care of this automatically.  You
  108.            can also pass literals instead of integer variables, but only
  109.            for arguments that are not modified by the routine.  The best
  110.            thing to do is just pass variables, which requires less stack
  111.            space than literals.
  112.  
  113.      2)    The arguments passed must be in proper order or the routine
  114.            will not work, possibly locking up your system.
  115.  
  116.      3)    All arguments must be present or the routine will not work,
  117.            possibly locking up your system.
  118.  
  119.  
  120. SPECIFYING COLORS AS ATTRIBUTES
  121.  
  122.           The Pulldown Menu System requires that colors be passed
  123.      as attributes instead of foreground and background colors.  This
  124.      not only contributes to consistency between the routines internal
  125.      to the library but also reduces the number of arguments needing to
  126.      be passed.
  127.  
  128.           So what is an attribute?  An attribute is a single byte,
  129.      containing a number between 0 and 255, that tells DOS 
  130.      what foreground and background color to use.  Every character
  131.      on the screen has its own attribute byte in addition to the
  132.      character byte, and the attribute and character byte sit together
  133.      in video memory.  This is why it is fast and efficient to use
  134.      attributes.
  135.  
  136.           An attribute is the background color, multiplied by sixteen,
  137.      plus the foreground color.  In hexadecimal, the background is the
  138.      high nibble and the foreground is the low nibble.  To simplify 
  139.      things, here is a table that yields the attribute for a given
  140.      background color and foreground color.  Note that background colors
  141.      go from black to white.  You can use higher numbered colors
  142.      for a background but the text will be flashing.
  143.  
  144.                                    BACKGROUND COLOR   
  145.                                     
  146.                   black  blue  green   cyan   red  magenta  brown  white
  147.                     0      1      2      3      4      5      6      7
  148.                  |-----|------|------|------|------|------|------|------| 
  149.      black     0 |  0  |  16  |  32  |  48  |  64  |  80  |  96  |  112 |
  150.                  |-----|------|------|------|------|------|------|------|
  151.      blue      1 |  1  |  17  |  33  |  49  |  65  |  81  |  97  |  113 |
  152.                  |-----|------|------|------|------|------|------|------|
  153.      green     2 |  2  |  18  |  34  |  50  |  66  |  82  |  98  |  114 |
  154.  F               |-----|------|------|------|------|------|------|------|
  155.  O   cyan      3 |  3  |  19  |  35  |  51  |  67  |  83  |  99  |  115 |
  156.  R               |-----|------|------|------|------|------|------|------|
  157.  E   red       4 |  4  |  20  |  36  |  52  |  68  |  84  |  100 |  116 |
  158.  G               |-----|------|------|------|------|------|------|------|
  159.  R   magenta   5 |  5  |  21  |  37  |  53  |  69  |  85  |  101 |  117 |
  160.  O               |-----|------|------|------|------|------|------|------|
  161.  U   brown     6 |  6  |  22  |  38  |  54  |  70  |  86  |  102 |  118 |
  162.  N               |-----|------|------|------|------|------|------|------|
  163.  D   white     7 |  7  |  23  |  39  |  55  |  71  |  87  |  103 |  119 |
  164.                  |-----|------|------|------|------|------|------|------|
  165.  C   gray      8 |  8  |  24  |  40  |  56  |  72  |  88  |  104 |  120 |
  166.  O               |-----|------|------|------|------|------|------|------|
  167.  L   lblue     9 |  9  |  25  |  41  |  57  |  73  |  89  |  105 |  121 |
  168.  O               |-----|------|------|------|------|------|------|------|
  169.  R   lgreen   10 | 10  |  26  |  42  |  58  |  74  |  90  |  106 |  122 |
  170.                  |-----|------|------|------|------|------|------|------|
  171.      lcyan    11 | 11  |  27  |  43  |  59  |  75  |  91  |  107 |  123 |
  172.                  |-----|------|------|------|------|------|------|------|
  173.      lred     12 | 12  |  28  |  44  |  60  |  76  |  92  |  108 |  124 |
  174.                  |-----|------|------|------|------|------|------|------|
  175.      lmagenta 13 | 13  |  29  |  45  |  61  |  77  |  93  |  109 |  125 |
  176.                  |-----|------|------|------|------|------|------|------|
  177.      yellow   14 | 14  |  30  |  46  |  62  |  78  |  94  |  110 |  126 |
  178.                  |-----|------|------|------|------|------|------|------|
  179.      bwhite   15 | 15  |  31  |  47  |  63  |  79  |  95  |  111 |  127 |
  180.                  |-----|------|------|------|------|------|------|------|
  181.  
  182.  
  183.  
  184. CALLING THE ROUTINE
  185.  
  186.      This is the required format for calling this routine:
  187.  
  188.  
  189.      CALL PULLDOWN(MENUBAR$,MenuRow%,MenuCol%,Menuattr%,Hotattr%,
  190.                    HiBarattr%,NVattr%,HiPos1%(),HiPos2%(),
  191.                    MaxSize%(),MaxItems%(),item$(),valid%(),toggle%(),ms%,
  192.                    Clearafter%,Seed%,SoundOn%,MenuSlct%,ItemSlct%)
  193.  
  194.  
  195.      Arguments:     MENUBAR$ - A string variable holding each pulldown menu
  196.                                name.  The number of menus is determined by
  197.                                the number of names is this string, which
  198.                                must be separated by at least one space on
  199.                                each side.  A space character must be the last
  200.                                character in the string.
  201.  
  202.                     MenuRow% - The row on which the menu bar will be 
  203.                                displayed.
  204.  
  205.                     MenuCol% - The column of the leftmost character in the
  206.                                menu bar.  For a full length menu bar, this
  207.                                would be set to one (1).
  208.  
  209.                    Menuattr% - The color attribute of the menubar and menus
  210.  
  211.                     Hotattr% - The color attribute of the "hot" letters
  212.  
  213.                      Hiattr% - The color attribute of the text selected by
  214.                                the highlight bar.
  215.  
  216.                      NVattr% - The color attribute of the "grayed out"
  217.                                non-valid selections. 
  218.  
  219.                    HiPos1%() - The integer array, dimensioned to the number of
  220.                                menus, holding the position of the 'hot'
  221.                                letter in each menu name in the MENUBAR$
  222.                                variable.  These letters will be highlighted
  223.                                with the color specified in the HiliteFG%
  224.                                variable.
  225.  
  226.                    HiPos2%() - A 2-dimensional integer array holding the 
  227.                                position of the 'hot' letter in each menu item
  228.                                for each menu. It's first dimension is the
  229.                                number of the menu, the second is the 
  230.                                number of the selection in the menu.  
  231.                                Dimension it for the number of menus and the 
  232.                                number of items in the largest menu.  For
  233.                                example,
  234.                                     DIM HiPos2%(menu%,slct%)
  235.  
  236.                   MaxSize%() - An integer array holding the length of the
  237.                                longest item in each menu.
  238.  
  239.                  MaxItems%() - An integer array holding the number of items in
  240.                                each menu.
  241.  
  242.                      Item$() - A 2-dimensional array holding the items for
  243.                                selection for each menu.  It is dimensioned
  244.                                like HiPos2%(),
  245.                                     DIM Item$(menu%,slct%)
  246.  
  247.                     Valid%() - A 2-dimensional flag array that determines if
  248.                                an item is valid for selection or not.  A value
  249.                                of 1 is valid; 0 means not valid, and the item
  250.                                is grayed-out.  It is dimensioned like
  251.                                HiPos2%().
  252.  
  253.                    Toggle%() - A 2-dimension flag array that determines the 
  254.                                toggling status of each item in each menu.  
  255.                                
  256.                                    2   -   exclusive toggle, on
  257.                                    1   -   inclusive toggle, on
  258.                                    0   -   no toggling
  259.                                   -1   -   inclusive toggle, off
  260.                                   -2   -   exclusive toggle, off
  261.  
  262.                                If toggling is used in a menu, it must all be
  263.                                of one type, either all exclusive or all
  264.                                inclusive.  Otherwise, it won't work properly.
  265.                                Toggle%() is dimensioned like HiPos2%().
  266.  
  267.                          ms% - Flag to indicate mouse support.  If ms%=0, the
  268.                                routine ignores the mouse if one is present.
  269.                                ms%=1 tells the routine to use the mouse.
  270.  
  271.                  ClearAfter% - If ClearAfter%=1, the menu will be erased after
  272.                                a selection is made.  A value of zero will 
  273.                                inhibit the erasing of the menu.
  274.  
  275.                        Seed% - When PULLDOWN is first called, the menu name
  276.                                corresponding to the number in this variable 
  277.                                is highlighted for selection.
  278.  
  279.                     SoundOn% - If set to zero (0), the routine will not make
  280.                                any sound.
  281.  
  282.                    Itemslct% - If set to -1 prior to CALLing PULLDOWN, the
  283.                                item selected will blink after it has been
  284.                                picked
  285.  
  286.      Returned:     MenuSlct% - The number of the menu containing the item that
  287.                                was selected.
  288.  
  289.                    ItemSlct% - The number of the item selected.
  290.                               
  291.                                                             
  292.     In addition, you can tell PULLDOWN to put in a dividing line with a 
  293. simple command.  All you do is insert a certain character into your
  294. ITEM$() array.  For example, to put a dividing line in your first menu after
  295. the third item, your program should define ITEM$(1,4) as:
  296.  
  297.             ITEM$(1,4) = "~"
  298.  
  299. The tilde "~" tells PULLDOWN to create a dividing line.
  300.  
  301.      The source code for PDDEMO is well documented and will provide a little
  302. more clarity on the function of each of these variable.  I encourage you to
  303. play around will PDDEMO a bit - get a feel for it by modifying it and seeing
  304. what it does.  Be sure to observe the calling conventions, though.
  305.  
  306.  
  307. COMPILING
  308.  
  309.     To create an .EXE file, follow these steps:
  310.  
  311.           1)   During development, use the EZQB.QLB (or EZPDS.QLB) Quick
  312.            Library inside the QB environment.
  313.  
  314.           2)   When you're ready to compile the finished program, first
  315.                decide if you want a stand-alone program or one that needs the
  316.                BRUNxx.exe file to run.  Then go to the DOS prompt in your QB
  317.                directory and use this syntax to compile your program:
  318.  
  319.                     BC PROGRAMNAME [/O],,nul       
  320.  
  321.                where PROGRAMNAME is the name of your basic program (no
  322.                extension), and the [/O] option tells QB to compile a stand-
  323.                alone program.  You may leave this option off if you want,
  324.                which will result in an executable file that needs the
  325.                BRUNxx.EXE file.  For example, to compile PDDEMO.BAS for
  326.                stand-alone program, type
  327.  
  328.                     BC PDDEMO /O
  329.  
  330.           3)   Now is when you link in the EZQB.LIB (or EZPDS.LIB) library
  331.                to the object code produced by the compiler.  From the DOS
  332.                prompt use this syntax to link your program:
  333.  
  334.                     LINK [/E] PROGRAMNAME,,,EZQB
  335.  
  336.                The [/E] is the EXEPACK option which produces a
  337.                smaller executable file and should be used for most every 
  338.                program that you may write.
  339.  
  340.           4)   You should now have an executable version of your QB program
  341.                in the QBxx directory.  Remember, if you didn't use the [/O]
  342.                option, the BRUNxx.EXE must be present.
  343.  
  344.  
  345.  
  346. HELP A BUDDING ENGINEER!
  347.  
  348.      If you think this pulldown menu routine will be useful to you, I would
  349. greatly appreciate a little donation to get me through graduate
  350. engineering school.  A $5.00 registration fee is all that's needed to get on 
  351. the mailing list and receive updates to PULLDOWN plus customer support.
  352. If you decide to register the full library (see below), the $5.00
  353. registration is waived.
  354.  
  355.  
  356. MORE ROUTINES!!
  357.  
  358.      If you run the EZDEMO1.EXE program on your disk, you will see a collection
  359. of my favorite routines that I would like to make available to you.  This is
  360. Volume 1 of the EZ-WINDOWS library.  I use these routines extensively in my
  361. programs, which not only saves a lot of time but also results in a professional
  362. looking program.  EZDEMO1.EXE has several command line parameters.  Type
  363. EZDEMO1 /? for a list of options.
  364.  
  365.      Here is what you get when you register the full library:  1) the complete
  366. library of routines with full documentation;  2)  free updates when they become
  367. available;  3)  customer support.  Included in customer support is E-mail,
  368. phone support, and the "wish list".  If you have an idea for a routine, and I
  369. get enough suggestions from others for the same type of routine, I will write
  370. it up and send it out with the next update.  In addition, I will be
  371. periodically updating my personal library with new routines which will be
  372. included in the next volume.  Each new volume can be obtained by registered
  373. users at a discount.
  374.  
  375.      I know a lot of you will want my source code, and I can understand that.
  376. I'm a little reluctant to give it out, but I will release it with the library
  377. for an extra fee.  For ordering info, see the REGISTER.DOC file.
  378.  
  379.  
  380. E-MAIL
  381.  
  382.      You may reach me by phone (503) 649-7251 until August 1991, or through
  383. E-mail at any time.  You can reach me at the following addresses:
  384.  
  385.             Prodigy        DVDT90A
  386.             PC-Link        Johnny Sky
  387.                         GEnie           J.STRONG6
  388.  
  389.  
  390. AND LASTLY...
  391.  
  392.      Have a ball! 
  393.  
  394.