Skip to end of metadata
Go to start of metadata

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.

  • "Theme.AppCompat.NoTitleBar"

  • "Theme.AppCompat.Fullscreen"

As of Titanium 9.3.0, the following "Theme.Titanium.*" prefixed themes are available. These themes derive from the AndroidManifest.xml file's <application/> assigned theme, which is set to "Theme.MaterialComponents.Bridge" by default.

  • "Theme.Titanium.NoTitleBar"
  • "Theme.Titanium.Fullscreen"

You can then remove the Action Bar from all windows by default by setting the theme in the tiapp.xml file's <application/> element.

In JavaScript code, you can hide/remove the Action Bar 2 different ways. This is preferred if you only want to hide an Action Bar in particular windows, not all windows.

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.

Action items

For action items, you can add items to the action bar by creating menu items and specifying the new  showAsAction  property. 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.
The following code sample creates a basic action item:

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, Resources/android/images/res-hdpi.

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.

If 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, expandActionView and collapseActionView, and accompanying expand and 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_TEXT is 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 actionView.
  • When an action item is displayed in the overflow menu (for example, when specified with SHOW_AS_ACTION_IF_ROOM or 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 TabGroup.getActivity method.

To receive a callback when the home icon is clicked, set the ActionBar.onHomeIconItemSelected property to a callback function:


You can use the ActionBar titlebackgroundImageicon, and 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 show and 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:

  1. Create an XML file in platform/android/res/values

  2. In the XML file, create an action bar style resource and set the parent style of the action bar style to Widget.AppCompat.ActionBar or another supported Action Bar parent. 

  3. Define action bar properties in the style resource to override the default values from the parent style.

  4. In the theme, set the android:actionBarStyle to name of action bar style you created. 

  5. Modify your tiapp.xml file to use the custom theme: 

    tiapp.xml

The example below modifies the Action Bar's background color and title text color.

platform/android/res/values/mytheme.xml

 

Further reading

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.

Android emulator

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:

  1. Make a note of the name of the emulator you're testing with (for example, titanium_25_WVGA800).
  2. Close the emulator.
  3. Run the Android AVD manager:

    android avd

    The android command is in the tools folder of the Android SDK folder. 
  4. Select the emulator you're testing with and click Edit.
  5. Click New next to the Hardware list.
  6. Choose Hardware Back/Home Keys and click OK.
  7. Change the Hardware Back/Home Keys value to No.
     
  8. Click outside the Hardware list to confirm the value change; make sure the value for Hardware Back/Home Keys is still displayed as No.
  9. Click Edit AVD.
  10. Run your test application again.

Genymotion emulator

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:

  1. Start the Genymotion app.
  2. Select the emulator you want to configure, then click Configure button .
  3. Enable Show Android navigation bar, then click OK.
  4. Run your test application again.

See also: