JavaScript client-side API JavaScript Reference: Class WL.OptionsMenu

Class WL.OptionsMenu

WL.OptionsMenu

Description:: IBM® Worklight® supplies a number of methods for manipulating the Android options menu and the Windows Phone 8, and Windows 8 apps application bar.
This section applies to Android, Windows Phone 8, and Windows 8 apps only.
The Android options menu and the Windows Phone 8, and Windows 8 apps application bar are accessible by pressing Menu on the device. IBM Worklight provides a client-side API for managing the menu and application bar.

Note:: If your application targets Android 3.0 (API level 11) or higher, WL.OptionsMenu might have no effect, depending on the device. For more information, see Creating an Options Menu in Android.

Method Summary
Method Attributes	Method Name and Description
	addItem(id, callbackFunction, title, options) Adds an item to the options menu or application bar.
	getItem(id) Returns an item.
	init(options) Initializes and enables the options menu or application bar.
	isEnabled(callback) Check whether the options menu or application bar is enabled.
	removeItem(id) Remove an item from the options menu or application bar.
	removeItems() Removes all items from the options menu or application bar.
	setEnabled(Mandatory) Enable or disable the options menu or application bar.
	setOpacity(number) Sets the opacity of the Windows Phone 8 application bar.
	setVisible(number) Make the options menu or application bar visible or invisible.

Method Detail

addItem

addItem(id, callbackFunction, title, options)

Adds an item to the options menu or application bar. Adds an item to the options menu or application bar. Can be called only after the menu is initialized. Items are placed in the menu in the order in which they are added. If you add an item with an existing ID, the new item replaces the existing one.

Parameters:

id - Mandatory string. Identifies the item.

callbackFunction - Mandatory JavaScript function. The callback function that is invoked when the user selects the item in the options menu.

title - Mandatory string. The title of the item.

options - The options parameter is mandatory, and the image property within it is also mandatory. Contains the following fields:

image
For Android, this field contains the name of the resource that contains the icon image for the item. For Windows Phone 8, and Windows 8, this field contains the path to the icon image for the item.
For Android, the image is located under the Android res/drawable* folders of the application. You can provide multiple images and place them in the drawable* folders that belong to the device densities your application supports.
For Windows Phone 8, the path starts from the folder /nativeResources/applicationBar. Do not explicitly mention this folder within the path.
For and Windows 8, the path starts from the folder /Resources/applicationBar. Do not explicitly mention this folder within the path.
The same set of images can be used for Android, Windows Phone 8, and Windows 8.
For Android, the image size depends on the density of the device. See the Android Options Menu documentation for details.
For Windows Phone 8, these images are 48 pixels by 48 pixels and have a white foreground on a transparent background that uses an alpha channel. The Application Bar colorizes the icon according to the current style settings and colored icons can cause this effect to display unpredictably.
For Windows 8, the image size is 160x80 pixel png sprite image with a transparent background. This sprite is divided into two rows of four columns, that is, 40x40 pixel cells (Each image is centered in its respective 40x40 cell). The 1st row is the normal button state, and the 2nd row is the toggled/selected state for toggle buttons. (If you don't use a toggle button with the image, you don't need the 2nd row). The columns are the rest, hover, active (pressed), and disabled states.
Enable
Optional Boolean. Defines whether the item is enabled or disabled.

Example:

// Android
WL.OptionsMenu.addItem("first", function(){alert("hello one");}, 'one', {image: 'one.png', enabled: true});

// Windows Phone 8
WL.OptionsMenu.addItem("first", function(){alert("hello one");}, one', {image: one.png', enabled: true});

// Windows 8
WL.OptionsMenu.addItem("first", function(){alert("hello one");}, one', {image: one.png', enabled: true});

getItem

getItem(id)

Returns an item. Returns the item with the specified ID. You can use Item methods to change the properties of the item.

Parameters:: id - Mandatory string. The ID of the required item.

Returns:: An Item object. If the specified ID is not found, the method returns null.
var itemOne = WL.OptionsMenu.getItem('first');

init

init(options)

Initializes and enables the options menu or application bar. Initializes the options menu or application bar and enables it. Must be called before it is used. On Windows Phone 8, the default opacity of the application bar is 1.0 (opaque).

Parameters:: options - A JSON block. Options for customizing the options menu init state opcaity - a decimal number between 0.0 and 1.0 that represents the opacity factor. 1.0 is fully opaque, 0.0 is fully transparent.

Example:

WL.OptionsMenu.init({opacity: 0.5});

Note:: JSON block is applicable only for Windows Phone 8. Default value of opacity is 1.0.

isEnabled

isEnabled(callback)

Check whether the options menu or application bar is enabled. Returns whether the options menu or application bar is enabled. Can be called only after the menu is initialized.

Parameters:: callback - a callback method that accepts the state enabled as a parameter.

Returns:

In Android environments: true if the menu is enabled; false if it is not.
In Windows Phone 8 environments: none. If the callback is null or undefined, the method fails and sends a message to the debugger console.

Example:

WL.OptionsMenu.isEnabled(isEnabledCallback);

function isEnabledCallback(enabled) {
	if (enabled) {
		// do something
	}
}

removeItem

removeItem(id)

Remove an item from the options menu or application bar. Removes the item with the indicated ID from the options menu or application bar. Can be called only after the menu is initialized.
If no item is found with the specified ID, nothing happens.

Parameters:: id - Mandatory string. Identifies the item to be removed.

removeItems

removeItems()

Removes all items from the options menu or application bar. Removes all items from the options menu or application bar. Can be called only after the menu is initialized.

setEnabled

setEnabled(Mandatory)

Enable or disable the options menu or application bar. This method enables or disables the options menu or application bar. When the menu or bar is disabled, it might still be visible, but all its items are disabled. The function disables all the items but does not change the enabled state of each Item.

Parameters:

Mandatory - Boolean.

true: Enable the menu
false: Disable the menu

setOpacity

setOpacity(number)

Sets the opacity of the Windows Phone 8 application bar. Sets the value for the application bar opacity.

Parameters:: number - Mandatory. Float between 0.0 and 1.0. 0.0 is transparent; 1.0 is opaque.
When the application bar is not opaque, Windows Phone 8 devices display it as an overlay on the application.

Note:: This method is applicable only for the Windows Phone 8 application bar.

setVisible

setVisible(number)

Make the options menu or application bar visible or invisible. Determines whether the options menu or application bar is visible. Can be called only after the options menu is initialized.

Parameters:

number - Mandatory Boolean.

true: Makes the menu visible on pressing Menu
false: Makes the menu invisible

Note:: This method is not supported on Windows 8.