# Titanium.Android.Menu

> The Titanium binding of an Android Options Menu.

- Source: https://titaniumsdk.com/docs/sdk/12.7.0/Titanium.Android.Menu
- Titanium SDK version: 12.7.0
- Kind: proxy
- Platforms: Android
- Since: Titanium SDK 1.5
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

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](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onCreateOptionsMenu) property.
The activity's menu object is passed in to the `onCreateOptionsMenu` function when the menu is created.
Use the Menu's [add()](https://titaniumsdk.com/docs/sdk/Titanium.Android.Menu.md#add) method to create new action items.

In Alloy you can use `<Menu>` and `<MenuItem>` elements to create an options menu.

``` xml
<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](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#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](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#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.

``` js
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](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Deep_Dives/Android_UI_Components_and_Conventions/Android_Themes.html) 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](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#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](https://developer.android.com/guide/topics/ui/menus.html) in the
    Android Developer Guides.

*   [Action Bar](https://developer.android.com/guide/topics/ui/actionbar.html) in
    the Android Developer Guides.

*   [Menu](https://developer.android.com/reference/android/view/Menu.html)
    in the Android Developer Reference.

## Example: 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.

``` js
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();
```

## Example: 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.

``` js
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();
```

## Example: 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:
``` 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:
``` js
function doClick(e) {
    Ti.API.info("Menu item clicked: " + e.source.title);
}

// Ensure menu is displayed
function doOpen(e) {
    $.win.activity.invalidateOptionsMenu();
}
```

## Properties

### items

- Type: Array<Titanium.Android.MenuItem>
- Platforms: Android
- Permission: read-only

Array of menu items in this menu.

## Methods

### add

- Platforms: Android

Creates a [Titanium.Android.MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) from the passed creation options.

Parameters:

- `options` (Object): Creation options. Supported options are [itemId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#itemId), [groupId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#groupId), [title](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#title), [order](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#order), [actionView](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#actionView), [checkable](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#checkable), [checked](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#checked), [enabled](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#enabled), [icon](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#icon), [showAsAction](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#showAsAction), [titleCondensed](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#titleCondensed), and [visible](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#visible).

Returns: Titanium.Android.MenuItem

### clear

- Platforms: Android

Clears all items from this menu.

You should release all references you have retained to [Titanium.Android.MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) previously created.

### close

- Platforms: Android

Closes the menu, if visible.

### findItem

- Platforms: Android

Locates a [MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) in this menu, by item ID or reference.

Returns the identified menu item, or `null` if the menu item was not located.

Parameters:

- `item` (Number | Titanium.Android.MenuItem): Integer [itemId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#itemId) or a reference to a `MenuItem` object.

Returns: Titanium.Android.MenuItem

### getItem

- Platforms: Android

Returns the [MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) at a specific index.

Returns `null` if no menu item exists at the specified index.

Parameters:

- `index` (Number): Index of the menu item to return.

Returns: Titanium.Android.MenuItem

### hasVisibleItems

- Platforms: Android

Returns `true` if this menu has visible items.

Returns: Boolean

### removeGroup

- Platforms: Android

Removes all menu items with the specified
[groupId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#groupId).

Parameters:

- `groupId` (Number): Group ID of items to remove.

### removeItem

- Platforms: Android

Removes a specific [MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) identified by its
[itemId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#itemId).

Parameters:

- `itemId` (Number): Item ID of item to remove.

### setGroupEnabled

- Platforms: Android

Enables or disables a group of menu items identified by a
[groupId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#groupId).

Parameters:

- `groupId` (Number): ID of the group to enable or disable.
- `enabled` (Boolean): True to enable the specified group, false to disable it.

### setGroupVisible

- Platforms: Android

Shows or hides a group of menu items identified by a
[groupId](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md#groupId).

Parameters:

- `groupId` (Number): Group ID to enable or disable.
- `visible` (Boolean): True to show the group, false to hide it.

### size

- Platforms: Android

Number of items in this menu.

Returns: Number

## Inherited members

7 members are inherited. Each is documented on the type that declares it.

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.7.0/Titanium.Proxy.md): `addEventListener`, `apiName`, `applyProperties`, `bubbleParent`, `fireEvent`, `lifecycleContainer`, `removeEventListener`

---

- This corpus documents Titanium SDK 13.4.1. Anything here that does not name a version describes 13.4.1.
- Titanium is maintained by TiDev. The Appcelerator toolchain is retired: there is no `appc` CLI, no Appcelerator Studio and no hosted build service. The supported CLI is `titanium` on npm, invoked as `ti`.