home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 8 / FreshFishVol8-CD1.bin / new / comm / bbs / 4d-bbsdemo / docs / text / 08.menu_commands < prev    next >
Text File  |  1993-12-28  |  28KB  |  805 lines
  1. Chapter 8:  Menus and Menu Commands
  2.  
  3.  
  4.  
  5.  
  6. 8.1 Overview
  7.  
  8.     The menus are the heart of the BBS.  They direct the user around the
  9. BBS and act as a guide.  Whether the menus are simple and plain, or
  10. complicated and fancy, the SysOp has complete control over every aspect of
  11. the menus.  This is a powerful feature enabling the SysOp to personalize
  12. and create a BBS which is very unique.
  13.  
  14. 8.2.1 Menu Formats
  15.  
  16.     All menu files are plain ASCII files located in the MENU:  directory.
  17. Editing and creating menus should be done with a text editor of your
  18. choice.
  19.  
  20.     The first line of the menu file should be the help file for the menu.
  21. This filename is appended either as .ASCII or .ANSI automatically by the
  22. BBS, depending on the on-line user's mode.
  23.  
  24.     The second line is the prompt for the menu.  This can include EIC
  25. codes and color codes.  If color codes are encountered and the user is in
  26. ASCII mode, they will simply be ignored.  There is a maximum of 80
  27. characters.
  28.  
  29.     The third line is the type of entry for the menu as listed below.
  30.  
  31.     TYPE DESCRIPTION
  32.  
  33.     0 Hotkey:  User enters one character without entering return.
  34.  
  35.     #>0 User can enter UP TO # characters, and must press Return at end
  36. (i.e.  10 means the user can enter up to 10 characters.)
  37.  
  38.      # The number sign means that a user can enter one character without
  39. having to press Return or enter up to a 3 digit number and must press
  40. return.  This is most often used in a menu to allow the user to enter
  41. hotkeys, and full numbers (i.e.  in a message base menu to change sections.
  42.  
  43.     -1 No user entry for this menu, and the first command will be executed
  44. automatically, irrelevant of the keypress code.  If the following commands
  45. also have the same keypress, they will be executed also.  This mode is
  46. designed for Command Menus.(Refer to section 8.4.1)
  47.  
  48.     From the fourth line on, each line represents one function.
  49. Everything on the line before the ":" represents the keypress for that
  50. function, everything on the right side of the colon is assumed to be the
  51. command.  The command can be split up into 1 to 4 parts separated by
  52. spaces.
  53.  
  54.     If a keystroke has more characters than allotted in line three, the
  55. function WILL NOT be accessible by the user.  Multiple lines CAN HAVE the
  56. same keystroke, in which case all lines will be executed BUT they must ALL
  57. be consecutive lines in the menu file.
  58.  
  59.     An example line would be:
  60.  
  61.     p:p p 0
  62.  
  63.     This means the keystroke is a single "p", and the command is ":p" with
  64. parameters of "p 0".  An example of multiple lines would be:
  65.  
  66.     o:2 TEXT:LOGOFF.TXT
  67.     o:0 q
  68.  
  69.     This would display the file "TEXT:LOGOFF.TXT" to the user, then do a
  70. quick logoff.  The following would NOT execute the third line:
  71.  
  72.     o:2 TEXT:LOGOFF.TXT
  73.     o:2 TEXT:LEAVE.TXT
  74.     p:p p 0
  75.     o:0 q
  76.  
  77.     In this example, the BBS would execute the first two commands, but
  78. upon seeing that "p" (line 4) is different from the "o" (line 2) the BBS
  79. would return to the prompt, and NOT execute the fourth line.
  80.  
  81. 8.2.1 Layouts
  82.  
  83.     4D-BBS uses menu locks to control user access to menus.  These menu
  84. locks can be unique to each user, and are system specific.  When designing
  85. your menus, it is best to first list all menus which you will be using, and
  86. give a unique lock to each menu.  If some menus are similar in function,
  87. you can give the same lock to them to cut down on the number of menu locks
  88. used.  (Refer to section 8.5.1 for more information.)
  89.  
  90.     There are two types of menu layouts which can be used.  The first is a
  91. hierachy method which means a menu is called, and when finished, the
  92. calling menu regains control.  You can stack menus in this method up to 16
  93. times, so keep this in mind when designing your menus.
  94.  
  95.     The second method is a basic goto or jump.  In this method, the
  96. calling menu is NOT remembered.  This is ideal if you wish to setup a maze
  97. or theme type, BBS since menus do not have to be remembered.
  98.  
  99.     Below are two examples of menus:
  100.  
  101.                                      Main Menu
  102.                     _____________|___________________
  103.                    |                          |                                       |
  104.         Message Bases      File Transfers                 Game Room
  105.                    |
  106.         Electronic Mail
  107.  
  108.     In the above setting, a user starts out at the Main Menu, and can go
  109. to one of the 3 menus.  If they choose the Message Bases, they can not go
  110. into the Game Room unless they exit the Message Bases and go back to the
  111. Main Menu.  If they are in the File Transfers, and want to go to Electronic
  112. Mail, they must go to the Main Menu, then the Message Bases, then finally
  113. to Electronic Mail.
  114.  
  115.  
  116.                       +-  Main Menu     -+
  117.                      /        |           \
  118.       Message Bases +---------+------------+-  Game Room
  119.         |            \        |           /
  120.       E-Mail          +- File Transfers -+
  121.  
  122.     In the above example, a user can jump from any section they wish to,
  123. EXCEPT for the E-Mail section.  To go to or from the E-Mail section, they
  124. must go through the Message Bases.
  125.  
  126.     Remember the above are ONLY examples, and the SysOp can setup the BBS
  127. using one of them, a combination, or design their own layout.
  128.  
  129. 8.2.2 Menu Move Commands
  130.  
  131.     The "0" and "1" menu command cover most basic menu move operations.
  132. They are as follows:
  133.  
  134.     COMMAND DESCRIPTION
  135.  
  136.     0 e Exits the current menu, and returns to the calling menu.  Can only
  137. be used if the calling menu used the "1" command.
  138.  
  139.     0 M Returns to the main menu and clears all hierarchy stacks.
  140.  
  141.     0 * NAME Enters a new menu WITHOUT saving the previous menu.  The "*"
  142. is the lock for the new menu.  The new menu does NOT know who the calling
  143. menu was.
  144.  
  145.     1 * Name Enter a name menu saving the previous menu.  The "*" is the
  146. lock for the new menu.  The new menu DOES know who the calling menu is and
  147. can use the "0 e" command to return to the calling menu.
  148.  
  149.     The two basic commands for moving between menus can be mixed, as in
  150. the second example of section 8.2.1, but caution should be exercised when
  151. doing so.  A loop like this can cause stack limit problems:
  152.  
  153.          Menu --+
  154.           |     |
  155.       Sub-Menu  |
  156.           |     |
  157.      Sub-Menu2 -+
  158.  
  159.     If a jump was used to go from Sub-Menu2 back to Menu, the stack would
  160. not be cleared.  Doing this too many times would bring upon a maximum
  161. sub-menus encountered error to the user.
  162.  
  163.  
  164.  
  165. 8.3 Menu Commands
  166.  
  167.     When a user presses a menu key the BBS will scan the menu file to see
  168. if any matching keypresses are found.  If none are found and the menu is in
  169. Hotkey mode, nothing will happen and the BBS will accept another character.
  170. If the menu is multi-character input and the BBS does not find a match, it
  171. will display "Unknown menu function" and redisplay the prompt.
  172.  
  173.     If the BBS does find a match, it will execute the command after the
  174. ":" in the line, and then check if the next line is the same.  If it is,
  175. then that line will also be executed and this cycle is continued until
  176. either a match is not found or the last command is executed.
  177.  
  178.     Once a command is finished the BBS displays the prompt again and
  179. starts this process over again.  If the command which was executed goes to
  180. another menu, this process is continued on THAT menu.  If the command logs
  181. the user off, the process stops.
  182.  
  183. 8.4 Types of Menus
  184.  
  185.     Currently there are 4 types of menus which you can setup.  These are:
  186. Command, Personal, Access, Global and Default Menus.
  187.  
  188. 8.4.1 Command Menus
  189.  
  190.     A Command Menu is a menu that directly executes the first command
  191. without displaying the logon/stats screen or bulletins.  An example of
  192. using this type of menu would be if you wanted to spawn a serial based
  193. program when a certain account logged on.  UUCP's UUCICO could be used this
  194. way.
  195.  
  196.     The format for this type of menu is the "Cmd." plus the account name
  197. plus ".menu".  So, if you were running UUCP, and your feeds logon account
  198. was called UUCP, you would make a menu called "Cmd.UUCP.Menu", which is a
  199. normal menu with the first command as "a:4 UUCICO" and the second command
  200. as "a:q".  Although the keypress for the commands are irrelevant, they MUST
  201. be the same.
  202.  
  203. 8.4.2 Personal Menus
  204.  
  205.     A Personal Menu is the same as a main menu, except it is used INSTEAD
  206. of the Default, Access or Main Menu.  This allows you to give a different