home / documentation / reference / hm_onitemhilite

HM_OnItemHilite

Description:

The custom (user defined) method that is called whenever HierMenus is about to highlight or dim a menu item.

Value:

JavaScript function.

Applies To:

Menu Items.

Browser Compatibility:

HM_OnItemHilite is supported in all browsers.

Parameters:

(itemEl,show,isSelected)

itemEl is the HTML element for the menu item

show is a boolean indicating whether the menu item is about to be highlighted (true) or dimmed (false).

isSelected is a boolean indicating whether the menu item is a selected menu item; i.e, if the color schemes about to be applied to the item will be the standard rollover colors (false) or the selected colors (true). Note that isSelected overrides the show setting. If isSelected is true, then the selected colors will be applied to the item regardless of the show setting.

Comments:

HM_OnItemHilite 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 item object, i.e., the internal item object that HierMenus creates to track the various unique parameters of the item itself. Thus, the this keyword, within the context of your custom function, refers directly to the item object.

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

When using HM_OnItemHilite note that it is not guaranteed that the action that is being called for is strictly necessary on the menu item. For example, in several places HierMenus may call for a menu item to be dimmed when, in fact, it is already dimmed. If strict adherence to the dimming/showing of the item is necessary for your use, then you may wish to check the current status of the item element before proceeding with your function.

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

Example Method:

// write a message to the status bar 
// describing the highlighting of a menu item
function HM_fc_ItemHilite(itemEl,show,isSelected) {
   if(isSelected) {
      window.status="Item "+this.ItemCount+" of menu "+
                    this.MenuID+" is about to be selected.";
   }
   else {
      var showHide=(show)?"highlighted":"dimmed";
      window.status="Item "+this.ItemCount+" of menu "+
                    this.MenuID+" is about to be "+showHide;
   }
}

Example Settings:

// Ok:
HM_OnItemHilite:HM_fc_ItemHilite,
HM_OnItemHilite:null,  // remove hook for this item

// Incorrect:
HM_OnItemHilite:"HM_fc_ItemHilite",
   // do not quote function names here
HM_OnItemHilite:"null", 
   // do not quote null here

Default:

null

See Also:

HM_OnVisibilityToggle, HM_OnMove, HM_OnCreateMenu, HM_OnMenuCreated, 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