Overview

VarioMenu objects' interfaces can be divided to three groups. First - the dual interfaces that represent the menu three to the script. Second - interfaces that are called by the application which hosts VarioMenu and the script (these have Host suffix in their names) and third - internal interfaces used in the communication between objects in VarioMenu (these have O- preffix).

In order to use VarioMenu an application should create VarioMenuTree object and keep it until the menu is needed. It uses IVarioMenuTreeHost interface to connect VarioMenu with the message loop and to take handle for menu accelerators. That handle should be passed to a call to TranslateAccelerator API function in the message loop. Importaint: Always call ClearMenuItems method of IVarioMenuTreeHost interface before you release the last interface to the VarioMenuTree object. If you don't do it the tree of MenuItem objects wouldn't desrtoy properly and memory leaks would appear.

To get menu handle to a branch of menu items use IVarioMenuHost interface. Call GetMenuFromHere to obtain the handle and FreeMenu when you no longer need it.

The host application should connect to the VarioMenuTree object and sink all events it fires through IVarioMenuEvents interface. This is the way it recieves notifications when a menu is clicked, or when it is changed and it should readraw the menu bar with DrawMenuBar function or keep and use the new menu or accelerator handle.

General behavior is that not the host application but VarioMenu is owner of all resource handles. That is why the host application can keep and use the handles while they are valid but not free them. An exception of that behavior is found in the implementation of OnRegenerateMenu event. The handler must free the old menu handle using DestroyMenu function and use the supplied new handle.
Another place where resource handles change their owner is in OnFreeMenu event. If the event handler returns VARIANT_TRUE in pbDontFree out parameter VarioMenu doesn't free the menu handle but only detaches it from the objects. That is useful when the menu is attached to a window. In that case Windows automatically frees the menu when the window is destroyed. If multiple handlers are connected to this event it is enough only one of them to return TRUE in pbDontFree in order to prevent menu destruction from VarioMenu.
Accelerator handles are autometically freed by VarioMenu. When the accelerator is regenerated and the handle changes, OnRegenerateAccel event is fired and the host application shoud use the given handle from now on in the calls to TranslateAccelerator in message loop.