home / documentation / reference / settrans

setTrans

Description:

The custom (user defined) method that implements (begins) a menu transition.

Value:

JavaScript function.

Applies To:

Menus.

Browser Compatibility:

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

Parameters:

(show)

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

Comments:

setTrans 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 setTrans (and its companion killTrans) 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., setTrans as opposed to HM_OnSetTrans 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. 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.

setTrans is intended to setup your custom menu transition, saving any necessary data and preparing to execute your menu animation. For a more detailed look at how custom transitions are created and implemented, see the mini-tutorial Custom Transitions.

When using custom transitions, the Internet Explorer specific transitions (defined with IEShowTransition and/or IEHideTransition) are ignored by HierMenus. If you wish to use them, you will need to either build the functionality into your own transition logic, or conditionally set the setTrans and killTrans parameters based on the browser. For example:

setTrans:(window.HM_IE55)?null:HM_f_SetSlide,

Example Method:

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

Example Settings:

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

// Incorrect:
setTrans:"HM_f_SetSlide",
   // do not quote function names here
setTrans:"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, IEHideTransition, IEShowTransition, HM_OnLink, killTrans, Custom Transitions Mini-Tutorial, Menu Event Hooks Mini-Tutorial