Titanium.Android.MenuItem
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.
Further Reading:
Extends: Titanium.Proxy · Since: 1.5 · Platforms: android
Properties #
accessibilityHint#
Type: String
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.
accessibilityLabel#
Type: String
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.
accessibilityValue#
Type: String
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.
actionView#
Type: Titanium.UI.View
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#
Type: Boolean
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#
Type: String
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.
bubbleParent#
Type: Boolean
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.
checkable#
Type: 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).
checked#
Type: Boolean
Determines if the item is 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).
groupId#
Type: Number
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#
Type: Number, String
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.
lifecycleContainer#
Type: Titanium.UI.Window, Titanium.UI.TabGroup
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.
order#
Type: Number
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.
See also:
showAsAction#
Type: Number
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.
titleCondensed#
Type: 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.
Methods #
addEventListener #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
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.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
collapseActionView #
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 #
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 #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
isActionViewExpanded #
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
removeEventListener #
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);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |
setCheckable #
Sets the checkable state of the menu item.
| Name | Type | Summary | Optional |
|---|---|---|---|
checkable | Boolean | True enable checking and unchecking this item, false to disable it. | No |
setChecked #
Sets the checked state of the menu item.
| Name | Type | Summary | Optional |
|---|---|---|---|
enabled | Boolean | True to check the item, false to uncheck it. | No |
Events #
click #
Fired when the user clicks the menu item.
collapse #
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 #
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.