home *** CD-ROM | disk | FTP | other *** search
/ Collection of Education / collectionofeducationcarat1997.iso / COMPUSCI / TOT11.ZIP / TOTDOC11.ZIP / CHAPT12.TXT < prev    next >
Text File  |  1991-02-11  |  59KB  |  1,430 lines
  1.                                                                            Menus
  2.                                                                            Menus
  3.                                                                            Menus
  4.  
  5.  
  6.  
  7.          "Ninety-eight percent of the adults in this country are decent, hard-
  8.          working Americans. It's the other lousy two percent that get all the
  9.          publicity. But then we elected them."
  10.  
  11.                                                                      Lily Tomlin
  12.  
  13.  
  14.  
  15.  
  16.  
  17. Introduction
  18.          You want menus, we got menus!
  19.  
  20.          The Toolkit includes three main menu types: pop-up menus, Lotus-style
  21.          menu bars and pull-down menus. All the menus can be nested many levels
  22.          deep, i.e. when the user selects an item from a menu, another menu can
  23.          be automatically displayed. You may optionally specify a description
  24.          for any menu item, and when the user highlights the item, the descrip-
  25.          tive text is automatically displayed. All the menus provide full mouse
  26.          support, and if the mouse cursor drifts across a specific item, it is
  27.          automatically highlighted. Menu items can also be selected with the
  28.          cursor keys or by pressing a menu item hotkey.
  29.          The object hierarchy includes a number of abstract objects, as illus-
  30.          trated in figure 12.1. You should never declare an instance of type
  31.          BaseMenuOBJ, WinMenuOBJ, BarMenuOBJ or KwikPullOBJ, as these are
  32.          abstract. Use one of the following objects to display a menu:
  33.  
  34.          MenuOBJ            This object displays a simple menu in a window. This
  35.                             object is commonly used for a program's main menu
  36.                             which is displayed when the program starts.
  37.          MoveMenuOBJ        This object is similar to MenuOBJ, except that the
  38.                             user can drag the menu around the screen to view the
  39.                             contents of the screen below.
  40.  
  41.          LotusMenuOBJ       The LotusMenuOBJ provides a 1-2-3 (or Paradox!)
  42.                             style menu bar. The user scrolls left and right
  43.                             along the menu bar.
  44.          PullMenuOBJ        This is an "IDE-like" pull-down menu which supports
  45.                             multiple levels of sub-menus.
  46.  
  47.          EZPullArrayOBJ     This objects provides a quick and easy way of
  48.                             creating a sophisticated pull-down menu. All you
  49.                             have to do is update a string array with the
  50.                             individual item details, and instruct the Toolkit to
  51.                             display the menu.
  52.  
  53. 12-2                                                                User's Guide
  54. --------------------------------------------------------------------------------
  55.  
  56.          EZPullLinkOBJ      This object is similar to the EZPullArrayOBJ, except
  57.                             that the menu item details are added to a linked
  58.                             list (of type DLLOBJ or descendant).
  59.  
  60.  
  61. Figure 12.1                                                            [PICTURE]
  62. Menu
  63. Object Hierarchy
  64.  
  65.  
  66.  
  67. Common Methods
  68.          All menus contain items, hotkeys, descriptions, and the like. The Tool-
  69.          kit's varied menu objects share a variety of common methods which are
  70.          used to construct the menu details and characteristics.
  71.  
  72.  
  73. Adding Menu Item Details
  74.  
  75.          The following methods are used to set the individual menu details:
  76.  
  77.          Init;
  78.  
  79.          The Init method is passed no parameters, and should be called before
  80.          any other menu method.
  81.  
  82.          AddItem(Txt:StrVisible);
  83.  
  84.          This method is used to add an item to the menu. The method is passed
  85.          one parameter identifying the menu text to be displayed. The item
  86.          string may include embedded highlight characters to indicate that a
  87.          specific character is designated as a hot key -- refer to the WriteHi
  88.          method on page 5-3 for further information. Special strings can be
  89.          passed to force blanks or lines in the menu item list - see the note at
  90.          the end of this section.
  91.  
  92.          The following methods may be called to further define the settings for
  93.          each item. Note, however, that the item must have been added with AddI-
  94.          tem (or AddFullItem) before these additional settings can be specified.
  95.  
  96.  
  97.          SetHK(Item:byte; HK:word);
  98.          Any item can be assigned a hotkey, which provides a way for the user to
  99.          select the item without scrolling to the item. All the user does is
  100.          press the hotkey. The de facto standard is to use normal alphabet char-
  101.          acters as the hotkeys. (Lotus and pull-down menus support additional
  102.          hotkeys which can be pressed even when the appropriate menu is not on
  103.          display -- this subject is discussed in detail later).
  104.  
  105.  
  106. Menus Menus Menus                                                           12-3
  107. --------------------------------------------------------------------------------
  108.  
  109.          SetMessage(Item:byte; Msg:StrVisible);
  110.  
  111.          The SetMessage method is used to define a message for an item. When the
  112.          item is highlighted, the message will be automatically displayed, and
  113.          when the user moves to a different item, the message is removed. The
  114.          Toolkit does not save the contents of the screen where the message is
  115.          displayed.
  116.  
  117.          SetID(Item:byte; ID:word);
  118.  
  119.          In a menu system, which includes sub-menus, this method can be used to
  120.          assign each topic in the menu a unique ID. The method is passed two
  121.          parameters; the item number and the item ID. This ID is of type word,
  122.          and will be returned by the menu method Activate if the item is
  123.          selected by the user. Note that you should not use IDs greater than
  124.          65000, because some of these IDs are used internally by the Toolkit.
  125.  
  126.          SetStatus(Item:byte, On:boolean);
  127.  
  128.          Sometimes, certain menu items will not be selectable. For example, a
  129.          File Save option may not be operative until a file has been loaded or
  130.          created. The SetStatus method is used to control whether an option is
  131.          selectable. The method is passed two parameters; the item number and a
  132.          boolean parameter. Set the boolean to TRUE to enable the item and FALSE
  133.          to disable it.
  134.  
  135.          SetSubMenu(Item:byte; SubMenu:BaseMenuPtr);
  136.  
  137.          This method is used to indicate that another menu should be displayed,
  138.          if the item is selected by the user. The Toolkit will automatically
  139.          display the new menu below and to the right of the active menu. The
  140.          method is passed two parameters; the item number and the address of the
  141.          sub-menu object. Normally, you will call another menu instance of the
  142.          same type as the parent, e.g. if the parent menu is of type MenuOBJ,
  143.          then the sub-menu is usually of type MenuOBJ. This, however, is not
  144.          mandatory, and any menu item can display a sub-menu of any type in the
  145.          menu object hierarchy. Note that the second parameter is the address of
  146.          the sub-menu, and is normally specified by preceding the menu object
  147.          with the Turbo Pascal "@" address symbol. For example:
  148.  
  149.                      SetSubMenu(5,@FileMenu);
  150.  
  151.          When you want to specify all the menu item details, e.g. message, HK,
  152.          sub-menu, etc., you can use the following all-in-one method:
  153.  
  154.  
  155.          AddFullItem(Txt:StrVisible;ID,Hk:word; Msg:StrVisible; SubM:Baseme-
  156.          nuPtr);
  157.  
  158.  
  159.  
  160. 12-4                                                                User's Guide
  161. --------------------------------------------------------------------------------
  162.  
  163.          As you may have guessed, this method is used to add a new item and
  164.          specify its settings in one heavy statement! This method is a single
  165.