[21.0] Creating Custom Menu Entries

v5.0 / 21 of 23 / 01 sep 99 / gvg

* While in early versions of VEE modifying the VEE menu bar required tinkering with a large menu file, VEE 4.X provided a new scheme that was much easier to work with. This chapter describes the details.

[21.1] OVERVIEW
[21.2] ADDING A FULL MENU OF CONVERSION FUNCTIONS
[21.3] SPLICING ENTRIES INTO AN EXISTING MENU
[21.4] ADDING A CUSTOM HELP FILE

[21.1] OVERVIEW

* With the current VEE custom menu scheme, menu modifications can be stored in a file in the VEE installation directory; the modifications will be incorporated into the VEE menu when VEE is booted. The menu file can have any name, but must end in the extension ".mnu". There can be more than one menu file in the VEE installation directory; VEE will incorporate all the modifications defined in all the files.

The VEE custom-menu system provides you with the following capabilities:

You can add new menu entries or submenus at any place in the menu hierarchy.
Menu entries can load files containing VEE objects and merge them into the target program.
Or they can link to custom help files.

The next sections describe several simple examples to illustrate how the current custom menu system works.

[21.2] ADDING A FULL MENU OF CONVERSION FUNCTIONS

* For a first example, imagine creating an entire new menu of VEE objects to perform metric conversions. The standard VEE menu looks like this:


 +-------------------------------------------------------------------------+
 | HP VEE                                                                  |
 +-------------------------------------------------------------------------+
 | File  Edit  View  Debug  Flow  Device  I/O  Data  Display  Window  Help |
 +-------------------------------------------------------------------------+
 |                                                                         |

According to Microsoft specs, no new menu entries should be put before the standard "Edit" entry or after the standard "Help" entry. So in this example we'll put the new "Convert" menu after "Data":


   --------------------------------------------+
                                               |
   --------------------------------------------+
     I/O  Data  Convert  Display  Window  Help |
   --------------------------------------------+
                ^                              |

This menu has the following entries:


   -------------------------
    Data  Convert  Display  
   -----+----------+--------
        | m2feet   |  meters to feet
        | feet2m   |  feet to meters
        | km2miles |  kilometers to miles
        | miles2km |  miles to kilometers
        | km2nm    |  kilometers to nautical miles
        | nm2km    |  nautical miles to kilometers
        +----------+
        | kg2lb    |  kilograms to pounds
        | lb2kg    |  pounds to kilograms
        +----------+
        | litr2gal |  liters to US gallons
        | gal2litr |  US gallons to liters
        +----------+
        | c2f      |  degrees Celsius to degrees Fahrenheit
        | f2c      |  degrees Fahrenheit to degrees Celsius
        +----------+

Each one of these functions consists of a simple Formula box with the appropriate conversion factor embedded. For example, the m2feet() function consists of:


   +--------------+
   |    m2feet    |
   +---+----------+
   | M | m*3.281  +-->
   +---+----------+

Each of these custom formulas is stored in its own file, with a name corresponding to the function -- in this case, the file name is "m2feet.vee". There's no magic reason to have that particular name -- it's just convenient.

I originally tried to define the Formulas as UserFunctions, but since the menu entries do a program merge, rather than library merge, and that didn't work so well.

The formulas are defined as follows:


   m2feet():      m*3.281
   feet2m():      f/3.281
   km2miles():    k/1.609
   miles2km():    m*1.609
   km2nm():       k/1.852
   nm2km():       n*1.852

   kg2lb():       k*2.205
   lb2kg():       l/2.205

   litr2gal():    l/3.786
   gal2litr():    g*3.786

   c2f():         (9/5)*c+32
   f2c():         (5/9)*(f-32)

The various files containing the conversion-factor formulas -- m2feet.vee, feet2m.vee, and so on -- are stored in a subdirectory of the VEE installation directory named "cf". Again, nothing magic about this, it's just convenient.

Now on to adding the menu. I created a file named "cf.mnu" and stored it in the VEE installation directory. Its contents are as follows (and will be explained in detail momentarily:


   # Conversion Factors Menu:  Build new menu list for conversion factors.
   #
   "MENU->Window"
   ("&Convert"
      ("&m2feet"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/m2feet.vee"
         [desc "converts meters to feet"]
      )
      ("&feet2m"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/feet2m.vee"
         [desc "converts feet to meters"]
      )
      ("&km2miles"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/km2miles.vee"
         [desc "converts kilometers to miles"]
      )
      ("m&iles2km"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/miles2km.vee"
         [desc "converts miles to kilometers"]
      )
      ("km2nm"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/km2nm.vee"
         [desc "converts kilometers to nautical miles"]
      )
      ("nm2km"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/nm2km.vee"
         [desc "converts nautical miles to kilometers"]
      )
      [separator]
      ("k&g2lb"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/kg2lb.vee"
         [desc "converts kilograms to pounds"]
      )
      ("&lb2kg"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/lb2kg.vee"
         [desc "converts pounds to kilograms"]
      )
      [separator]
      ("li&tr2gal"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/litr2gal.vee"
         [desc "converts liters to US gallons"]
      )
      ("g&al2litr"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/gal2litr.vee"
         [desc "converts US gallons to liters"]
      )
      [separator]
      ("&c2f"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/c2f.vee"
         [desc "converts degrees Celsius to degrees Fahrenheit"]
      )
      ("f&2c"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/cf/f2c.vee"
         [desc "converts degrees Fahrenheit to degrees Celsius"]
      )
   )

The first element in the file is simply a comment:


   # Conversion Factors Menu:  Build new menu list for conversion factors.

The "#" character defines a comment line. The next element specifies the creation of a new menu entry and where the new entry will be placed in the VEE menu hierarchy:


   "MENU->Window"

The "MENU" keyword specifies a new menu entry, and points to where the new menu entry should be placed -- in this case, before the "Window" entry in the main VEE menu. After this comes a series of entries that defines the architecture of the new menu:


   ("&Convert"
      ("&m2feet"
      ...
      )
      ("&feet2m"
      ...
      )
      ("&km2miles"
      ...
      )
      ("m&iles2km"
      ...
      )
      ("km2nm"
      ...
      )
      ("nm2km"
      ...
      )
      [separator]
      ("k&g2lb"
      ...
      )
      ("&lb2kg"
      ...
      )
      [separator]
      ("li&tr2gal"
      ...
      )
      ("g&al2litr"
      ...
      )
      [separator]
      ("&c2f"
      ...
      )
      ("f&2c"
      ...
      )
   )

The "Convert" entry is the name of the menu. The various entries nested below it give the entries for each of the functions -- "m2feet", "feet2m", and so on. The "[separator]" keyword defines a menu separator line.

Note the use of the ampersand ("&") to designate "shortcut" characters; given the entry "&km2miles", then "k" is the shortcut character, and once you select the menu you can select that entry by pressing "k". Shortcut characters are optional -- you don't have to define one. Selecting the appropriate characters can be tricky, and if you have duplicates only the first entry with the shortcut character will match it.

All the function entries have a similar form:


   ("&m2feet"
      [visibleWhen notRunning]
      getDevicesFrom: "~installDir/cf/m2feet.vee"
      [desc "converts meters to feet"]
   )

The "&m2feet" item simply gives the menu entry, as mentioned. The next item:


   [visibleWhen notRunning]

-- simply specifies that this menu entry is disabled ("grayed-out") when VEE is actually running a program. It is optional.

The next item specifies the action to be taken, and what to take the action on:


   getDevicesFrom: "~installDir/cf/m2feet.vee"

The "getDevicesFrom" keyword specifies that a file containing VEE objects be merged into the current VEE program; the parameter is the target VEE file. Note that the "~installDir" string simply indicates the defined VEE installation directory. Although forward slashes ("/") are used to define the path, the path is valid for both HP-UX and Windows.

The last item is an optional descriptive string that shows up on the status bar at the bottom of the VEE display when the mouse is over that menu entry:


   [desc "converts meters to feet"]

[21.3] SPLICING ENTRIES INTO AN EXISTING MENU

* For a second example, consider adding entries to an existing menu. In this case we'll add some barchart routines to the Display menu.

The default Display menu has the form:


   ---------------------
   Data  Display  Window
   ----+------------------------+--
       | AlphaNumeric           |
       | Logging AlphaNumeric   |
       | Indicator             >|
       +------------------------+
       | XY Trace               |
       | Strip Chart            |
       | Complex Plane          |
       +------------------------+
       | X vs Y Plot            |
       | Polar Plot             |
       +------------------------+
       | Waveform (Time)        |
       | Spectrum (Freq)       >|
       +------------------------+
       | Picture                |
       | Label                  |
       | Beep                   |
       | Note Pad               |
       +------------------------+

The revised menu adds two entries for Bar Chart objects:


   ---------------------
   Data  Display  Window
   ----+------------------------+--
       | AlphaNumeric           |
       | Logging AlphaNumeric   |
       | Indicator             >|
       +------------------------+
       | XY Trace               |
       | Strip Chart            |
       | Complex Plane          |
       +------------------------+
       | Bar Chart 1            | <- new menu entries
       | Bar Chart 2            |
       +------------------------+
       | ...                    |

For this example, all these entries do is enter the complete Bar Chart example programs provided with VEE. This isn't all that useful, but revising the Bar Chart program files to give a cleaner solution is beyond the scope of this article.

In any case, the new menu entries are provided by a file named "bchart1.mnu", which contains the following:


   # Bar Charts Menu 1:  Insert Bar Chart routines in line with menu.
   #
   "MENU->Display->X vs Y Plot"
   ("Bar Chart 1"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/examples/lib/barcht1.vee"
         [desc "bar chart 1"]
   )
   "MENU->Display->X vs Y Plot"
   ("Bar Chart 2"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/examples/lib/barcht2.vee"
         [desc "bar chart 2"]
   )
   "MENU->Display->X vs Y Plot"
   ( [separator] )

Note, very importantly, that this file contains three separate menu definitions, all of which are inserted (in sequence) before the "X vs Y Plot" menu entry:


   "MENU->Display->X vs Y Plot"
   ("Bar Chart 1"
   ...
   )
   "MENU->Display->X vs Y Plot"
   ("Bar Chart 2"
   ...
   )
   "MENU->Display->X vs Y Plot"
   ( [separator] )

This is a little awkward, but it's the only way to splice menu entries into an existing menu.

Another thing to note is that these entries are inserted before the "X vs Y Plot" entry in the menu. If you want to insert them at the very end, you have to use the END entry:


   # Bar Charts Menu 2:  Insert Bar Chart routines at end of menu.
   #
   "MENU->Display->END"
   ( [separator] ) 
   "MENU->Display->END"
   ("Bar Chart 1"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/examples/lib/barcht1.vee"
         [desc "bar chart 1"]
   )
   "MENU->Display->END"
   ("Bar Chart 2"
         [visibleWhen notRunning]
         getDevicesFrom: "~installDir/examples/lib/barcht2.vee"
         [desc "bar chart 2"]
   )

This gives:


   | X vs Y Plot            |
   | Polar Plot             |
   +------------------------+
   | Waveform (Time)        |
   | Spectrum (Freq)       >|
   +------------------------+
   | Picture                |
   | Label                  |
   | Beep                   |
   | Note Pad               |
   +------------------------+
   | Bar Chart 1            | <- new menu entries
   | Bar Chart 2            |
   +------------------------+

* Instead of inserting the new entries in line with the old menu, it may be cleaner (particularly if there are a number of new entries) to build a cascade menu instead. For example:


   ---------------------
   Data  Display  Window
   ----+------------------------+--
       | AlphaNumeric           |
       | Logging AlphaNumeric   |
       | Indicator             >|
       +------------------------+
       | XY Trace               |
       | Strip Chart            |
       | Complex Plane          |
       +------------------------+--------------+
       | Bar Charts            >| Bar Chart 1  | <- new cascade menu
       +------------------------+ Bar Chart 2  |
       | X vs Y Plot            +--------------+
       | Polar Plot             |
       +------------------------+
       | Waveform (Time)        |
       | Spectrum (Freq)       >|
       +------------------------+
       | Picture                |
       | Label                  |
       | Beep                   |
       | Note Pad               |
       +------------------------+

These new entries are inserted by a file named "bchart2.mnu", which has the content:


   "MENU->Display->X vs Y Plot"
   ( [separator] )
   "MENU->Display->X vs Y Plot"
   ( "Bar Charts"
      ( "Bar Chart 1"
            [visibleWhen notRunning]
            getDevicesFrom: "~installDir/examples/lib/barcht1.vee"
            [desc "bar chart 1"]
      )
      ( "Bar Chart 2"
            [visibleWhen notRunning]
            getDevicesFrom: "~installDir/examples/lib/barcht2.vee"
            [desc "bar chart 2"]
      )
   )

[21.4] ADDING A CUSTOM HELP FILE

* As a final example, the VEE custom menu system allows you to link to custom Help files, so we'll link a "help" file into the menu. The standard help menu looks like this:


   ------------------------------+
    Window  Help                 |
   -------+----------------------+
          | Contents             |
          | How To Use Help      |
	  +----------------------+
	  | Instruments ...      |
	  +----------------------+
	  | Open Example ...     |
	  | About VEE ...        |
	  +----------------------+

The revised menu looks like this:


   ------------------------------+
    Window  Help                 |
   -------+----------------------+
          | Contents             |
          | How To Use Help      |
	  +----------------------+
	  | Instruments ...      |
	  +----------------------+
	  | Open Example ...     |
	  | ActiveX Control Help | <- new entry
	  | About VEE ...        |
	  +----------------------+

The menu file is named "menu.hlp" and contains the text:


   "MENU->Help->About VEE..."
   ("ActiveX Control Help"
       help: "Reference@~installDir\call.hlp"
       [desc "link to ActiveX Control help file"]
   )

The only new thing here is the entry:


   help: "Reference@~installDir\call.hlp"

The "help" keyword specifies a link to a helpfile. The link defines both the helpfile name ("call.hlp") and the topic in the helpfile ("Reference"). You must define both to establish the link as there is no default.