# Titanium.Android.ActionBar

> An action bar is a window feature that identifies the application and user location, and provides user actions and navigation modes.

- Source: https://titaniumsdk.com/docs/sdk/12.6.4/Titanium.Android.ActionBar
- Titanium SDK version: 12.6.4
- Kind: proxy
- Platforms: Android
- Since: Titanium SDK 3.0
- Extends: Titanium.Proxy
- Inheritance: Titanium.Proxy

You can add action items to the action bar by defining an Android menu and setting the
menu items to display as action items. See [Menu](https://titaniumsdk.com/docs/sdk/Titanium.Android.Menu.md) and
[MenuItem](https://titaniumsdk.com/docs/sdk/Titanium.Android.MenuItem.md) for details.

You cannot change the action bar's settings until the window's [activity](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#activity)
or tab group's [activity](https://titaniumsdk.com/docs/sdk/Titanium.UI.TabGroup.md#activity) has been created.
You can detect this by assigning a callback to the activity's [onCreate](https://titaniumsdk.com/docs/sdk/Titanium.Android.Activity.md#onCreate)
property.

Note that setting the [Window.navBarHidden](https://titaniumsdk.com/docs/sdk/Titanium.UI.Window.md#navBarHidden) property
to true disables the Action Bar since it is part of the navigation title bar.

For more examples on using the Action Bar, refer to the
[Android Action Bar guide](https://titaniumsdk.com/guide/Titanium_SDK/Titanium_SDK_How-tos/User_Interface_Deep_Dives/Android_UI_Components_and_Conventions/Android_Action_Bar.html).

#### Application Notes for Alloy

Starting with Alloy 1.5.0, you can add ActionBar attributes to the `ActionBar` element.
To use the action bar, add the `<ActionBar>` tag as a child of either a
a `<Window>` or `<TabGroup>`, then set ActionBar attributes in either the XML or TSS file.

Starting with Alloy 1.4.0, you can also add ActionBar attributes to the `Menu` element.
Do not define ActionBar attributes in both the `ActionBar` and `Menu` elements. Only define the
attributes in one element.

To add action items to the action bar, add the `<Menu>` tag as a child of either
a `<Window>` or `<TabGroup>`, then add `<MenuItem>` tags as children of the `<Menu>` tag.
Set MenuItem attributes in either the XML or TSS file.

For an example of using the Action Bar with Alloy, see "Action Bar using Alloy XML Markup" below.

## Example: Action Bar using Alloy XML Markup

Adds action items and sets several properties on a window's action bar in the XML and TSS files.

`app/views/index.xml`:
``` xml
<Alloy>
    <Window title="My Test App">
        <ActionBar id="actionbar" title="My XML Menu" onHomeIconItemSelected="doMenuClick" />
        <Menu>
            <MenuItem id="item1" title="Settings" onClick="openSettings" />
            <MenuItem id="item2" title="Search" onClick="doSearch" />
        </Menu>
        <Label id="label">Welcome!</Label>
    </Window>
</Alloy>
```


`app/controllers/index.js`:
```
function doMenuClick() {}
function openSettings() {}
function doSearch() {}
$.index.open();
```

`app/styles/index.tss`:
```
"MenuItem": {
    showAsAction: Ti.Android.SHOW_AS_ACTION_ALWAYS
},
"#item1": {
    icon: Ti.Android.R.drawable.ic_menu_preferences
},
"#item2": {
    icon: Ti.Android.R.drawable.ic_menu_search
},
"#actionbar": {
    icon: "/actionicon.png",
    displayHomeAsUp: true,
    backgroundImage: "/actionbackground.png"
}
```

## Example: Action Bar Example

The following example sets several properties on a window's action bar.

``` js
const win = Ti.UI.createWindow({
    title: "Old Title",
    navBarHidden: false
});
if (OS_ANDROID) {
    win.activity.onCreate = () => {
        const actionBar = win.activity.actionBar;
        if (actionBar) {
            actionBar.backgroundImage = Ti.Filesystem.getFile(Ti.Filesystem.resourcesDirectory, 'bg.png').nativePath;
            actionBar.title = "New Title";
            actionBar.onHomeIconItemSelected = () => {
                Ti.API.info("Home icon clicked!");
            };
        }
    };
}
win.open();
```

The above can be done for a tab group via its [activity](Titanium.UI.TabGroup.activity) property.
Note that individual tab windows do not have an activity. Only the root tab group (which hosts the tabs)
provides an activity property.

## Properties

### backgroundImage

- Type: String
- Platforms: Android
- Permission: write-only

The background image for the action bar, specified as a local file path or URL.

### customView

- Type: Titanium.UI.View
- Platforms: Android
- Since: Titanium SDK 7.1.0

Sets a view to be used for a custom navigation mode.

Inserts a custom view for navigation in the space
between the application's home button and menu actions.
The custom view is trimmed to fit the space available.

### displayHomeAsUp

- Type: Boolean
- Platforms: Android
- Permission: write-only

Displays an "up" affordance on the "home" area of the action bar.

See also: [setDisplayHomeAsUpEnabled](https://developer.android.com/reference/android/app/ActionBar.html#setDisplayHomeAsUpEnabled(boolean))
in the Android Developer Reference.

### homeAsUpIndicator

- Type: String | Number | Titanium.Blob
- Platforms: Android
- Since: Titanium SDK 11.0.0
- Permission: write-only

Sets a custom icon for the "home" button in the corner of the action bar.

Can be set to a `String` file path or URL to an image, to an image blob, or to a resource ID
from `Ti.App.Android.R.drawable.*` or `Ti.Android.R.drawable.*`. It's highly recommended to set this
to a vector drawable resource ID.

### homeButtonEnabled

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 3.3.0
- Permission: write-only

Enable or disable the "home" button in the corner of the action bar.

See also: [setHomeButtonEnabled](https://developer.android.com/reference/android/app/ActionBar.html#setHomeButtonEnabled(boolean))
in the Android Developer Reference.

### icon

- Type: String | Number | Titanium.Blob
- Platforms: Android
- Permission: write-only

Sets the application icon displayed in the "home" area of the action bar.

Before Titanium 11.0.0, this property only supports a `String` and it must be assigned a local file path
or URL to an image.

As of Titanium 11.0.0, this property can also be assigned an image blob or a native drawable resource ID
from `Ti.App.Android.R.drawable.*` or `Ti.Android.R.drawable.*`.

### logo

- Type: String | Number | Titanium.Blob
- Platforms: Android
- Permission: write-only

Sets the application logo displayed in the "home" area of the action bar.

Before Titanium 11.0.0, this property only supports a `String` and it must be assigned a local file path
or URL to an image.

As of Titanium 11.0.0, this property can also be assigned an image blob or a native drawable resource ID
from `Ti.App.Android.R.drawable.*` or `Ti.Android.R.drawable.*`.

### navigationMode

- Type: Number
- Platforms: Android

Controls the navigation mode.

The navigation mode can be [NAVIGATION_MODE_STANDARD](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#NAVIGATION_MODE_STANDARD), or [NAVIGATION_MODE_TABS](https://titaniumsdk.com/docs/sdk/Titanium.Android.md#NAVIGATION_MODE_TABS).
A TabGroup is initialized by Titanium Mobile with `NAVIGATION_MODE_TABS`, and can be hidden by setting to `NAVIGATION_MODE_STANDARD`. `NAVIGATION_MODE_LIST` is not yet supported.
See also: [setNavigationMode](https://developer.android.com/reference/android/app/ActionBar.html#setNavigationMode(int))
in the Android Developer Reference.

### onHomeIconItemSelected

- Type: Callback
- Platforms: Android
- Permission: write-only

Callback function called when the home icon is clicked.

### subtitle

- Type: String
- Platforms: Android
- Since: Titanium SDK 3.2.3

Sets the subtitle of the action bar.

### title

- Type: String
- Platforms: Android

Sets the title of the action bar.

### visible

- Type: Boolean
- Platforms: Android
- Since: Titanium SDK 11.0.0

Gets or sets the action bar visibility state.

Setting this property to `true` or `false` is the equivalent of calling the
[show()](https://titaniumsdk.com/docs/sdk/Titanium.Android.ActionBar.md#show) or [hide()](https://titaniumsdk.com/docs/sdk/Titanium.Android.ActionBar.md#hide) methods.

## Methods

### hide

- Platforms: Android

Hides the action bar if it is currently showing.

See also:
[hide](https://developer.android.com/reference/android/app/ActionBar.html#hide())
in the Android API Reference.

### setDisplayShowHomeEnabled

- Platforms: Android
- Since: Titanium SDK 3.3.0

Shows or hides the action bar home icon

See also:
[setDisplayShowHomeEnabled](https://developer.android.com/reference/android/app/ActionBar.html#setDisplayShowHomeEnabled(boolean))
in the Android API Reference.

Parameters:

- `show` (Boolean): Boolean to show or hide action bar home icon

### setDisplayShowTitleEnabled

- Platforms: Android
- Since: Titanium SDK 3.3.0

Shows or hides the action bar title/subtitle

See also:
[setDisplayShowTitleEnabled](https://developer.android.com/reference/android/app/ActionBar.html#setDisplayShowTitleEnabled(boolean))
in the Android API Reference.

Parameters:

- `show` (Boolean): Boolean to show or hide action bar title/subtitle

### show

- Platforms: Android

Shows the action bar if it is currently hidden.

See also:
[show](https://developer.android.com/reference/android/app/ActionBar.html#show())
in the Android API Reference.

## Inherited members

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

- [Titanium.Proxy](https://titaniumsdk.com/docs/sdk/12.6.4/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`.