The action bar is a major UI feature for Android applications in Android 3.0 and later. To understand all of the features of the action bar and its place in Android applications, we recommend reviewing the Android Design: Action Bar and the Action Bar API guide on the Android developer site.
Hiding the action bar
Titanium shows an Action Bar by default in all windows. If you do not want to show them, then there are 2 ways to do so.
In a theme XML file, you can remove the Action Bar from the window when it is opened.
Titanium provides the following built-in themes which derive from
"Theme.AppCompat.*". The "NoTitleBar" based themes remove the Action Bar. The "Fullscreen" theme removes both the Action Bar and Status Bar.
As of Titanium 9.3.0, the following
"Theme.Titanium.*" prefixed themes are available. These themes derive from the
<application/> assigned theme, which is set to
"Theme.MaterialComponents.Bridge" by default.
You can then remove the Action Bar from all windows by default by setting the theme in the
You can remove the Action Bar before by setting the window's "theme" creation property.
Alternatively, you can hide the Action Bar after the window is opened by getting the activity's action bar instance and call the hide method.
Action bar tabs
For Titanium 7.x.x and older versions, a tab group might display its tabs within the action bar depending on device orientation and the size of the screen. The actual display of the tabs depends on the number of tabs and the amount of screen space available. If there is not enough space to fit all of the tabs on the action bar, Android may display scrolling tabs or a drop-down list instead.
For Titanium 8.0.0 and higher, tabs are never shown within the action bar.
showAsActionproperty. Valid values are:
SHOW_AS_ACTION_ALWAYS. Show item in action bar.
SHOW_AS_ACTION_IF_ROOM. Show item in action bar if space permits, or in the overflow menu otherwise.
SHOW_AS_ACTION_NEVER. Only show item in the overflow menu. This is the default.
You can OR the above values with one of the following modifiers:
SHOW_AS_ACTION_WITH_TEXT. Show the action item text instead of its icon, if space permits.
SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW. Create a standard action item button that can be "expanded" to show an action view.
Android has very specific guidelines for action item icons, including density-specific size requirements. So you'll probably want to generate icons for each density and store them in the density-specific folders in
Resources/android. For example,
To specify a view to use in place of the the default action item button, use the
actionView property. When you add an action view to an action bar, the native view underlying the Titanium view is inserted into the action bar. The view will only be visible if the underlying native view has an inherent size. For example, a Button or ImageView corresponds to an Android native control that is sized based on its contents, so will appear in the action bar. Any Titanium layout properties specified on the view (such as width and height) are ignored by the native Android layout system.
showAsAction is set to
SHOW_AS_ACTION_COLLAPSE_ACTION_VIEW is specified, the icon or title is shown when the item is collapsed, and the action view is shown when the item is expanded. When expanded, the action view takes over most of the action bar, and other action items are hidden. The
MenuItem object supports two new methods,
collapseActionView, and accompanying
collapse events. The most common use of the expandable action item is for Android search widget, Ti.UI.Android.SearchView.
When creating action items, keep in mind:
- The behavior of
SHOW_AS_ACTION_WITH_TEXTis rather unpredictable; if you specify an icon and SHOW_AS_ACTION_WITH_TEXT, the Android OS still may choose to display either the text or the icon, depending on how much space is available in the action bar. This determination may vary based on which orientation an application was launched in, so the setting should be used with care if your application supports multiple orientations. To force Android to display text for an action item, specify a title but no icon.
Note that Android displays either text or an icon in the action bar. If you need to include both text and an icon, you can create a Titanium button with both text and icon, and add it as the
- When an action item is displayed in the overflow menu (for example, when specified with
SHOW_AS_ACTION_NEVER), it is displayed as text, without an icon. This is the way the overflow menu is meant to behave. It may cause some confusion because it differs from the way items are displayed in the action bar (where they use the icon if available) and in the legacy Android menu (where both icon and text are displayed).
- You should always specify a title for an action item. Titles are used to display in the overflow menu, and are also displayed as hints when the user long-presses on an action item.
- Only a few items can be displayed in the action bar. See the Android Design: Action Bar for guidelines on selecting action items.
Dynamically updating action items
Since the options menu is considered always open when the action bar is in use,
onCreateOptionsMenu is only called when the window or tab group is opened. To force the
onCreateOptionsMenu method to be executed again, call
Activity.invalidateOptionsMenu. The following code sample shows one way to switch the action items when the user changes tabs in a tab group.
Other action bar features
Direct access to some action bar methods and properties is available through the
Activity.actionBar property. The activity and action bar objects are not created until the associated window or tab group is opened. Initial updates to these objects should be done in the
open event handler for the window or tab group.
Currently, the tab group activity is only available from using the
To receive a callback when the home icon is clicked, set the
ActionBar.onHomeIconItemSelected property to a callback function:
You can use the
logo properties to set the title, background, app icon, and app logo used in the action bar, respectively. Set the
ActionBar.displayHomeAsUp property to
true to display the "up" affordance.
ActionBar also provides
hide methods to show and hide the action bar. For example, to show the "up" affordance on a tab group's action bar you could use code like this:
Styling the action bar
To change the style of the action bar, create a custom theme to override the Action Bar style properties. To create a custom theme:
Create an XML file in
In the XML file, create an action bar style resource and set the parent style of the action bar style to
Widget.AppCompat.ActionBaror another supported Action Bar parent.
Define action bar properties in the style resource to override the default values from the parent style.
In the theme, set the
android:actionBarStyleto name of action bar style you created.
tiapp.xmlfile to use the custom theme:
The example below modifies the Action Bar's background color and title text color.
Testing in the emulator
To test on an emulator, you may need to configure some options to display the action bar and overflow menu. Note that the overflow option does not appear on emulators and devices running Android 2.3.x and earlier.
When testing the action bar in the Android emulator, note that the action overflow menu is not displayed in the default emulator, because the default emulator represents a device with hardware buttons.
To configure the Android emulator to show the overflow menu:
- Make a note of the name of the emulator you're testing with (for example,
- Close the emulator.
- Run the Android AVD manager:
androidcommand is in the
toolsfolder of the Android SDK folder.
- Select the emulator you're testing with and click Edit.
- Click New next to the Hardware list.
- Choose Hardware Back/Home Keys and click OK.
- Change the Hardware Back/Home Keys value to No.
- Click outside the Hardware list to confirm the value change; make sure the value for Hardware Back/Home Keys is still displayed as No.
- Click Edit AVD.
- Run your test application again.
If you do not see the overflow menu when testing on a Genymotion emulator, you may need to enable the navigation bar.
To enable the navigation bar, the emulator must not be currently opened, then:
- Start the Genymotion app.
- Select the emulator you want to configure, then click Configure button .
- Enable Show Android navigation bar, then click OK.
- Run your test application again.