home *** CD-ROM | disk | FTP | other *** search
/ POINT Software Programming / PPROG1.ISO / basic / mnusys21 / readme.doc < prev    next >
Encoding:
Text File  |  1993-10-06  |  9.4 KB  |  218 lines
  1. Menusys PowerBASIC Menuing System
  2. Version/Release 2.1
  3. (C) Copyright 1993 by Tim Gerchmez
  4. ----------------------------------
  5.  
  6.     Menusys is a complete text-mode GUI for PowerBASIC 3.0.  Included
  7. is Menulib, a library of support routines that add a great deal of
  8. functionality to Menusys.  Menusys can be used either by itself or with
  9. Menulib ; however, using routines in Menulib requires that you link in
  10. the Menusys routines as well.
  11.  
  12.        Both Menusys and Menulib are supplied as PowerBASIC .PBU files
  13. in this package.  All the subprograms and functions are detailed in
  14. the files MENUSYS.DOC and MENULIB.DOC.
  15.  
  16.     You may use Menusys and Menulib routines in your programs intended
  17. for PERSONAL USE ONLY, without paying any fees.  However, if you intend to
  18. distribute your programs that include Menusys and/or Menulib, either for
  19. profit or for freeware release, you must register Menusys and Menulib with
  20. me.  Registration for both packages is $25.00 (twenty five dollars), and 
  21. entitles you to the source code for both libraries.  You will also be 
  22. entitled to ongoing technical support by mail for both libraries.
  23.  
  24.     Businesses may NOT use the shareware version of Menusys/Menulib, as
  25. it is intended for evaluation purposes only.  A business may only run
  26. the demo .EXE programs included, and may NOT use Menusys/Menulib routines
  27. under ANY circumstances without registering.  Site licensing is available;
  28. please contact me at the address below with a reasonable offer, and I'll
  29. consider it.
  30.  
  31.     To register Menusys/Menulib, please send a check/MO for $25.00
  32. made out to Tim Gerchmez, to:
  33.  
  34. Tim Gerchmez
  35. 12648 S.E. 81st Pl.
  36. Renton, WA  98056-9121
  37.  
  38. Please specify the disk format desired - if you don't, I'll assume
  39. 3 1/2", 1.44Mb High Density format.
  40.  
  41. BE SURE to include your phone number and return address so I can send
  42. you the source code to Menusys and Menulib, and can notify you when
  43. upgrades are available to the programs.  Once you register, you're
  44. automatically registered for ALL future versions of both libraries.
  45.  
  46. Distributors: Please distribute this entire package/archive freely,
  47.           making every attempt to keep the files together.
  48. -----------------------------------------------------------------------------
  49.  
  50. Installing Menusys/Menulib:
  51.  
  52.     To install, create a subdirectory under your PB3 directory entitled
  53. SHAREMNS or something similar, and copy all files in this archive (disk)
  54. to that subdirectory.  If you're in the RUNME program included with this
  55. package, you can press <I> now to install the package to the drive/
  56. subdirectory of your choice (if it doesn't exist, RUNME will create it).
  57. After that, copy the .PBU files manually to your PowerBASIC .PBU
  58. directory.  Also copy the included PowerBASIC help file MENUSYS.PBH to your 
  59. main PowerBASIC directory.  This help file provides online help for Menusys/
  60. Menulib which is accessible by pressing SHIFT-F1 repeatedly until the Menusys
  61. help menu comes up.
  62.  
  63.  
  64. Using Menusys/Menulib Routines
  65. ------------------------------
  66.  
  67.     Menusys requires no special "event-driven" programming techniques.
  68. You simply include a special header in your programs (see MNSSHELL.BAS),
  69. and check for either of the following conditions in the main loop of your 
  70. program:
  71.  
  72. * If the mouse cursor is on the top row of the screen, and the left mouse
  73.   button is pressed, call the main MENUSYS routine to display the pulldown
  74.   menus.  Use the MCHECK sub, and the global variables msy% and lb%.
  75.   For example:
  76.  
  77.   call mcheck
  78.   IF msy% = 1 AND lb% = 1 then goto dothemenu
  79.  
  80. * If the alt key is pressed, call the main MENUSYS routine to display the
  81.   pulldown menus.  Use the ALTKEY% function.  For example:
  82.  
  83.   IF altkey% then goto dothemenu
  84.  
  85.     That's all there is to it!  The other routines in Menusys and Menulib
  86. you call as needed - for user input, menu selection, check boxes, etc.
  87.  
  88.     You can use the SUB printtopmenu to display the top (bar) menu at the
  89. start of your program.  Be sure to call this routine every time you erase
  90. the screen if you want to "keep" a menu at the top of the screen at all times.
  91. See MNSDEMO.BAS to see how this routine can be used.
  92.  
  93.  
  94. Explanation of PUBLIC variables
  95. -------------------------------
  96.  
  97.     Each Menusys/Menulib program should include a header declaring a
  98. series of PUBLIC variables.  A complete example of this header is in the
  99. file MNSSHELL.BAS, which is a "shell" you can use to add Menusys/Menulib
  100. routines to your programs.  These PUBLIC variables are correspondingly 
  101. declared as EXTERNAL statements in the MENUSYS.PBU and MENULIB.PBU files, 
  102. and are "global" to your program and to Menusys and Menulib.  Each of them
  103. defines an important parameter, and most should be set at the start of your
  104. program (before calling Menusys/Menulib routines):
  105.  
  106. * scrnbuf?(min,2) - Declares a buffer for storing text screens.  At the start
  107.   of your programs, you should have the statement DIM scrnbuf?(1:4096, 0:3), 
  108.   which will actually DIM the scrnbuf?() variable to the required minimum 
  109.   values.
  110.  
  111. * explode%  - Set this variable to 0 for normal boxes, or 1 for "exploding"
  112.   boxes in your Menusys/Menulib program.  A value greater than 1 introduces
  113.   a delay in the "exploding" effect which will vary from computer to computer.
  114.   You can change the value of this variable "on the fly" to make some boxes
  115.   explode, and some not.
  116.  
  117. * flash% - Setting this variable to 1 produces a "flashing" effect when        
  118.   you pick a menu option, making it easier for a user to tell which option
  119.   was selected.  You can change the value of this variable "on the fly."
  120.  
  121. * mouse% - Set to 1 for MOUSE EXISTS or 0 for NO MOUSE at the start of 
  122.   your program.  Use MHARDRESET to reset and check for the presence of a
  123.   mouse driver (see docs).  Menusys/Menulib will work with or without the
  124.   presence of a mouse (except for a few of the commands, like MOUSEPICK).
  125.  
  126. * segment& - Defines the current video segment (&hb000 for monochrome or        
  127.   &hb800 for color).  Set with the function VIDSEG&.
  128.  
  129. * msx%, msy% - Current location of the mouse cursor on the screen in x
  130.   and y text-screen coordinates (1-80 and 1-25).  These variables are set
  131.   by calling SUB MCHECK.
  132.  
  133. * lb%, rb% - Status of the left and right mouse buttons (1=pressed, 0=    
  134.   not pressed).  These are set by calling SUB MCHECK.
  135.  
  136. * topcount% - number of "top" (bar menu) selections.  See MNSSHELL.BAS
  137.   for demo of use.
  138.  
  139. * bottomcount% - number of "bottom" (box menu) selections.  See MNSSHELL.BAS
  140.   for demo of use.
  141.  
  142. * mainclr% - Main screen character color.
  143.  
  144. * mainbckg% - Main screen background color.    '"Main" Screen Colors
  145.  
  146. * clr% - Temporary screen character color.
  147.  
  148. * bckg% - Temporary screen background color.            
  149.  
  150. * clr1%, clr2%, clr3% - Alternate character colors used by many routines.    
  151.  
  152. * bckg1%, bckg2%, bckg3%  - Alternate Background Colors used by many
  153.   routines.
  154.  
  155. * helpfn$ - Name of help file for F1 online help.  Leave undefined for
  156.   no help.  See READHELP for format of help files.
  157.  
  158. * progname$ - Name of current program.  Used by several routines.  Leave     
  159.   undefined for no name.
  160.  
  161.  
  162. CONVERTING TO VERSION 2.1
  163. -------------------------
  164.  
  165.     Version 2.1 of Menusys/Menulib is a major overhaul, and it's likely
  166. that this version will "break" your code written using previous versions.
  167. The first thing you have to do is add the following statements to your code:
  168.  
  169. * In the PUBLIC statements at the top of your program, add:
  170.  
  171. public scrnbuf?(min,2)
  172. public explode%, flash%
  173.  
  174. * Add the following statement to your program prior to calling
  175.   Menusys/Menulib routines:
  176.  
  177. dim scrnbuf?(1:4096, 0:3)
  178. explode% = 0: flash% = 0
  179.  
  180.     At this point, I'd suggest compiling your code and making changes
  181. as the need comes up.  In updating Menulib, I found it necessary to delete
  182. several routines that I deemed unnecessary or not supportive of the overall
  183. concept of Menusys, to make room for improvements to the really powerful
  184. routines.  I apologize for any inconvenience this may cause you, and I've
  185. included the source code to the "old" routines I removed, so you can simply
  186. merge them into your main source program.
  187.  
  188.  
  189. Special note for Version 2.0+ : Monochrome (MDA) Compatibility
  190. --------------------------------------------------------------
  191.  
  192.     Menusys now uses direct buffering for screen saves, rather than
  193. transferring data between screen pages as earlier versions did.  This makes
  194. Menusys compatible with ALL display adapters, including the original MDA
  195. adapter (which has only one screen page available).  It also means that you
  196. must set aside a 16K (minimum) buffer at the start of your programs that use
  197. Menusys/Menulib.  This is done with the statement: 
  198.  
  199. DIM scrnbuf?(1:4096,0:3)
  200.  
  201.     You should add this command to all your Menusys programs if you wish 
  202. to compile them with Version 2.0, and should also add a corresponding PUBLIC 
  203. statement:
  204.  
  205. public scrnbuf?(min,2) 
  206.  
  207. at the top of your programs.  See MNSSHELL for an example.  Direct buffering 
  208. also gives you the ability to store many more screens, as you can increase 
  209. the 3 to as high a number as there is memory available (4K used for each 
  210. increase of subscript).  You can use the PAGECOPY command, or the new 
  211. SCREENSTORE and SCREENRECALL commands to store and retrieve full-color text 
  212. screens.  See the docs for each of these commands for more information.
  213.  
  214.  
  215.     I hope you enjoy using Menusys and Menulib.  A version for
  216. QuickBASIC 4.5 is also available.
  217.  
  218.