You are reading 12.6.3. See this page in 13.4.1.
Titanium.Android.Menu
Extends Titanium.Proxy
The Titanium binding of an Android Options Menu.
The Menu and MenuItems APIs are used to create the action items for the action bar. Action items can appear in either the action bar or the action bar's overflow menu.
To create action items with JavaScript, assign a callback function to the activity's
onCreateOptionsMenu property.
The activity's menu object is passed in to the onCreateOptionsMenu function when the menu is created.
Use the Menu's add() method to create new action items.
In Alloy you can use <Menu> and <MenuItem> elements to create an options menu.
<Menu id="menu" platform="android">
<!-- Cannot specify node text. Use attributes only. -->
<MenuItem id="saveitem" title="Save" icon="item1.png" onClick="doSave" />
<MenuItem id="closeitem" title="Close" icon="item1.png" onClick="doClose" />
</Menu>
To switch menu items dynamically, call
invalidateOptionsMenu, which causes
the onCreateOptionsMenu callback to be called again.
Menus on Tab Groups
Menus must be added to tab groups using the tab group's activity. These changes were required to support the Android 3.0 action bar.
The TabGroup activity is available using TabGroup.activity.
However, unlike a window's activity it is not currently possible to set properties on
the tab group's activity before the tab group is opened. To add a menu to a tab group,
set the onCreateOptionsMenu property to the tab group's open event listener, and
then call invalidateOptionsMenu to force the changes to take effect.
tabGroup.addEventListener("open", function(e) {
var activity = globals.tabs.getActivity();
activity.onCreateOptionsMenu = function(e) {
var menuItem = e.menu.add({
title : "Add Task",
showAsAction : Ti.Android.SHOW_AS_ACTION_ALWAYS,
icon : "add_icon.png"
});
menuItem.addEventListener("click", function(e) {
//
});
}
activity.invalidateOptionsMenu();
});
Application Notes for Release 3.2.x and earlier
If you are using Release 3.2.x and earlier, the options menu is presented differently based on the Android version and application settings.
On Android devices prior to Android 3.0 (API level 11), the menu is always presented as an options menu, which is displayed when the Menu button is pressed.
On Android 3.0 and later, menu items can be displayed as action items in the action bar. To enable this, the application must be built with a theme that supports the action bar, such as the Holo theme. (See Android Themes in the Titanium Guides for information on setting your application's theme.)
For menu items displayed in the menu, the onCreateOptionsMenu function is called
once, and the onPrepareOptionsMenu callback function is called each
time the menu is opened. The onPrepareOptionsMenu function can be used to switch menu items dynamically.
Further Reading
See also:
-
Menus in the Android Developer Guides.
-
Action Bar in the Android Developer Guides.
-
Menu in the Android Developer Reference.
Examples
Creating a Simple Menu
This sample creates an Android menu that displays a menu item named "Item 1", which logs a debug message when clicked.
If the action bar is in use, the menu item will be displayed as an action item if there is room in the action bar.
var win = Ti.UI.createWindow({
fullscreen: true
});
var activity = win.activity;
activity.onCreateOptionsMenu = function(e){
var menu = e.menu;
var menuItem = menu.add({
title: "Item 1",
icon: "item1.png",
showAsAction: Ti.Android.SHOW_AS_ACTION_IF_ROOM
});
menuItem.addEventListener("click", function(e) {
Ti.API.debug("I was clicked");
});
};
win.open();
Creating a Dynamic Menu
This sample creates an Android menu that displays a menu item named
"Login" or "Logout", depending on the value of a loggedIn Boolean variable.
Click on the item to toggle the variable's value.
var win = Ti.UI.createWindow({
fullscreen: true
});
var LOGIN = 1, LOGOUT = 2;
var loggedIn = false;
var activity = win.activity;
activity.onCreateOptionsMenu = function(e){
var menu = e.menu;
var login = menu.add({ title: "Login", itemId: LOGIN });
login.icon = 'login.png';
login.addEventListener("click", function(e) {
loggedIn = true;
// In Android 3.0 and above we need to call invalidateOptionsMenu() for menu changes at runtime
win.activity.invalidateOptionsMenu();
});
var logout = menu.add({ title: "Logout", itemId: LOGOUT });
logout.icon = 'logout.png';
logout.addEventListener("click", function(e) {
loggedIn = false;
// In Android 3.0 and above we need to call invalidateOptionsMenu() for menu changes at runtime
win.activity.invalidateOptionsMenu();
});
};
activity.onPrepareOptionsMenu = function(e) {
var menu = e.menu;
menu.findItem(LOGIN).visible = !loggedIn;
menu.findItem(LOGOUT).visible = loggedIn;
};
win.open();
Alloy XML Markup
Previous simple menu example as an Alloy view.
Due to the way menus are created in Alloy, menus created using Alloy markup are not
displayed until the options menu is invalidated. To force menus (or action items)
to be displayed, call invalidateOptionsMenu from the open event listener of the window or tab group
where the menu is defined.
index.xml:
<Alloy>
<!-- Create a heavyweight window to use the Android menu. -->
<Window id="win" fullscreen="true" onOpen="doOpen">
<!-- The Menu tag adds the Android menu. -->
<Menu id="menu" platform="android">
<!-- Cannot specify node text. Use attributes only. -->
<MenuItem id="menuItem" title="Item 1" icon="item1.png" onClick="doClick" showAsAction="Ti.Android.SHOW_AS_ACTION_IF_ROOM" />
</Menu>
<!-- Place additional views here -->
</Window>
</Alloy>
index.js:
function doClick(e) {
Ti.API.info("Menu item clicked: " + e.source.title);
}
// Ensure menu is displayed
function doOpen(e) {
$.win.activity.invalidateOptionsMenu();
}
Properties 4
Inherited from Titanium.Proxy
The name of the API that this proxy corresponds to.
Inherited from Titanium.Proxy
Indicates if the proxy will bubble an event to its parent.
Default: true
Array of menu items in this menu.
Inherited from Titanium.Proxy
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
Methods 15
Creates a Titanium.Android.MenuItem from the passed creation options.
| Parameters | Type | Description |
|---|---|---|
| options | Object | Creation options. Supported options are itemId, groupId, title, order, actionView, checkable, checked, enabled, icon, showAsAction, titleCondensed, and visible. |
Inherited from Titanium.Proxy
Adds the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. 4 fields
|
applyProperties
since 3.0.0Inherited from Titanium.Proxy
Applies the properties to the proxy.
| Parameters | Type | Description |
|---|---|---|
| props | Dictionary | A dictionary of properties to apply. |
Clears all items from this menu.
You should release all references you have retained to Titanium.Android.MenuItem previously created.
Closes the menu, if visible.
Locates a MenuItem in this menu, by item ID or reference.
Returns the identified menu item, or null if the menu item was not located.
| Parameters | Type | Description |
|---|---|---|
| item | Number | Titanium.Android.MenuItem | Integer itemId or a reference to a |
Inherited from Titanium.Proxy
Fires a synthesized event to any registered listeners.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| event? | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. |
Returns the MenuItem at a specific index.
Returns null if no menu item exists at the specified index.
| Parameters | Type | Description |
|---|---|---|
| index | Number | Index of the menu item to return. |
Returns true if this menu has visible items.
Inherited from Titanium.Proxy
Removes the specified callback as an event listener for the named event.
| Parameters | Type | Description |
|---|---|---|
| name | String | Name of the event. |
| callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to 4 fields
|
Removes all menu items with the specified groupId.
| Parameters | Type | Description |
|---|---|---|
| groupId | Number | Group ID of items to remove. |
| Parameters | Type | Description |
|---|---|---|
| itemId | Number | Item ID of item to remove. |
Enables or disables a group of menu items identified by a groupId.
| Parameters | Type | Description |
|---|---|---|
| groupId | Number | ID of the group to enable or disable. |
| enabled | Boolean | True to enable the specified group, false to disable it. |
Shows or hides a group of menu items identified by a groupId.
| Parameters | Type | Description |
|---|---|---|
| groupId | Number | Group ID to enable or disable. |
| visible | Boolean | True to show the group, false to hide it. |
Number of items in this menu.