The menus are accessible from the toolbar script through the Host.Menus property. This property represents the base VarioMenu object which has only one property (in the current VarioMenu version) - MenuTree which is the root of the menu structure the application defines.

Using the menus

The menu usage involves two different activities - menu definition and showing menu branches. 

In the menu definition phase the application creates menu branches and fills them with menu items, radio groups and so on. This has no visual consequence - it only defines a menu structure in the memory. The menu structure can be changed at any time the only limitation is that you must not alter the menu branch being shown while it is visible to the user.

In the menu showing phase the application calls the Host.DisplayPopupMenu method to show  part of the already defined menu structure as a pop-up menu. Any portion of the defined menu structure can be shown as a pop-up. The screen location is specified in the call to the DisplayPopupMenu method in screen coordinates - the application is responsible to compute the coordinates as appropriate.

Menu definition 

Let's illustrate this with a simple code:

Dim i,m, root
Set root = Host.Menus.MenuTree

Set m = root.CreateSubItem("MyContextMenu")

Set i = m.CreateSubItem("itm_0")
i.Caption = "IE ScriptBar Overview"
i.Handler = "OnSampleMenuCommand"
i.HandlerNamespace = ""
i.Info = Settings("BasePath") & "info.htm"

Set i = m.CreateSubItem("itm_sep_0")
i.Type = 2

Set i = m.CreateSubItem("itm_1")
i.Caption = "newObjects []"
i.Handler = "OnSampleMenuCommand"
i.HandlerNamespace = ""
i.Info = "http://www.newobjects.com"

The lines shown in bold above do the key work here. 

1. First we save the menu structure root in a variable to make the next statements shorter.
2. Then we create a new menu branch and we name it "MyContextMenu". We receive a reference to it in the m variable.
3. We add menu items to the newly created branch.

The menu item parameters. 

You can see the full reference of the menu item properties here. In the sample code above we use the most useful ones:

Caption - specifies the text that the user will see when the menu item is displayed. See also Caption property in the VarioMenu references.

Handler - The most important parameter - specifies the name of the routine in the toolbar script that will be called when the user clicks the menu item. This is an even handling routine you must implement in order to handle the menu item click user action. See the function prototype in the events reference. If the routine specified here is not implemented an error will occur. See also Handler property in the VarioMenu references. 

HandlerNamespace - You can omit this property always. It is put in this code only to remind those of you who use the VarioMenu in various environments that it supports that the events can be handled in more than one script. However in the current version of IE ScriptBar the menu events can be handled only in the toolbar script. Therefore you should not use the property or if you want to use it assign an empty string to it. See also HandlerNamespace property in the VarioMenu references.

Info - This parameter is for your application. You can save there any thing you like - string, number even object. When the event handler receives a menu item click notification it can access this property and thus determine what action to perform. There are many possible techniques - you can use a textual key strings like the URL above (where the handler function just navigates to the URL specified in the Info property), but you can also save an object and perform certain actions on it in the handler function. See also Info property in the VarioMenu references.

Type - This property specifies the type of the menu item. A menu item object can play different roles in the menu structure you define. It can be a root of a new menu sub-branch (a pop-up), a separator, a radio menu group or just a simple menu item. you can see all the constants in the here. To reduce the code needed the VarioMenu is designed to automatically set this property in the most cases. For example: See also Type property in the VarioMenu references.

Calling the CreateSubItem like in the above example (Set i = m.CreateSubItem ..) means that you use this item as a placeholder for a menu sub-branch. 

Creating a new menu item in a menu radio group automatically sets the Type to mitGroupMember.

For a regular menu item you can change the type to:

mitSeparator (2) - making the menu item a separator line which doesn't fire events and has no need of a caption.

mitCheckable (3) - making the menu item checkable

mitRadioGroup (4) - making the menu item a placeholder for radio group choices.

General rules

All the menu items and sub-branches in the branch must have unique names. I.e. you must specify unique name in the CreateSubItem call for each menu item you create over the same object. When the name is not important you can just generate random or sequential names, but you can make use of this instead - by using the name as a key string used later in the event handler to determine what kind of operation must be performed. This will leave the Info property free for other purposes. Of course, you can put in the Info property whatever you want - including a collection or an array of many values, so the name is most often generated in manner that helps debugging the application and nothing more, but as you can see above the actual usage is up to you - do whatever you find convenient.

Showing the menu

Sub ShowMenu(x,y)
  Host.DisplayPopupMenu Host.Menus.MenuTree.Subs("MyContextMenu"), x, y
End Sub

To show the menu you need just to specify which branch is to be shown and the screen coordinates. You can pass any branch including branches extracted from deeper parts of the menu structure - such as:

Host.DisplayPopupMenu Host.Menus.MenuTree.Subs("MyMenu")("MySubMenu1")("MySubMenu2"), x, y

I.e. the menu hierarchy you define may contain several levels of nested menu branches and you can pick a branch from any depth.

The above routine is implemented in the toolbar script. To make use of it you must call it from the toolbar DHTML in response to some user action - button/image or other element click for instance. As for the screen coordinates it is best to compute them in the DHTML part of the toolbar. We will give you a simple example on how to compute them, but notice that depending on how the DHTML part is designed you may need more complicated arithmetic. Check the DHTML References topics in MSDN for in-depth information for the DHTML object model and the ways to compute element coordinates.

The DisplayPopupMenu method supports an optional flags which control the way the menu is placed on the screen relatively to the specified coordinates and the available space. Although they are rarely used take a look at them in the Toolbar utility methods reference.

Additional techniques

Very often the applications that use menus want to be able to track the user's movements over an opened menu and show hints aboutthe menu item over which the mouse cursor is. Although the IE toolbars provide limited space your particular design may be able to hold such an information. If you want to track the user selection you must handle the OnMenuSelect event. By default it is disabled in the toolbar.cfg - enable it first!

You can implement quite interesting menu tracking capabilities - including dynamic design changes to the toolbar while the user moves over the menu.