Contents

Android Developer Reference

This is the official Google Android site for developers. Here you will find all the documentation you need to develop rich android applications.

You will most likely visit this site often.

All tutorials and sample code are credited to their respected owners.

Portions of this page are reproduced from work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

UI & Layouts

This topic covers some of the most common ui elements and their uses.

The ActionBar

The ActionBar is a window feature that identifies the application and user location, and provides user actions and navigation modes. You should use the action bar in most activities that need to prominently present user actions or global navigation, because the action bar offers users a consistent interface across applications and the system gracefully adapts the action bar's appearance for different screen configurations. You can control the behaviors and visibility of the action bar with the ActionBar APIs, which were added in Android 3.0 (API level 11).

Adding and ActionBar

This section will guide you through creating and incorporating an ActionBar in your app.

Beginning with Android 3.0 (API level 11), the ActionBar is included in all activities that use the Theme.Holo theme (or one of its descendants), which is the default theme when either the targetSdkVersion or minSdkVersion attribute is set to "11" or greater. For example, this code needs to be in your AndroidManifest.xml file:

Creating Actions for the ActionBar

The ActionBar gets populated when the onCreateOptionsMenu() method is called. These entries are called actions. You can define these actions in an XML resource file. The MenuInflator class allows you to inflate these actions defined in the XML file and then they can be added to the ActionBar. The showAsAction attribute allows you to define how the action is displayed. For example if ifRoom is defined the action is only displayed in the ActionBar (if there is sufficient space available).

Remove or Hide the ActionBar

If you don't want the action bar for a particular activity, set the activity theme to Theme.Holo.NoActionBar. For example:

You can also hide the action bar at runtime by calling hide(). For example:

When the action bar hides, the system adjusts your activity layout to fill all the screen space now available. You can bring the action bar back with show().

When the activity first starts, the system populates the action bar and overflow menu by calling onCreateOptionsMenu() for your activity. As discussed in the Menus section, it's in this callback method that you should inflate an XML menu resource that defines the menu items. For example:

In the XML file, you can request a menu item to appear as an action item by declaring android:showAsAction="ifRoom" for the element. This way, the menu item appears in the action bar for quick access only if there is room available. If there's not enough room, the item appears in the overflow menu. If your menu item supplies both a title and an icon with the android:title and android:icon attributes then the action item shows only the icon by default. If you want to display the text title, add "withText" to the android:showAsAction attribute. For example:

Splitting the ActionBar

When your application is running on Android 4.0 (API level 14) and higher, there's an extra mode available for the action bar called "split action bar." When you enable split action bar, a separate bar appears at the bottom of the screen to display all action items when the activity is running on a narrow screen (such as a portrait-oriented handset). Splitting the action bar to separate the action items ensures that a reasonable amount of space is available to display all your action items on a narrow screen, while leaving room for navigation and title elements at the top.

To enable split action bar, simply add uiOptions="splitActionBarWhenNarrow" to your <activity> or <application> manifest element.

Customizing the ActionBar

By default, your application icon appears in the action bar on the left side. If you'd like, you can enable the icon to behave as an action item. In response to user action on the icon, your application should do one of two things:

When the user touches the icon, the system calls your activity's onOptionsItemSelected() method with the android.R.id.home ID. In response, you should either start the home activity or take the user one step up in your application's structural hierarchy.

If you respond to the application icon by returning to the home activity, you should include the FLAG_ACTIVITY_CLEAR_TOP flag in the Intent. With this flag, if the activity you're starting already exists in the current task, then all activities on top of it are destroyed and it is brought to the front. Adding this flag is often important because going "home" is an action that's equivalent to "going back" and you should usually not create a new instance of the home activity. Otherwise, you might end up with a long stack of activities in the current task with multiple instances of the home activity.

For example, here's an implementation of onOptionsItemSelected() that returns to the application's "home" activity:

Navigating Up

As a supplement to traditional "back" navigation which takes the user to the previous screen in the task history you can enable the action bar icon to offer "up" navigation, which should take the user one step up in your application's structural hierarchy. For instance, if the current screen is somewhere deep in the hierarchy of the application, touching the app icon should navigate upward one level, to the parent of the current screen.

To enable the icon for up navigation (which displays the "up" indicator next to the icon), call setDisplayHomeAsUpEnabled(true) on your ActionBar:

When the user touches the icon, the system calls your activity's onOptionsItemSelected() method with the android.R.id.home ID, as shown in the above section about Using the App Icon for Navigation.

Here are some good links about android Menus and ActionBars.

http://developer.android.com/guide/topics/ui/menus.html
http://developer.android.com/guide/topics/ui/actionbar.html#Adding

Activities

The Activity class is an important part of an application's overall lifecycle, and the way activities are launched and put together is a fundamental part of the platform's application model. For a detailed perspective on the structure of an Android application and how activities behave, please read the Application Fundamentals and Tasks and Back Stack developer guides. You can also find a detailed discussion about how to create activities in the Activities Developer Guide. Consult the Android Activity Documentation for more information.

Example Basic Activity: example.java

You can see here that this Java class extends Activity which provides common functionality for a wide range of uses. Notice the setContentView() method that takes a resource id to the layout.xml resource to use for the display view. Below you can see the sample xml layout file to be passed into this method to display the view.

main.xml

There are many different activities available for you to use, Most of them are used for specific purposes and will be touch upon in other tutorials.

Menus

By default, every Activity supports an options menu of actions or options. You can add items to this menu and handle clicks on your additions. The easiest way of adding menu items is inflating an XML file into the Menu via MenuInflater. The easiest way of attaching code to clicks is via onOptionsItemSelected(MenuItem) and onContextItemSelected(MenuItem).

Some of the caveats and limitations for the different menu types are listed below. (May change as different android versions are released).

Creating and Configuring an Options Menu

For all menu types, Android provides a standard XML format to define menu items. Instead of building a menu in your activity's code, you should define a menu and all its items in an XML menu resource. You can then inflate the menu resource (load it as a Menu object) in your activity or fragment.

Here's an example menu named game_menu.xml

You can add a submenu to an item in any menu (except a submenu) by adding a <menu> element as the child of an <item>. Submenus are useful when your application has a lot of functions that can be organized into topics, like items in a PC application's menu bar (File, Edit, View, etc.). For example:

To specify the options menu for an activity, override onCreateOptionsMenu() (Fragments provide their own onCreateOptionsMenu() callback). In this method, you can inflate your menu resource (defined in XML) into the Menu provided in the callback. For example:

Handling Click Events for Menus

When the user selects an item from the options menu (including action items in the action bar), the system calls your activity's onOptionsItemSelected() method. This method passes the MenuItem selected. You can identify the item by calling getItemId(), which returns the unique ID for the menu item (defined by the android:id attribute in the menu resource or with an integer given to the add() method). You can match this ID against known menu items to perform the appropriate action. For example:

Here are some good links about android menus.

http://developer.android.com/guide/topics/ui/menus.html

Styles & Themes

When designing your application, you can use styles and themes to apply custom and uniform formatting to its UI elements.

Differences between styles and themes.

Styles and themes are defined as resources. Android provides some default style and theme resources that you can use, or you can declare your own custom style and theme resources.

How to create custom Styles & Themes

When designing your application, you can use styles and themes to apply custom and uniform formatting to its UI elements.

Follow the steps below to learn how to do this.

  1. Create a file named styles.xml in the your application's res/values directory. Add a root node.
  2. For each style or theme, add a <style> element with a unique name and, optionally, a parent attribute. The name is used for referencing these styles later, and the parent indicates what style resource to inherit from.
  3. Inside the <style> element, declare format values in one or more <item> element(s). Each <item> identifies its style property with a name attribute and defines its style value inside the element.
  4. You can then reference the custom resources from other XML resources, your manifest or application code.

Below is an example style definition.

Below are some helpful links about Styles and Themes

http://developer.android.com/guide/topics/ui/themes.html

Layouts

This topic covers layouts in a more detailed fashion than was seen earlier. In this topic we will examine how to make some practical layouts that you might be able to use in your own apps. Later on in this tutorial we will go over the many layouts that are available to us by Android.

Click the button below to go to the tutorial.