home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / pmos2002.zip / DEF / menus.def < prev    next >
Text File  |  1997-05-11  |  13KB  |  204 lines
  1. DEFINITION MODULE Menus;
  2.  
  3.         (****************************************************************)
  4.         (*                                                              *)
  5.         (*      Displays menus on screen, allows terminal user to       *)
  6.         (*                      select from them.                       *)
  7.         (*                                                              *)
  8.         (*  Programmer:         P. Moylan                               *)
  9.         (*  Last edited:        11 May 1997                             *)
  10.         (*  Status:             OK                                      *)
  11.         (*                                                              *)
  12.         (****************************************************************)
  13.  
  14. (************************************************************************)
  15. (*                                                                      *)
  16. (*  NOTE: This module gives you the choice of specifying your own       *)
  17. (*  window in which to display the menu, or using a window which is     *)
  18. (*  created for you when SelectFromMenu is called.  In either case,     *)
  19. (*  you use CreateMenu to define the menu initially, SelectFromMenu     *)
  20. (*  to prompt the user to choose from the menu, and DestroyMenu when    *)
  21. (*  you have finished using the menu.  You can also control some        *)
  22. (*  aspects of menu behaviour by calling the optional procedures        *)
  23. (*  MenuColours, SetOptions, and OffEdge after calling CreateMenu.      *)
  24. (*                                                                      *)
  25. (*  In most applications, you will want to let this module look after   *)
  26. (*  the screen window for you.  You need to call PositionMenu to        *)
  27. (*  define where on the screen the menu will be displayed, but you      *)
  28. (*  don't need to open a window explicitly.  The menu does not appear   *)
  29. (*  on the screen until SelectFromMenu is called, and - unless you      *)
  30. (*  have specified the MNoClose option - it disappears from the         *)
  31. (*  screen as soon as the keyboard user has made a selection.           *)
  32. (*  You may, if you wish, use a new call to PositionMenu before each    *)
  33. (*  call to SelectFromMenu, although the more common case would be to   *)
  34. (*  call PositionMenu just once, after the call to CreateMenu.          *)
  35. (*                                                                      *)
  36. (*  The alternative is to open your own screen window, and to call      *)
  37. (*  DisplayMenu to show the menu on the screen.  (This also means       *)
  38. (*  that DisplayMenu defines the location of the menu on the screen,    *)
  39. (*  so in this case PositionMenu should not be called.)  After that,    *)
  40. (*  you call SelectFromMenu to prompt the user to choose an item.       *)
  41. (*  This possibility is provided for applications where, for example,   *)
  42. (*  you want multiple menus within the same screen window.              *)
  43. (*                                                                      *)
  44. (*  Note for users of earlier versions of this module: the earlier      *)
  45. (*  distinction between Normal Mode and Special Mode is now obsolete.   *)
  46. (*                                                                      *)
  47. (************************************************************************)
  48.  
  49. FROM Windows IMPORT
  50.     (* type *)  Window, Colour, RowRange, ColumnRange;
  51.  
  52. TYPE
  53.     Menu;               (* is private *)
  54.     ItemText = ARRAY ColumnRange OF CHAR;
  55.     MenuColumn = CARDINAL;
  56.  
  57.     (* Note the dual use of the word "column".  A variable of type      *)
  58.     (* ColumnRange refers to a horizontal screen position.  But in      *)
  59.     (* menus we use "column" to a column of character strings, which    *)
  60.     (* is why we have the separate type MenuColumn.  The type           *)
  61.     (* MenuColumn is defined primarily to make it clear which type of   *)
  62.     (* column is being referred to in every case.                       *)
  63.  
  64.     MenuOption = (MTitle, MNoTitle, MBorder, MNoBorder, MClose, MNoClose,
  65.                         MKeyBack, MNoKeyBack, MFastSelect, MNoFastSelect,
  66.                         MMouse, MNoMouse, MCloseonClickOutside,
  67.                         MNoCloseonClickOutside);
  68.  
  69.     MO = SET OF MenuOption;
  70.  
  71.     (* The options have the following meanings:                         *)
  72.     (*  MTitle          Messages[0], as specified in the CreateMenu     *)
  73.     (*                  call, is used as a menu title to be displayed.  *)
  74.     (*  MNoTitle        No title is displayed, Messages[0] is ignored.  *)
  75.     (*  MBorder         The menu has a border.                          *)
  76.     (*  MNoBorder       The menu has no border.                         *)
  77.     (*  MClose          The window containing the menu is closed after  *)
  78.     (*                  a selection has been made.                      *)
  79.     (*  MNoClose        The window containing the menu is kept open on  *)
  80.     (*                  return from SelectFromMenu (and the same window *)
  81.     (*                  will be re-used on the next call).              *)
  82.     (*  MKeyBack        The keystroke that caused an exit from          *)
  83.     (*                  SelectFromMenu remains available to the caller, *)
  84.     (*                  via InKey() or equivalent.                      *)
  85.     (*  MNoKeyBack      On return from SelectFromMenu, the keystroke    *)
  86.     (*                  that caused the exit has been consumed.         *)
  87.     (*  MFastSelect     A menu item reached by selection key or mouse   *)
  88.     (*                  click is selected immediately.                  *)
  89.     (*  MNoFastSelect   The user has to type Space or Return to select  *)
  90.     (*                  the highlighted menu item.                      *)
  91.     (*  MMouse          The user may move and hide the menu with the    *)
  92.     (*                  mouse, if a mouse driver is present.            *)
  93.     (*  MNoMouse        User may click on the menu but may not move it  *)
  94.     (*                  with the mouse.                                 *)
  95.     (*  MCloseonClickOutside                                            *)
  96.     (*                  If user clicks outside the menu, we return as   *)
  97.     (*                  if Esc had been typed, and the click remains    *)
  98.     (*                  available to be interpreted by whatever windows *)
  99.     (*                  are on the screen.                              *)
  100.     (*  MNoCloseonClickOutside                                          *)
  101.     (*                  Any mouse click outside the menu is consumed    *)
  102.     (*                  but otherwise ignored.                          *)
  103.     (* Note that some of the options are mutually contradictory.  This  *)
  104.     (* way of specifying options was chosen to make it easy to specify  *)
  105.     (* "no change to previously set option", e.g. if you specify        *)
  106.     (* neither MTitle nor MNoTitle then the behaviour of the menu with  *)
  107.     (* respect to the title display remains at what was already in      *)
  108.     (* force.  If you specify contradictory options (e.g. MTitle and    *)
  109.     (* MNoTitle) at the same time then the result is not guaranteed to  *)
  110.     (* be consistent between versions of this module.                   *)
  111.  
  112.     OffEdgeOption = (stick, wrap, escape, return);
  113.  
  114.     (* An OffEdgeOption specifies what is to be done when the user      *)
  115.     (* tries to run the menu cursor off the edge of the menu.  The      *)
  116.     (* possibilities are:                                               *)
  117.     (*  stick           The cursor refuses to move in that direction.   *)
  118.     (*  wrap            The cursor wraps to the opposite edge.          *)
  119.     (*  escape          Return to caller with a result of 0.            *)
  120.     (*  return          Return to caller with a result that reflects    *)
  121.     (*                  the currently highlighted item.                 *)
  122.  
  123. (************************************************************************)
  124.  
  125. PROCEDURE CreateMenu (VAR (*OUT*) M: Menu;  columns: MenuColumn;
  126.                         VAR (*IN*) Messages: ARRAY OF ItemText;
  127.                         NumberOfItems: CARDINAL);
  128.  
  129.     (* Introduces a menu into the system, but does not display it yet.  *)
  130.     (* For a simple vertical menu, columns = 1.  Use columns > 1 for    *)
  131.     (* shorter and wider menus.  Messages[0] is the label to put into   *)
  132.     (* the menu header, if present.  The remaining entries in Messages  *)
  133.     (* are the items displayed when the menu is put on the screen.      *)
  134.     (* Special case: if you specify NumberOfItems = 0 then the whole of *)
  135.     (* array Messages is used.                                          *)
  136.     (* For each entry of Messages, the selection character is the       *)
  137.     (* character following a "\".  If there is no "\", the selection    *)
  138.     (* character is the first character.  The selection character must  *)
  139.     (* be alphanumeric.  To disable the selection character feature,    *)
  140.     (* put the "\" in front of a non-alphanumeric character or put it   *)
  141.     (* at the end of the string.                                        *)
  142.  
  143. PROCEDURE PositionMenu (M: Menu;  startline, endline: RowRange;
  144.                                 leftcol, rightcol: ColumnRange);
  145.  
  146.     (* Sets the screen position and size to be used when this menu is   *)
  147.     (* displayed by a call to SelectFromMenu.  This procedure does not  *)
  148.     (* actually display the menu - that doesn't happen until            *)
  149.     (* SelectFromMenu is called.                                        *)
  150.  
  151. PROCEDURE MenuColours (M: Menu;  fore, back, hfore, hback, select: Colour);
  152.  
  153.     (* Set the colours for the screen display of the menu.  The colours *)
  154.     (* fore and back are used as the normal foreground and background   *)
  155.     (* colours, and the highlighted menu item is displayed in colours   *)
  156.     (* hfore, hback.  The "select" colour is for highlighting the       *)
  157.     (* selection character.  This procedure is optional.                *)
  158.  
  159. PROCEDURE SetOptions (M: Menu;  options: MO);
  160.  
  161.     (* See the MenuOptions declaration for the possible options.  This  *)
  162.     (* procedure is optional.  If it is not called, the default options *)
  163.     (* are {MTitle,MBorder,MClose,MNoKeyBack,MNoFastSelect,MMouse,      *)
  164.     (* MCloseonClickOutside}.                                           *)
  165.  
  166. PROCEDURE OffEdge (M: Menu;  top, bottom, left, right: OffEdgeOption);
  167.  
  168.     (* Sets the menu behaviour when the user runs the cursor off the    *)
  169.     (* edge of the menu.  There is one parameter for each edge of the   *)
  170.     (* menu.                                                            *)
  171.     (* See the OffEdgeOption type declaration for the possible options. *)
  172.  
  173. PROCEDURE SelectFromMenu (M: Menu): CARDINAL;
  174.  
  175.     (* Displays menu M on the screen, allows terminal user to use       *)
  176.     (* cursor keys to move about the menu and the ENTER key to select   *)
  177.     (* an item.  (The space bar is also accepted, as an alternative to  *)
  178.     (* the ENTER key, to select an item.)  An item may also be selected *)
  179.     (* by typing its initial letter, followed by space or ENTER.        *)
  180.     (* Returns the number of the item which was selected.               *)
  181.     (* (Item numbers start from 1).  An answer of 0 indicates that the  *)
  182.     (* user typed the ESC key to return without selecting anything.     *)
  183.  
  184. PROCEDURE DestroyMenu (M: Menu);
  185.  
  186.     (* Removes a menu from the system, freeing up the space it used.    *)
  187.  
  188. (************************************************************************)
  189. (*                      ALTERNATIVE DISPLAY PROCEDURE                   *)
  190. (************************************************************************)
  191.  
  192. PROCEDURE DisplayMenu (w: Window;  M: Menu;
  193.                                 rows, columns, initialvalue: CARDINAL);
  194.  
  195.     (* Displays menu M at the current cursor position in window w,      *)
  196.     (* with initialvalue specifying a field to highlight.  The space    *)
  197.     (* reserved on the screen is "rows" screen rows in height and       *)
  198.     (* "columns" character positions wide.  (The remainder of window w  *)
  199.     (* may of course be used for other purposes, including other        *)
  200.     (* menus.)  When SelectFromMenu is called, it will use window w.    *)
  201.  
  202. END Menus.
  203.  
  204.