Reference « Documentation

Coding Reference for jsDOMenu Version 1.3

This reference describes the methods and fields available in jsDOMenu.

Global public constructors
Public methods for jsDOMenu()
Public methods for menuObj.items["itemName"] (or menuObj.items.itemName)
Global public methods
Global public fields

Global public constructors

jsDOMenu()

Create a new menu.

Syntax

menuObj = new jsDOMenu(width, mode, id, alwaysVisible, className);

Arguments

width - Required. Integer that specifies the width of the menu. Default unit is "px".

mode - Optional. String that specifies the mode of the menu. Defaults to "cursor". Allowed values are "cursor", "absolute", "fixed", and "static". If the mode = "static", you must also specify an unique id.

A menu is a cursor menu if any of the following is true:

It is a main menu that shows at the position of the cursor, i.e., it is a pop-up main menu.
It is a submenu and its main menu is a cursor menu.

A menu is an absolute menu if any of the following is true:

It is a main menu that is fixed at a particular position with respect to the document.
It is a submenu and its main menu is an absolute or static menu.

A menu is a fixed menu if any of the following is true:

It is a main menu that is fixed at a particular position with respect to the window.
It is a submenu and its main menu is a fixed menu.

A menu is a static menu if it is a main menu that is fixed at a particular position with respect to the document structure.

Do not confuse absolute menus with fixed menus. An absolute menu will move together with the page when you scroll. If you scroll up/down enough, it will be totally out of view. On the other hand, a fixed menu will not move with the page when you scroll. It will always be visible regardless of how much you scroll (provided it is positioned within the window when the page loads).

In addition, a static menu is fixed at a particular position with respect to the document structure, i.e. the position of the menu will "flow" with the document when the browser is resized. Thus, it is not required to call methods like setX(), moveTo(), etc to position the menu.

id - Optional, except when mode = "static". String that specifies the id of the element that will contain the menu. This argument is required when mode = "static". It is recommended that the element you specify is an empty DIV tag. For example:

<div id="staticMenu"></div>

Note that the id must be unique.

alwaysVisible - Optional. Boolean that specifies whether the menu is always visible. Defaults to false. If set to true, the menu will always be visible, unless you execute its hide() method to hide it.

className - Optional. String that specifies the CSS class selector for the menu. Defaults to "jsdomenudiv". The class selector "jsdomenudiv" is defined in the theme file, e.g. classic.css.

Remarks

The method signature for this constructor has been changed compared with the previous version (v1.2.1).

You can access the HTML element object of the menu using the menuObj field. For example, menuObj.menuObj.style holds the style object of the HTML element.

menuItem()

Create a new menu item.

Syntax

menuItemObj = new menuItem(displayText, itemName, actionOnClick, 
                           enabled, className, classNameOver);

Arguments

displayText - Required. String that specifies the text to be displayed on the menu item. If displayText is "-", a menu separator will be created instead.

itemName - Optional. String that specifies the name of the menu item. Defaults to "" (no name). You should set this argument only if you need to reference this menu item later on.

actionOnClick - Optional. String that specifies the action to be done when the menu item is being clicked. Defaults to "" (no action).

There are two types of actions allowed:

Link: Loads a new page on click. The value of actionOnClick is a URL.
Code: Execute Javascript code(s) on click. The value of actionOnClick is the code(s) to be executed.

To distinguish between the two types, prefix "link:" or "code:" respectively to the value. For example, "code:alert('Hello World!');" instead "alert('Hello World!');". For links, prefixing "link:" is optional, as any prefix other than "code:" will be intepreted as a link.

enabled - Optional. Boolean that specifies whether the menu item is enabled/disabled. Defaults to true. The default value can also be set using "".

className - Optional. String that specifies the CSS class selector for the menu item. Defaults to "jsdomenuitem". The default value can also be set using "". The class selector "jsdomenuitem" is defined in the theme file, e.g. classic.css.

classNameOver - Optional. String that specifies the CSS class selector for the menu item when the cursor is over it. Defaults to "jsdomenuitemover". The default value can also be set using "". The class selector "jsdomenuitemover" is defined in the theme file, e.g. classic.css.

Remarks

If you need to define any argument, you must also define the arguments before it. For example, if you need to define the third argument, but not the second, you still need to set the second argument to "" (default value).

The following codes are equivalent to the above:

menuItemObj = new menuItem(displayText);
menuItemObj.itemName = itemName;
menuItemObj.actionOnClick = actionOnClick;
menuItemObj.enabled = enabled;
menuItemObj.className = className;
menuItemObj.classNameOver = classNameOver;

You should only define the fields that need to be changed.

addMenuItem()

Add a new menu item to the menu.

Syntax

menuObj.addMenuItem(menuItemObj);

Argument

menuItemObj - Required. Menu item that is going to be added to the menu.

Remarks

You can access the HTML element object of the menu item using the items field. For example, menuObj.items["itemName"].style (or menuObj.items.itemName.style) holds the style object of the HTML element, where "itemName" is the value of itemName field of the menuItemObj added.

setClassName()

Set the class name of the menu.

Syntax

menuObj.setClassName(className);

Argument

className - Required. String that specifies the CSS class selector for the menu.

Remarks

The following code is equivalent to the above:

menuObj.menuObj.className = className;

setMode()

Set the mode of the menu.

Syntax

menuObj.setMode(mode);

Argument

mode - Required. String that specifies the mode of the menu. Allowed values are "cursor", "absolute", and "fixed".

Remarks

If you change the mode of any menu, it is recommended that you change the mode of all its submenus as well.

setAlwaysVisible()

Set whether the menu is always visible.

Syntax

menuObj.setAlwaysVisible(alwaysVisible);

Argument

alwaysVisible - Required. Boolean that specifies whether the menu is always visible. If set to true, the menu will always be visible, unless you execute its hide() method to hide it.

Remarks

The following code is equivalent to the above:

menuObj.menuObj.alwaysVisible = alwaysVisible;

show()

Show the menu.

Syntax

menuObj.show();

Argument

None

Remarks

The following code is equivalent to the above:

menuObj.menuObj.style.visibility = "visible";

hide()

Hide the menu.

Syntax

menuObj.hide();

Argument

None

Remarks

setX()

Set the x-coordinate of the menu.

Syntax

menuObj.setX(x);

Argument

x - Required. Integer that specifies the x-coordinate of the menu. Default unit is "px".

Remarks

setY()

Set the y-coordinate of the menu.

Syntax

menuObj.setY(y);

Argument

y - Required. Integer that specifies the y-coordinate of the menu. Default unit is "px".

Remarks

moveTo()

Move the menu to the x-coordinate specified by the first argument and the y-coordinate specified by the second argument.

Syntax

menuObj.moveTo(x, y);

Arguments

x - Required. Integer that specifies the x-coordinate of the menu. Default unit is "px".

y - Required. Integer that specifies the y-coordinate of the menu. Default unit is "px".

Remarks

moveBy()

Move the menu towards left by the amount specified by the first argument, and away from top by the amount specified by the second argument. If you want to move the menu towards right, or away from bottom, specify a negative value respectively.

Syntax

menuObj.moveBy(x, y);

Arguments

x - Required. Integer that specifies how much left/right the menu will move. Default unit is "px".

y - Required. Integer that specifies how much top/bottom the menu will move. Default unit is "px".

Remarks

setAllExceptFilter()

Set the filter such that the menu will show up only if the region that is being clicked/right clicked is not specified in the filter.

Syntax

menuObj.setAllExceptFilter(filter);

Argument

filter - Required. Array that specifies the regions where the menu will not show up when clicked/right click. Each array element is made up of two parts, separated by ".". The first part is any HTML tag, the second part is the id of the tag. The "*" wildcard can be used.

For example:

filter = new Array("A.*", "IMG.*");

means that the menu will show up if the region that is being clicked/right clicked is not anchor tag (<a>) or image tag (<img>).

filter = new Array("*.nomenu");

means that the menu will show up if the region that is being clicked/right clicked is not having id = "nomenu".

filter = new Array("P.nomenu");

means that the menu will show up if the region that is being clicked/right clicked is not paragraph tag (<p>) having id = "nomenu".

Remarks

The filter is case-insensitive. This method is used mainly for cursor menus. Calling this method will also reset the noneExceptFilter field to an empty array.

setNoneExceptFilter()

Set the filter such that the menu will show up only if the region that is being clicked/right clicked is specified in the filter.

Syntax

menuObj.setNoneExceptFilter(filter);

Argument

filter - Required. Array that specifies the regions where the menu will show up when clicked/right click. Each array element is made up of two parts, separated by ".". The first part is any HTML tag, the second part is the id of the tag. The "*" wildcard can be used.

For example:

filter = new Array("A.*", "IMG.*");

means that the menu will show up only if the region that is being clicked/right clicked is anchor tag (<a>) or image tag (<img>).

filter = new Array("*.menu");

means that the menu will show up only if the region that is being clicked/right clicked is having id = "menu".

filter = new Array("P.menu");

means that the menu will show up if the region that is being clicked/right clicked is paragraph tag (<p>) having id = "menu".

Remarks

The filter is case-insensitive. This method is used mainly for cursor menus. Calling this method will also reset the allExceptFilter field to an empty array.

setBorderWidth()

Set the border width of the menu.

Syntax

menuObj.setBorderWidth(width);

Argument

width - Required. Integer that specifies the border width of the menu. Default unit is "px".

Remarks

This method may be deprecated in future versions. Therefore, try not to use it in this version.

It is recommended that you set the border width using stylesheet instead.

The following code is equivalent to the above:

menuObj.menuObj.style.borderWidth = width + "px";

Public methods for menuObj.items["itemName"] (or menuObj.items.itemName)

setClassName()

Set the class name of the menu item.

Syntax

menuObj.items["itemName"].setClassName(className);

Argument

className - Required. String that specifies the CSS class selector for the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setClassName(className);

setClassNameOver()

Set the class name of the menu item when the cursor is over the menu item.

Syntax

menuObj.items["itemName"].setClassNameOver(classNameOver);

Argument

classNameOver - Required. String that specifies the CSS class selector for the menu item when the cursor is over the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setClassNameOver(classNameOver);

This method is not available if the menu item is a menu separator.

setDisplayText()

Set the display text of the menu item.

Syntax

menuObj.items["itemName"].setDisplayText(displayText);

Argument

displayText - Required. String that specifies the text to be displayed on the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setDisplayText(displayText);

This method is not available if the menu item is a menu separator.

setSubMenu()

Set the menu that will show up when the cursor is over the menu item.

Syntax

menuObj.items["itemName"].setSubMenu(menuObj);

Argument

menuObj - Required. Menu that will show up when the cursor is over the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setSubMenu(menuObj);

This method is not available if the menu item is a menu separator.

setArrowClassName()

Set the class name of the arrow.

Syntax

menuObj.items["itemName"].setArrowClassName(className);

Argument

className - Required. String that specifies the CSS class selector for the arrow.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setArrowClassName(className);

This method is available only if the setSubMenu() method has been called to set a submenu for the menu item.

setArrowClassNameOver()

Set the class name of the arrow when the cursor is over the menu item.

Syntax

menuObj.items["itemName"].setArrowClassNameOver(className);

Argument

className - Required. String that specifies the CSS class selector for the arrow when the cursor is over the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setArrowClassNameOver(className);

This method is available only if the setSubMenu() method has been called to set a submenu for the menu item.

showIcon()

Show the icon before the display text.

Syntax

menuObj.items["itemName"].showIcon(className, classNameOver);

Arguments

className - Required. String that specifies the CSS class selector for the icon.

classNameOver - Optional. String that specifies the CSS class selector for the icon when the cursor is over the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.showIcon(className, classNameOver);

This method is not available if the menu item is a menu separator.

setIconClassName()

Set the class name of the icon.

Syntax

menuObj.items["itemName"].setIconClassName(className);

Argument

className - Required. String that specifies the CSS class selector for the icon.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setIconClassName(className);

This method is available only if the showIcon() method has been called to show the icon before the display text.

setIconClassNameOver()

Set the class name of the icon when the cursor is over the menu item.

Syntax

menuObj.items["itemName"].setIconClassNameOver(classNameOver);

Argument

classNameOver - Required. String that specifies the CSS class selector for the icon when the cursor is over the menu item.

Remarks

The following code is equivalent to the above:

menuObj.items.itemName.setIconClassNameOver(classNameOver);

This method is available only if the showIcon() method has been called to show the icon before the display text.

Global public methods

initjsDOMenu()

Method to call before creating the menus.

Syntax

initjsDOMenu();

Argument

None.

Remarks

This method is attached to the body tag (<body>) as a onload event handler. Therefore, you should not call this method again.

createjsDOMenu()

Method that contains the codes to create and customize the menus.

Syntax

createjsDOMenu();

Argument

None.

Remarks

This method is found in jsdomenu.inc.js. It will be called by the initjsDOMenu() method. Therefore, you should not call this method again.

setPopUpMenu()

Set the menu to be the pop-up menu.

Syntax

setPopUpMenu(menuObj);

Argument

menuObj - Required. Menu that specifies the pop-up menu.

Remarks

This method should be called only if you are using cursor menus.

activatePopUpMenuBy()

Set how the pop-up menu is shown/hidden.

Syntax

activatePopUpMenuBy(showValue, hideValue);

Argument

showValue - Required. Integer that specifies how the pop-up menu is shown.

hideValue - Required. Integer that specifies how the pop-up menu is hidden.

Allowed values for showValue/hideValue are:

0: Shows/Hides the cursor menu by left click only.
1: Shows/Hides the cursor menu by right click only.
2: Shows/Hides the cursor menu by left or right click.

Remarks

Certain browsers (e.g. Opera) do not support the right click feature.

This method should be called only if you are using cursor menus.

hideAllMenus()

Hide all menus, except those with alwaysVisible = true.

Syntax

hideAllMenus();

Argument

None.

Remarks

This method may be useful if you wish to control how the menus hide.

hideCursorMenus()

Hide all menus with mode = "cursor", except those with alwaysVisible = true.

Syntax

hideCursorMenus();

Argument

None.

Remarks

This method may be useful if you wish to control how the menus hide.

hideVisibleMenus()

Hide all menus with mode = "absolute" or mode = "fixed", except those with alwaysVisible = true.

Syntax

hideVisibleMenus();

Argument

None.

Remarks

This method may be useful if you wish to control how the menus hide.

hideMenus()

Hide the menu and all its submenus.

Syntax

hideMenus(menuObj);

Argument

menuObj - Required. Menu that specifies the menu and all its submenus to be hidden.

Remarks

This method may be useful if you wish to control how the menus hide.

Global public fields

You can define the following global public fields in jsdomenu.config.js to override the default values.

allExceptFilter

Array that specifies the regions where the menu will not show up if clicked/right clicked. Each array element is made up of two parts, separated by ".". The first part is any HTML tag, the second part is the id of the tag. The "*" wildcard can be used.

Default Value

var allExceptFilter = new Array("A.*", 
                                "BUTTON.*", 
                                "IMG.*", 
                                "INPUT.*", 
                                "OBJECT.*", 
                                "OPTION.*", 
                                "SELECT.*", 
                                "TEXTAREA.*");

Remarks

If both allExceptFilter and noneExceptFilter are not empty, the value of allExceptFilter will be used.

noneExceptFilter

Array that specifies the regions where the menu will show up if clicked/right clicked. Each array element is made up of two parts, separated by ".". The first part is any HTML tag, the second part is the id of the tag. The "*" wildcard can be used.

Default Value

var noneExceptFilter = new Array();

Remarks

If both allExceptFilter and noneExceptFilter are not empty, the value of allExceptFilter will be used.

menuClassName

String that specifies the CSS class selector for the menu.

Default Value

var menuClassName = "jsdomenudiv";

Remarks

The class selector "jsdomenudiv" is defined in the theme file, e.g. classic.css.

menuItemClassName

String that specifies the CSS class selector for the menu item.

Default Value

var menuItemClassName = "jsdomenuitem";

Remarks

The class selector "jsdomenuitem" is defined in the theme file, e.g. classic.css.

menuItemClassNameOver

String that specifies the CSS class selector for the menu item when the cursor is over it.

Default Value

var menuItemClassNameOver = "jsdomenuitemover";

Remarks

The class selector "jsdomenuitemover" is defined in the theme file, e.g. classic.css.

sepClassName

String that specifies the CSS class selector for the menu separator.

Default Value

var sepClassName = "jsdomenusep";

Remarks

The class selector "jsdomenusep" is defined in the theme file, e.g. classic.css.

arrowClassName

String that specifies the CSS class selector for the arrow.

Default Value

var arrowClassName = "jsdomenuarrow";

Remarks

The class selector "jsdomenuarrow" is defined in the theme file, e.g. classic.css.

arrowClassNameOver

String that specifies the CSS class selector for the arrow when the cursor is over it.

Default Value

var arrowClassNameOver = "jsdomenuarrowover";

Remarks

The class selector "jsdomenuarrowover" is defined in the theme file, e.g. classic.css.

menuMode

String that specifies the default mode of the menus.

Default Value

var menuMode = "cursor";

Remarks

Allowed values are "cursor", "absolute", "fixed", and "static".

menuBorderWidth

Integer that specifies the border width of the menu. Default unit is "px".

Default Value

var menuBorderWidth = 2;

Remarks

This field may be deprecated in future versions. Therefore, try not to use it in this version.

Safari will use the value of this field to render the menus when the page loads, and disregard the value set in the stylesheet. Other Gecko-based browsers like Mozilla Firefox or Microsoft Internet Explorer will use the value set in the stylesheet to render the menus when the page loads, and disregard the value of this field.

View the Example page to see a simple example of how to create jsDOMenu.

Back to Documentation

Compiled on 16 January 2005.

The latest version is available at http://www.tohzhiqiang.per.sg/projects/jsdomenu/docs/reference.php.

Reference « Documentation

Coding Reference for jsDOMenu Version 1.3

Global public constructors

jsDOMenu()

Syntax

Arguments

Remarks

menuItem()

Syntax

Arguments

Remarks

Public methods for jsDOMenu()

addMenuItem()

Syntax

Argument

Remarks

setClassName()

Syntax

Argument

Remarks

setMode()

Syntax

Argument

Remarks

setAlwaysVisible()

Syntax

Argument

Remarks

show()

Syntax

Argument

Remarks

hide()

Syntax

Argument

Remarks

setX()

Syntax

Argument

Remarks

setY()

Syntax

Argument

Remarks

moveTo()

Syntax

Arguments

Remarks

moveBy()

Syntax

Arguments

Remarks

setAllExceptFilter()

Syntax

Argument

Remarks

setNoneExceptFilter()

Syntax

Argument

Remarks

setBorderWidth()

Syntax

Argument

Remarks

Public methods for menuObj.items["itemName"] (or menuObj.items.itemName)

setClassName()

Syntax

Argument

Remarks

setClassNameOver()

Syntax

Argument

Remarks

setDisplayText()

Syntax

Argument

Remarks

setSubMenu()

Syntax

Argument