home / documentation / reference / killtrans

killTrans

Description:

The custom (user defined) method that completes (finishes) a menu transition.

Value:

JavaScript function.

Applies To:

Menus.

Browser Compatibility:

killTrans is not supported in Netscape 4.x or Internet Explorer 4.x.

Parameters:

None.

Comments:

killTrans 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 can be accessed through the eMenu property of the menu object (this.eMenu).

Using killTrans (and its companion setTrans) is somewhat different from using other Menu Event Hooks, in that a call to setTrans replaces (i.e., overrides) a default activity of HierMenus instead of simply indicating that a particular HierMenus activity is about to take place. (The differing naming of the hooks, i.e., killTrans as opposed to HM_OnKillTrans is symbolic of this substantial difference. Instead of simply hooking an existing HierMenus action, you are replacing it.) Specifically, setTrans replaces the normal visibility toggle of a menu, allowing you to display or hide the menu via your own custom methods. killTrans immediately finishes the transition begun with setTrans. HierMenus' own sliding menus are implemented via setTrans and killTrans hooks.

Needless to say, because this event hook replaces a key function of HierMenus, you should implement it carefully. Only advanced developers should seek to tackle the creation of custom setTrans and killTrans methods.

killTrans is intended to complete your custom menu transition, immediately resetting the menu to the state it would have been in if no transition were applied at all. (Normally, this simply means that you should call the menu's visibilityToggle method passing to it the same show value that was passed to your setTrans method). Since HierMenus never knows what the status of a particular custom menu transition is, it calls killTrans at several places throughout the script to ensure that the current menu transition is complete (before, for example, attempting to move the menu as the result of a window resize or launch a new display transition on the menu). Therefore you must define killTrans so that it first checks its own transition status (which you can control) and does nothing if your menu transition is already complete. For a more detailed look at how custom transitions are created and implemented, see the mini-tutorial Custom Transitions.

Example Method:

See the mini-tutorial Custom Transitions for an extended example of setTrans and killTrans methods.

Example Settings:

// Ok:
killTrans:HM_f_SetSlide,
killTrans:null,  // remove hook for this menu

// Incorrect:
killTrans:"HM_f_SetSlide",
   // do not quote function names here
killTrans:"null", 
   // do not quote null here

Default:

null

See Also:

HM_OnVisibilityToggle, 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, Custom Transitions Mini-Tutorial, Menu Event Hooks Mini-Tutorial