unreleased

Versionmainunreleased

Titanium.Android.MenuItem

proxyAndroidsince 1.5

The Titanium binding of an Android menu item.

As of Release 3.3.0, the Menu and MenuItem APIs are used to create action items for the action bar. Prior to Release 3.3.0, the APIs could also be used to customize the Options Menu.

In JavaScript, use the Menu's add() method to create new action items.

In Alloy you can define <MenuItem> elements inside a <Menu> element.

<Menu id="menu" platform="android">
    <MenuItem id="saveitem" title="Save" icon="item1.png" onClick="doSave" />
    <MenuItem id="closeitem" title="Close" icon="item1.png" onClick="doClose" />
</Menu>

Action items can appear in either the action bar or the action bar's overflow menu. To determine how an action item is displayed, set showAsAction.

You can optionally customize the look of action items using the actionView property.

See the Titanium.Android.Menu reference page for additional code examples.

Properties 19

accessibilityHint

Stringsince 8.3.0

Briefly describes what performing an action (such as a click) on the view will do.

Value of this property is concatenated together with Titanium.Android.MenuItem.accessibilityLabel and Titanium.Android.MenuItem.accessibilityValue in the order: accessibilityLabel, accessibilityValue, accessibilityHint. The concatenated value is then passed as the argument to the native MenuItemCompat.setContentDescription method.

Default: null

accessibilityLabel

Stringsince 8.3.0

A succinct label identifying the view for the device's accessibility service.

Value of this property is concatenated together with Titanium.Android.MenuItem.accessibilityValue and Titanium.Android.MenuItem.accessibilityHint in the order: accessibilityLabel, accessibilityValue, accessibilityHint. The concatenated value is then passed as the argument to the native MenuItemCompat.setContentDescription method.

Default: null

accessibilityValue

Stringsince 8.3.0

A string describing the value (if any) of the view for the device's accessibility service.

Value of this property is concatenated together with Titanium.Android.MenuItem.accessibilityLabel and Titanium.Android.MenuItem.accessibilityHint in the order: accessibilityLabel, accessibilityValue, accessibilityHint. The concatenated value is then passed as the argument to the native MenuItemCompat.setContentDescription method.

Default: null

actionView

Titanium.UI.Viewsince 3.0.0

Custom view that replaces the default menu item button.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 3.0 (API level 11) and greater.

In order to display the custom view, set the item's showAsAction property to either Titanium.Android.SHOW_AS_ACTION_ALWAYS or Titanium.Android.SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW.

Since Alloy 1.6.0, you can specify this property using the <ActionView> element as a child of the <MenuItem> element, for example:

<Alloy>
    <Window>
        <Menu>
            <MenuItem showAsAction="Ti.Android.SHOW_AS_ACTION_ALWAYS" title="Search">
                <ActionView>
                    <SearchView ns="Ti.UI.Android" hintText="Type Something"/>
                </ActionView>
            </MenuItem>
        </Menu>
    </Window>
</Alloy>

actionViewExpanded

Booleansince 3.0.0read-only

True if this menu item's action view has been expanded.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 4.0 (API level 14) and greater.

apiName

Stringsince Android 3.2.0, iPhone 3.2.0, iPad 3.2.0, macOS 9.2.0read-only

Inherited from Titanium.Proxy

The name of the API that this proxy corresponds to.

bubbleParent

Booleansince Android 3.0.0, iPhone 3.0.0, iPad 3.0.0, macOS 9.2.0

Inherited from Titanium.Proxy

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

Default: true

checkable

Boolean

Determines if the item can be checked.

Note that check marks are not supported in the icon menus (main options menu shown when fewer than six options are included). Check marks are discouraged in expanded menus (available when six or more options menu items are defined).

Default: false

checked

Boolean

Determines if the item is checked.

Default: false

enabled

Boolean

Determines if the item is enabled.

Default: true

groupId

Numberread-only

Group ID for this item.

Items that share a group ID may be operated on as a group using the menu's setGroupEnabled and setGroupVisible methods.

icon

Number | Stringwrite-only

Icon to display for the this menu item.

Icons are not displayed in expanded menus.

Icons can be specified as a local image URI or an Android resource ID.

itemId

Numberread-only

Item ID for this item.

lifecycleContainer

Titanium.UI.Window | Titanium.UI.TabGroupsince 3.6.0

Inherited from Titanium.Proxy

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

order

Numberread-only

Integer used for controlling the category and sort order for menu items.

The lower bits of this value control the order of the menu item related to other menu items within its category. A menu item with a given value will be displayed before any items with higher values.

The upper bits of the value control the category. These can be set to the values defined by the CATEGORY constants in the Android Menu class, These values are not exposed as constants in Titanium.

showAsAction

Numbersince 3.0.0write-only

A set of flags that controls how this item appears in the action bar.

This is an action-bar specific API. Prior to Release 3.3.0, this property only works on devices running Android 3.0 (API level 11) and greater.

You may set one or more flags (by OR'ing them together) to control how this menu item should be placed inside the action bar.

To control if your item should be displayed as an action button or placed in the overflow menu set one of these flags: Titanium.Android.SHOW_AS_ACTION_ALWAYS, Titanium.Android.SHOW_AS_ACTION_IF_ROOM, or Titanium.Android.SHOW_AS_ACTION_NEVER.

If you only wish to display the text label even if the item has an icon set the Titanium.Android.SHOW_AS_ACTION_WITH_TEXT flag. Note that the SHOW_AS_ACTION_WITH_TEXT setting is only a hint to the system -- the text may or may not be shown depending on the width of the screen. For example, text may not be shown on phones in portrait mode. In addition if the application can be displayed in both portrait and landscape mode, whether or not the text is displayed depends on the device's orientation when the application launches. (This is true of both Titanium applications and native Android applications.) For this reason, using SHOW_AS_ACTION_WITH_TEXT is not recommended for applications that support both orientations.

If you want to guarantee that text and icon are always visible, you can create a button with the text and image, and specify it as the item's actionView.

You may specify if your action view is collapsible by setting this property to Titanium.Android.SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW.

For a collapsible item, the item button (icon and/or text) is displayed when the item is collapsed, and the action view is displayed when the item is expanded.

If SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW is not specified, any actionView specified is displayed instead of the item's icon and/or text.

Accepts

title

String

Title of the item.

titleCondensed

String

Shortened version of the item's title.

If both title and titleCondensed are specified, titleCondensed is used in the icon menus, and the title is used in the extended menus.

visible

Boolean

Determines whether the menu item is visible.

Default: true

Methods 15

addEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to invoke when the event is fired. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

applyProperties

since 3.0.0

Inherited from Titanium.Proxy

Applies the properties to the proxy.

Parameters
Parameters	Type	Description
props	Dictionary	A dictionary of properties to apply.

collapseActionView

since 3.0.0

Collapse the action view associated with this menu item.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 4.0 (API level 14) and greater.

expandActionView

since 3.0.0

Expand the action view associated with this menu item.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 3.0 (API level 11) and greater.

fireEvent

Inherited from Titanium.Proxy

Fires a synthesized event to any registered listeners.

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

isActionViewExpanded

deprecated

Deprecated since 10.0.0

Use the <Titanium.Android.MenuItem.actionViewExpanded> property instead.

Returns the actionViewExpanded state of the menu item.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 4.0 (API level 14) and greater.

Returns Boolean

isCheckable

deprecated

Deprecated since 10.0.0

Use the <Titanium.Android.MenuItem.checkable> property instead.

Returns the checkable state of the menu item.

Returns Boolean

isChecked

deprecated

Deprecated since 10.0.0

Use the <Titanium.Android.MenuItem.checked> property instead.

Returns the checked state of the menu item.

Returns Boolean

isEnabled

deprecated

Deprecated since 10.0.0

Use the <Titanium.Android.MenuItem.enabled> property instead.

Returns the enabled state of the menu item.

Returns Boolean

isVisible

deprecated

Deprecated since 10.0.0

Use the <Titanium.Android.MenuItem.visible> property instead.

Returns the visible state of the menu item.

Returns Boolean

removeEventListener

Inherited from Titanium.Proxy

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

Parameters
Parameters	Type	Description
name	String	Name of the event.
callback	Callback<Titanium.Event>	Callback function to remove. Must be the same function passed to `addEventListener`. 4 fields bubbles Boolean True if the event will try to bubble up if possible. cancelBubble Boolean Set to true to stop the event from bubbling. source Object Source object that fired the event. type String Name of the event fired.

setCheckable

deprecated

Deprecated since 10.0.0, removed in 10.0.0

Use the <Titanium.Android.MenuItem.checkable> property instead.

Sets the checkable state of the menu item.

Parameters
Parameters	Type	Description
checkable	Boolean	True enable checking and unchecking this item, false to disable it.

setChecked

deprecated

Deprecated since 10.0.0, removed in 10.0.0

Use the <Titanium.Android.MenuItem.checked> property instead.

Sets the checked state of the menu item.

Parameters
Parameters	Type	Description
enabled	Boolean	True to check the item, false to uncheck it.

setEnabled

deprecated

Deprecated since 10.0.0, removed in 10.0.0

Use the <Titanium.Android.MenuItem.enabled> property instead.

Sets the enabled state of the menu item.

Parameters
Parameters	Type	Description
enabled	Boolean	True to enable item, false to disable it.

setVisible

deprecated

Deprecated since 10.0.0, removed in 10.0.0

Use the <Titanium.Android.MenuItem.visible> property instead.

Sets the visible state of the menu item.

Parameters
Parameters	Type	Description
visible	Boolean	True to show the item, false to hide it.

Events 3

click

Fired when the user clicks the menu item.

collapse

since 3.0.0

Fired when the action view has been collapsed.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 4.0 (API level 14) and greater.

expand

since 3.0.0

Fired when the action view has been expanded.

This is an action-bar specific API. Prior to Release 3.3.0, this API only works on devices running Android 4.0 (API level 14) and greater.