Titanium.Android.Menu

> Titanium.Android.Menu

The Titanium binding of an Android Options Menu.

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.)

To determine how an action item is displayed, set showAsAction and optionally actionView when creating a menu item.

Creating Menu Items

To create menu 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.

In Alloy you can use

and 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>

You must call invalidateOptionsMenu from the open event listener of the window or tab group where the menu is defined.

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.

When the action bar is in use, the menu is considered to be always open and prepareOptionsMenu is never called. To switch menu items dynamically, call invalidateOptionsMenu. This causes the createOptionsMenu to be called again.

Menus on Tab Groups

Prior to Titanium 3.0, menu items could be added to the individual windows of a tab group.

Starting in Titanium 3.0, 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.getActivity. 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();
});

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.setIcon("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.setIcon("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).setVisible(!loggedIn);
  menu.findItem(LOGOUT).setVisible(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.invalidateOptionsMenu();
}

  • 1.5
Defined By

Properties

apiName : Stringreadonly

The name of the API that this proxy corresponds to.

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Button returns Ti.UI.Button.

  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
Indicates if the proxy will bubble an event to its parent. ...

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

  • 3.0
  • 3.0
  • 3.0
Titanium.Android.Menu
items : Titanium.Android.MenuItem[]readonly

Array of menu items in this menu.

Array of menu items in this menu.

Defined By

Methods

Titanium.Android.Menu
( options ) : Titanium.Android.MenuItem
Creates a Titanium.Android.MenuItem from the passed creation options. ...

Creates a Titanium.Android.MenuItem from the passed creation options.

Parameters

Returns

( name, callback ) : void
Adds the specified callback as an event listener for the named event. ...

Adds the specified callback as an event listener for the named event.

Parameters

  • name : String

    Name of the event.

  • callback : Callback<Object>

    Callback function to invoke when the event is fired.

Returns

  • void
Applies the properties to the proxy. ...

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

  • 3.0
  • 3.3
  • 3.0
  • 3.0
  • 3.0
  • 3.1

Parameters

  • props : Dictionary

    A dictionary of properties to apply.

Returns

  • void
Titanium.Android.Menu
( ) : void
Clears all items from this menu. ...

Clears all items from this menu.

You should release all references you have retained to Titanium.Android.MenuItem previously created.

Returns

  • void
Titanium.Android.Menu
( ) : void
Closes the menu, if visible. ...

Closes the menu, if visible.

Returns

  • void
Titanium.Android.Menu
( item ) : Titanium.Android.MenuItem
Locates a MenuItem in this menu, by item ID or reference. ...

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

Returns

( name, event ) : void
Fires a synthesized event to any registered listeners. ...

Fires a synthesized event to any registered listeners.

Parameters

  • 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

  • void
Gets the value of the apiName property. ...

Gets the value of the apiName property.

  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2
  • 3.2

Returns

  • String
Gets the value of the bubbleParent property. ...

Gets the value of the bubbleParent property.

  • 3.0
  • 3.0
  • 3.0

Returns

  • Boolean
Titanium.Android.Menu
( index ) : Titanium.Android.MenuItem
Returns the MenuItem at a specific index. ...

Returns the MenuItem 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.Menu
( ) : Titanium.Android.MenuItem[]
Gets the value of the items property. ...

Gets the value of the items property.

Returns

Titanium.Android.Menu
( ) : Boolean
Returns true if this menu has visible items. ...

Returns true if this menu has visible items.

Returns

  • Boolean
( name, callback ) : void
Removes the specified callback as an event listener for the named event. ...

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

  • name : String

    Name of the event.

  • callback : Callback<Object>

    Callback function to remove. Must be the same function passed to addEventListener.

Returns

  • void
Titanium.Android.Menu
( groupId ) : void
Removes all menu items with the specified groupId. ...

Removes all menu items with the specified groupId.

Parameters

  • groupId : Number

    Group ID of items to remove.

Returns

  • void
Titanium.Android.Menu
( itemId ) : void
Removes a specific MenuItem identified by its itemId. ...

Removes a specific MenuItem identified by its itemId.

Parameters

  • itemId : Number

    Item ID of item to remove.

Returns

  • void
( bubbleParent ) : void
Sets the value of the bubbleParent property. ...

Sets the value of the bubbleParent property.

  • 3.0
  • 3.0
  • 3.0

Parameters

  • bubbleParent : Boolean

    New value for the property.

Returns

  • void
Titanium.Android.Menu
( groupId, enabled ) : void
Enables or disables a group of menu items identified by a groupId. ...

Enables or disables a group of menu items identified by a groupId.

Parameters

  • groupId : Number

    ID of the group to enable or disable.

  • enabled : Boolean

    True to enable the specified group, false to disable it.

Returns

  • void
Titanium.Android.Menu
( groupId, visible ) : void
Shows or hides a group of menu items identified by a groupId. ...

Shows or hides a group of menu items identified by a groupId.

Parameters

  • groupId : Number

    Group ID to enable or disable.

  • visible : Boolean

    True to show the group, false to hide it.

Returns

  • void
Titanium.Android.Menu
( ) : Number
Number of items in this menu. ...

Number of items in this menu.

Returns

  • Number