home *** CD-ROM | disk | FTP | other *** search
/ Zodiac Super OZ / MEDIADEPOT.ISO / FILES / 13 / N_B_V203.ZIP / MENUS.TXT < prev    next >
Text File  |  1996-07-04  |  11KB  |  208 lines
  1. $if 0
  2.     ┌──────────────────────────╖                        PowerBASIC v3.20
  3.  ┌──┤          DASoft          ╟──────────────────────┬──────────────────╖
  4.  │  ├──────────────────────────╢    Copyright 1995    │ DATE: 1995-10-01 ╟─╖
  5.  │  │ FILE NAME   MENUS   .TXT ║          by          ╘════════════════─ ║ ║
  6.  │  │                          ║  Don Schullian, Jr.                     ║ ║
  7.  │  ╘══════════════════════════╝                                         ║ ║
  8.  │ A license is hereby granted to the holder to use this source code in  ║ ║
  9.  │ any program, commercial or otherwise,  without receiving the express  ║ ║
  10.  │ permission of the copyright holder and without paying any royalties,  ║ ║
  11.  │ as long as this code is not distributed in any compilable format.     ║ ║
  12.  │  IE: source code files, PowerBASIC Unit files, and printed listings   ║ ║
  13.  ╘═╤═════════════════════════════════════════════════════════════════════╝ ║
  14.    │                ....................................                   ║
  15.    ╘═══════════════════════════════════════════════════════════════════════╝
  16. $endif
  17.  
  18. '.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°.°
  19. ' ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° ° °
  20.  
  21. These functions and routines for menus are, I think,  just a bit past the
  22. point where I wanted to develop this package.  As menus are so  important
  23. to program/user interface  I generally like to design them separately for
  24. each program. Not so much on how they work ( that's pretty constant ) but
  25. in how they look and feel. I think it best if you have a look around this
  26. suite of functions then raid them for ideas and code.  You can, of course
  27. use them as they are but they are somewhat complicated.
  28.  
  29. ─────────────────────────────────────────────────────────────────────────
  30.  
  31. Menus are, still, an important part of any program. In graphics the items
  32. are, now-a-days,  icons but in text mode they are words.  Because of this
  33. they can be,  for a typist, easier to handle;  that is if you've got them
  34. set-up like the drop-down menu in PowerBASIC where the selections all can
  35. be chosen by a single letter. Remember, a typist does not  want to remove
  36. his/her hands from the keyboard.
  37.  
  38. The items of a menu can come from an array of known values you have given
  39. the program during production or can be read from an  index file, DOS, or
  40. a data file you have allowed the user to modify. Regardless of where they
  41. come from, or their numbers,  they all have to be displayed in an orderly
  42. manner that is easily accessible to the user. PowerBASIC's drop-down menu
  43. and file menu are two good examples of how menus should be presented.
  44.  
  45. Each item of a menu can have one of several values:
  46.   Non-existent   drawn as a separating line "├──────────────┤"
  47.   Inactive       shown but not selectable
  48.   Active         selectable
  49.     Selected     under the bar : this is also know as "HOT"
  50.     Not selected
  51.  
  52. Hot keys can be used differently also:
  53.   0) not used - the user is forced to move the bar and press <ENTER>
  54.   1) automatic selection: assumes that this item was moved to and selected
  55.   2) move only to the next/first item bearing this first letter
  56.   3) a variation is where letter keys are collected into a string and
  57.      the menu searches for the first match for the string
  58.        ie: user inputs "P" "O" and "W"
  59.            "P"   finds the first item starting with "P"
  60.            "PO"  skips forward to the first item starting with "PO"
  61.            "POW" skips forward to the first item starting with "POW"
  62.      this style is extremely handy when faced with hundreds or thousands
  63.      of items such as would be found in customer indexes, product lists,
  64.      etc.
  65.  
  66. Browsing is just another form a menu can take. It usually displays only a
  67. single item with extended information and is popular when searching for
  68. customer records, etc.
  69.  
  70. Item selection can also be interpreted differently also:
  71.   1) <ENTER> selects the single item and exits the function
  72.   2) <SPACE> toggles an ON/OFF variable and displays a mark for
  73.              the selected items
  74.      <ENTER> ends multiple selections
  75.              ie: the program presents a list of files found in a directory
  76.                  the user selects those files to be deleted
  77.                  when <ENTER> is pressed the hot items are acted upon
  78.  
  79. Menus can either wrap or not. Wrap is where the bar moves to the 1st item
  80. when it passes the last item on it's way down and moves to the last item
  81. when it passes the 1st item on it's way up.
  82.  
  83. Menus can consist of one column of items or several columns. If there is
  84. more than one column the selections can be displayed vertically ordered or
  85. horizontally ordered. (PB uses this style for the file menu) If the menu
  86. has to scroll to display all the items then horizontal order is, by and far
  87. the best of the two possibilities. If, on the other hand, the menu doesn't
  88. scroll then vertical is the more user friendly as it is more common to find
  89. columnized lists in vertical order (see any dictionary or index).
  90.  
  91. If the menu is going to scroll then it may be advantageous to display a
  92. slider button to indicate where, approximately, in the list the user is. This
  93. is most common in graphics but can be done quite effectively in text mode
  94. also. This style also allows a visual area for the mouse to be used to
  95. indicate "UP" and "DOWN". In fact the whole row above and below the item
  96. list can be used for these purposes but that may not be readily apparent
  97. to the user.
  98.  
  99. And, finally, we come to the hard part! What are these things supposed to
  100. look like? No one answer comes to mind, here, as each program has it's own
  101. look and feel that is, in part, effected by the menu design. Herein lies
  102. the difficult part of building a write once-use many menu routine. What
  103. follows is the architecture of how I handle the situation. It's not
  104. particularly easy to use while developing a program but sure cuts down on
  105. code when compiled, allows for a quick language change of the whole program,
  106. and has just about everything one could ask for.
  107.  
  108. ────────────────────────────────────────────────────────────────────────────
  109. ────────  fTmenuHOT%                                               ─────────
  110. ────────────────────────────────────────────────────────────────────────────
  111.  
  112. Each menu has 4 arrays sent to it:
  113.   I$()  = the items to be used
  114.   H$()  = a one line message displayed as each item comes under the bar
  115.   O?()  = an ON/OFF flag
  116.   T%()  = > 0 if item has been "tagged" or not
  117.  
  118.   Each array is dimmed starting with element ZERO. In this manner if your
  119.   menu will not be using the Help strings you can:
  120.  
  121.   I$(0) carries the 20 bytes of TMenuTYPE and the menu title in bytes 21+.
  122.   H$()  if DIMmed to ZERO will bypass the help feature
  123.   O?()  must be dimmed out to it's full length as the menu routine uses it
  124.         to store hot-key info if the item is "ON" when it came in.
  125.   T%()  can also be DIMmed to ZERO if no tagging is to take place or
  126.         up to the number of items you wish to be tagged           or
  127.         one element for each item
  128.         HUGH?
  129.         Ok. Your menu has 100 items. You want your user to select up to
  130.         any 5 of them: DIM T%(5) and when the 5th item is tagged the menu
  131.         returns. Or, DIM T%(100) and the user can run around tagging all
  132.         the items.
  133.  
  134.   There is one menu call to get all this happening: fTMenuHOT%
  135.   but I've put a group of small intermediate calls so you can get to any
  136.   or none of the "special" features without putting extra code into your
  137.   programs. The presence or absence of "H", "O", and/or "T" tells what
  138.   each routine expects or sets up for you.
  139.  
  140.   fTmenu%   ( I$(), LastI%, H$, Exet$, SelNo% )
  141.     the H$ here is a one-time help line or NULL if you don't want it
  142.     H$(), O?() and T%() are all taken care of for you
  143.  
  144.   fTmenuH%  ( I$(), LastI%, H$(), Exet$, SelNo% )
  145.     here you have requested a menu with a help line for each item.
  146.     O?() and T%() are taken care of for you
  147.  
  148.   fTmenuHO% ( I$(), LastI%, H$(), O?(), Exet$, SelNo% )
  149.     here only the T%() is omitted so each item has it's own help and can
  150.     be either On or Off
  151.  
  152.   fTmenuHT% ( I$(), LastI%, H$(), T%(), Exet$, SelNo% )
  153.     all items are ON, each has a help line and Tagging is implemented
  154.  
  155.   fTmenuO%  ( I$(), LastI%, H$, O?(), Exet$, SelNo% )
  156.     a one-time help line or NULL for H$ and items can be ON/OFF but
  157.     no tagging allowed
  158.  
  159.   fTmenuOT% ( I$(), LastI%, H$, O?(), T%(), Exet$, SelNo% )
  160.     once again a 1 time help line, items can be ON/OFF and ON items can
  161.     be Tagged
  162.     (This one really doesn't make much sense! I don't know what kind of
  163.      logic it would take to find oneself in this situation but....     )
  164.  
  165.   fTmenuT%  ( I$(), LastI%, H$, T%(), Exet$, SelNo% )
  166.     a one-time help line, all item are ON, and tagging is in effect
  167.  
  168.   fTmenuHOT% ( I$(), LastI%, H$(), O?(), T%(), Exet$, SelNo% )
  169.     EVERYTHING......
  170.     once again, I don't know <HOW> you could do this but this is the main
  171.     driver for all the others so it's gotta' big job to do.
  172.  
  173. Now that you know what, let's move on to "HOW".
  174.   I$() is a list of the menu items but I$(0) carries some special info into
  175.   the function. I$(0) is the data for TMenuTYPE and the title for the menu.
  176.     eg: I$(0) = tM + "Main Menu"
  177.         or.....
  178.         LSET tM = I$(0) : Title$ = MID$( I$(0), 23 )
  179.  
  180.                            ' ┌───────────────────┐
  181.                            '┌┤ GENERAL MENU TYPE ├───────────────────────────
  182. TYPE TmenuTYPE             '│└───────────────────┘
  183.   SetUp   AS BYTE          '│ if 0 then TmenuSETUP will be called
  184.   Row     AS BYTE          '│ starting row ( box border if .Brdr > 0 )
  185.   Col     AS BYTE          '│ starting col ( box border if .Brdr > 0 )
  186.   Iwide   AS BYTE          '│ MAX item width
  187.   IRows   AS BYTE          '│ N° if item rows    1, 2, 3, 4 etc
  188.   ICols   AS BYTE          '│ N° of item columns 1, 2, 3, 4 etc
  189.   Vert    AS BYTE          '│ Vertical YES/NO
  190.   Wrap    AS BYTE          '│ Wrap ON/OFF
  191.   HKs     AS BYTE          '│ 0 = NONE : 1 = ALPHA : 2 = HOT-KEY : >2 = TAG
  192.   '─────────────────────────┤
  193.   AttrN   AS BYTE          '│ Normal
  194.   AttrL   AS BYTE          '│ Letter HI-light or Tagged Item
  195.   AttrB   AS BYTE          '│ select Bar
  196.   AttrO   AS BYTE          '│ "OFF" item
  197.   '─────────────────────────┤
  198.   Srow    AS BYTE          '│ all 3 of these are computed by fTmenuBox$ when
  199.   Scol    AS BYTE          '│  .Srow > 0 else if .Srow = 0 then ignored
  200.   Srows   AS BYTE          '│  values used by fTmenuHOT% if .Srow > 0
  201.   Aattr   AS BYTE          '│  arrow attribute if > 0 else Battr used
  202.   '─────────────────────────┤
  203.   Brdr    AS BYTE          '│ Border style     SEE: TBoxDRAW
  204.   Battr   AS BYTE          '│ Border attribute
  205.   Shdo    AS BYTE          '│ Shadow style     SEE: DrawTShadow
  206.   Sattr   AS BYTE          '│ Shadow attribute
  207.   Tpos    AS BYTE          '│ Title Position
  208. END TYPE                   '└──────────────┤ 22 bytes ├──────────────────────