home / documentation / reference / hm_onvisibilitytoggle

HM_OnVisibilityToggle

Description:

The custom (user defined) method that is called whenever HierMenus is about to toggle the visibility of a menu.

Value:

JavaScript function.

Applies To:

Menus.

Browser Compatibility:

HM_OnVisibilityToggle is supported in all browsers.

Parameters:

(menuEl,show)

menuEl is the HTML element for the menu

show is a boolean indicating whether the menu is about to be displayed (true) or hidden (false).

Comments:

HM_OnVisibilityToggle is a HierMenus Menu Event Hook; a means for you to execute your own custom JavaScript code from within normal HierMenus processing. All menu event hooks expect to be set to the name of a custom function (typically of your own creation, although the HM_Loader.js file contains some custom functions designed for use with event hooks), a function literal, or a dynamically generated function.

The function you create for use with this menu event hook should be designed as a method of the menu object, i.e., the internal menu object that HierMenus creates to track the various unique parameters of the menu itself. Thus, the this keyword, within the context of your custom function, refers directly to the menu object.

The menu object (referred to by this) is not the same as the menu element. The menu object is the internal structure that HierMenus uses to track various pieces of information specific to this menu. The menu element is the actual HTML page element that represents the menu itself. You access the menu object via the this keyword within your custom method; you access the menu element via the first parameter passed to the function.

When using HM_OnVisibilityToggle note that it is not guaranteed that the action that is being called for is strictly necessary on the menu. For example, in several places HierMenus may call for a menu to be hidden when, in fact, it is already hidden. If strict adherence to the visibility toggling is necessary for your use, then you may wish to check the current visibility status of the menu element before proceeding with your function. Alternately, you may wish to use Top/ChildUponDisplay and/or Top/ChildUponHide instead.

For further usage and implementation information, see the mini-tutorial Menu Event Hooks.

Example Method:

// write a message to the status bar 
// describing the toggling of a menu
function HM_fc_VisToggle(menuEl,show) {
   var showHide=(show)?"displayed":"hidden";
   window.status=this.MenuID+" is about to be "+showHide;
}

Example Settings:

// Ok:
HM_OnVisibilityToggle:HM_fc_VisToggle,
HM_OnVisibilityToggle:null,  // remove hook for this menu

// Incorrect:
HM_OnVisibilityToggle:"HM_fc_VisToggle",
   // do not quote function names here
HM_OnVisibilityToggle:"null", 
   // do not quote null here

Default:

null

See Also:

HM_OnMove, HM_OnCreateMenu, HM_OnMenuCreated, HM_OnItemHilite, HM_OnBuildMenus, HM_OnItemClick, HM_OnItemHover, HM_OnCreateItem, HM_OnItemCreated, HM_OnMenuOver, HM_OnMenuOut, HM_OnItemOver, HM_OnItemOut, HM_OnLink, setTrans, killTrans, Menu Event Hooks Mini-Tutorial