Page: Android Action Bar
Page: Custom Numeric and Date Formatting
Page: Predefined Numeric and Date Formats
Page: Deploying to Android Devices
Page: QuickView titles
Page: Using Android Simulators
Page: Multi-Platform Management
Page: Shared Resource Requirements
Page: Android Display Constraints
Page: Platform-Specific Resource Requirements
Page: 7.4 Release Notes
Android Action Bar
The Android action bar appears in your app at the top of the device's screen. The action bar provides a simple way to add actions such as navigation and search to your app. These action can be global to the app, such as a way to navigate back the the home screen, or actions can be specific to a particular area of the app.
The action bar appears automatically in your app. That is, you do not have to enable the action bar. However, you do have the option of hiding the action bar, if necessary.
Android devices use the action bar to display:
- Back navigation button
- App icon
- Title text
- Navigation icons
- Overflow menu
- Other elements including search box and navigation bars
AppStudio enterprise mobility platform supports the action bars and lets you control the content and the styling of the action bar in your app.
This page includes the following topics:
- Action bar layout
- Controlling the title text in the action bar
- Override the title text in the action bar
- Controlling title text for the secondary screen of the Lookup and Association controls
- Displaying the app icon in the action bar
- Setting action bar text styles and background image
- Adding Global Search or Screen Search icons to the action bar
- Configuring Title Button One and Title Button Two screen menu items
Action bar layout
In its simplest form, the action bar appears at the top of the app in a single row, as the following image shows:
The main area of the action bar includes the back button, app icon, and title text. In this example, the title text includes the row count of the List screen.
You can add up to three navigation icons to the action bar, as the following example shows:
In this example, the action bar shows the following three icons:
- A search icon (magnifying glass above) corresponding to Screen Search. or
- Icons for two menu items corresponding to Title Button One (home icon above) and Title Button Two (+ icon above). Define Title Button One and Title Button Two independently for each screen in the app.
AppStudio lets you create different types of menu items in your app:
- Contextual menu items invoke an operation when the user interacts with a List screen. For example, a menu item of type Dial with prompt is a contextual menu item that initiates a phone call when a user selects a list item.
- Non-context menu items are menu items that cannot be invoked by selecting a list item. Instead, select a non-context menu items from a popup menu. A menu item of type About, Navigation, or Save is an example of a non-context menu item.
For more information on menu items, see Creating Screen Menus.
To access non-context menu items on an Android device that has a hardware menu button, press the menu button.
For Android devices that do not have a hardware menu button, the action bar displays an overflow menu icon at the right end of the action bar, as shown below:
To access non-context menu items, select the overflow icon on the action bar. A popup menu appears that lets you select the desired menu item.
The overflow menu does not display menu icons, even if you define them on the menu items.
The action bar is configured with a back button, in the shape of a less-than sign, "<", which lets the user traverse the app's back stack. This button displays on all app screens, excludinglogin and startup screens.
You cannot change the less-than sign, "<", used by the back button.
Use the back button to navigate to the previous app screen. If you display an app icon in the action bar, and the back button is visible in the action bar, the app icon also functions as a back button.
Displaying the navigation bar in the action bar
To add a navigation bar to your app, define a set of tabs that the user presses to navigate to a specific screen and view. For more information on creating navigation bars, see Navigating Between Screens. On Android devices that support the action bar, the navigation bar appears as part of the action bar.
For BlackBerry and iOS devices, the navigation bar appears at the bottom of the screen.
For wide devices, or smartphones in landscape mode, the navigation bar appears integrated within the action bar, as the following image shows:
In this image, the navigation bar is enclosed within the action bar, after the app icon and before the search icon.
Android supports split action bars for apps that run on narrow-screen devices—for example, a portrait-oriented phone with a screen width less than 480dp (density-independent pixel). If the action bar is split into two sections, it displays the following:
- Top: Back icon, app icon, title text, Title Button One/Two, overflow icon
- Bottom: Navigation bar
The following image shows a narrow device where the navigation bar appears in the lower half of the action bar:
Hiding the action bar
The action bar appears automatically in your app to display the app icon, the back button, and title text. An individual screen can disable the action bar by setting its Hide Title Bar property.
However, a screen cannot hide the action bar regardless of the setting of its Hide Title Bar property if any of the following conditions are true:
- The app uses Global Search or Screen Search
- Any menu items are defined by the screen, not just those with a gesture of Tile Button One or Title Button Two
- The navigation bar is enabled for the screen
If the app uses just the navigation bar, but no other navigation icons, then the navigation bar occupies the entire area of the action bar when you set the Hide Title Bar property, as shown below:
Controlling the title text in the action bar
By default, the title text of the action bar is obtained from the Display Name property of the current screen. For a List screen, if you set the Show Row Count property, the row count also appears in the title text, enclosed in parenthesis.
For a From screen, the title text can also append text from entity data field. For a List screen, if the screen has a parent entity, you can append the value of an entity data field from the parent entity.
To append an entity field, set the check box in the
IsName column for the entity field:
- Select the Data Entities icon on the AppStudio toolbar.
- Double click on the entity to open it.
- Select Edit Fields.
For the associated entity field, set the check box in the
- Save the app.
After you set the check box in the
IsName column, the associated field is displayed as follows:
" " separator-char +
" " + entity-value]
- display-name is the Display Name property of the screen.
- separator-char is the string that is set by the Screen title separator property on the Client Display tab of the Application Properties. By default, it is a hyphen (-).
- entity-value is the value of the entity field.
Override the title text in the action bar
If a screen displays the navigation bar within the action bar, the title text is omitted from the action bar. This is because the user can already see the title text in the navigation bar, so repeating it in the title area of the action bar is redundant.
The Pyxl scripting language contains several functions that work with the title of a view. These functions are not all supported by the action bar, as described below:
getTitle()- Not supported
setTitleStyle()- Not supported
For more information on these functions, see View Functions.
Controlling title text for the secondary screen of the Lookup and Association controls
An Association Field Control encapsulates the relationship between two entities and enables a screen to join the data from one entity with another. A Lookup Control, also called a dynamic choice list, lets you create a choice list and populate the list values at run time from a data source.
Depending on how you configure them, an Association control or Lookup control on one screen can open a secondary screen to prompt the user to perform an action. That secondary screen can also display the action bar.
When the secondary screen opens, and the secondary screen displays the action bar, the title text of the action bar is determined as follows:
- Lookup control
- The text specified by the Hint Text property of the Lookup control.
- If the Hint Text property is null or empty, the text specified by the Label property of the Lookup control.
- If the Label property is null or empty, the text specified by the Display Name property of the target screen of the Lookup control.
- Association control
- The text specified by the Menu Alias of the Association control.
- If the Menu Alias is null or empty, the text specified by the Label property of the Association control.
- If the Label property is null or empty, the text specified by the Display Name property of the target screen of the Association control.
Also, the row count of the secondary screen is appended to the title text, in the form:
"title-text" + " " + "(row-count)"
Displaying the app icon in the action bar
Android action bars can display an app icon next to the back navigation button. Pressing either the back navigation button or the app icon navigates back to the previous screen.
You can configure an app so this icon is constant, or so that it varies according to the current screen. AppStudio obtains the image for the app icon from one of the following properties, in descending order of precedence:
- The image specified by the current screen's Screen Icon property.
- If the screen's Show Entity Icon property is set, the image specified by the Client Image property of the entity associated with the screen.
- If the Use Custom Image property on the Client Display tab of the Application Properties screen is set, use the image specified by the Application Icon property.
If none of these properties is set, the image is obtained from the app build.
The icon image's size and format should conform to Android recommendations. If the icon is not sized correctly, AppStudio resizes it as necessary.
The icon is positioned flush with the action bar's left and top/bottom borders, and the title text (if any) on the right, so the icon image should include any padding that you wish to display as a buffer between the icon and these borders.
Setting action bar text styles and background image
Use a combination of style properties and configuration settings to control the appearance of the action bar in your app:
- Configure the text style of the action bar for the entire app by using the Default Title Style style. Edit this style by using the style manager in AppStudio. To access the style manager, select the Styles icon in the AppStudio toolbar.
- Override the appearance of the action bar for an individual screen by setting the screen's Title Style property.
- Set the background image of the action bar by using the Title Background Image property. Access this property on the Client Display tab of the Applications Properties.
The background image is cropped to the size of the action bar. If the image is too small, it is positioned at the top-left of the action bar. If the image is too large, it is cropped at the bottom and right side of the image to fit the available space.
Adding Global Search or Screen Search icons to the action bar
The following rules determine the appearance of the search icon and its action:
- If Screen Search is enabled for the current screen, the search icon appears and the search uses Screen Search even if Global Search is enabled.
- If Global Search is enabled for the current screen, the search icon appears and the search uses Global Search.
- If neither search is enabled, no search icon appears.
The search input box appears in response to selecting the search icon. The appearance of the search input box is based on the version of Android and the screen size of the device:
- For Android 2.x devices, the search input box always appears below the action bar.
- For Android 4.x devices, when the screen is wide enough, the search input box appears in the action bar. If the screen is not wide enough, the search input box appears below the action bar.
If you enable Screen Search on a screen displayed by a Screen Host control, the search icon appears inside the Screen Host control and not in the action bar. You cannot enable Global Search on a Screen Host control.
Configuring Title Button One and Title Button Two screen menu items
Each screen in an app defines its own set of menu items. These menu items are shared across all views for that screen. You can modify screen menus individually and you can define menu items that are shared by all screens in a workflow. For more information on creating menus, see Creating Screen Menus.
When you create a menu item, you assign a gesture to it, such as Tap, Shake, Title Button One, Title Button Two, or None. Menu items associated with a gesture of Title Button One (home icon below) and Title Button Two (+ icon below) appear in the Android action bar, as the following image shows:
The position of the icons for Title Button One and Title Button Two is fixed. Title Button One always appears to the right of Title Button Two on the right side of the action bar.
If you create a single menu item of type Title Button One or Title Button Two, selecting the icon invokes that menu item. However, you can create multiple menu items with the same gesture. For example, you create three menu items with the gesture of Title Button One. In this case, selecting the icon for Title Button One opens a popup menu that lets you select which of the three menu items to invoke.
For Android 4.x devices, the menu items in the popup also display an icon. However, Android 2.x devices do not display icons.
Setting the icon or text displayed by Title Button One and Title Button Two
Title Button One and Title Button Two are represented on the action bar by either an icon or text. However, you cannot display both an icon and text for Title Button One and Title Button Two.
The appearance of the icon or text is determined by the following rules:
- If an icon is specified for the first menu item configured with gesture Title Button One or Title Button Two, then the action bar displays that icon.
- If no icon is specified for the first menu item configured with gesture Title Button One or Title Button Two, and the menu item navigates to a screen that has its Screen Icon property set, then the action bar displays the icon specified by the Screen Icon property.
- If all of the menu items configured with gesture of Title Button One navigate to a screen of type Add, and no icon is specified for the first menu item, then use a "+" icon.
If all of the menu items configured with gesture of Title Button Two are a navigation to a screen of type Find, and no icon is specified for the first menu item, then use a magnifying glass icon.
The default magnifying glass icon for Title Button Two looks just like the default search icon displayed when you enable enabled Global Search or Screen Search. Typically, you define your own icon when Title Button Two references a Find screen.
An image configured in the app build.
Otherwise, the menu item displays the text of the first menu item.
On Android 4.x devices, the text for Title Button One and Title Button Two menu items always displays in upper case.