The onCreate method

When Android creates an activity, Android calls the activity’s onCreate method. This happens much more often than you’d think, because Android destroys and then re-creates activities while the user navigates from place to place. For example, if your phone runs low on memory, Android can kill some running activities. When you navigate back to a killed activity, Android re-creates the activity for you. The same thing happens when you turn the phone from portrait to landscape mode. If the developer doesn’t override the default behavior, Android destroys an activity and re-creates the activity before displaying the activity in the other mode.

In Listing 4-1, the onCreate method has things named savedInstanceState and R.layout.activity_main.

• The savedInstanceState variable stores information about some of the activity’s values when the activity was previously destroyed.

  The statement super.onCreate(savedInstanceState) tells Android to restore those previous values. This way, the activity takes up where it last left off.

  During what appears to the user to be a continuous run, Android might destroy and re-create an activity several times. An activity’s savedInstanceState helps to maintain continuity between destructions and re-creations.

  To be precise, the statement super.onCreate(savedInstanceState) calls the parent class’s onCreate method. To read more about parent classes in Java, see Book II, Chapter 2.

• The method parameter R.layout.activity_main is a roundabout way of coding the buttons, text fields, and the way they’re all laid out.

  In Listing 4-1, the call to setContentView plops these buttons, text fields, images, and other stuff on the activity screen. For more about this, check the section “The R.java file”, later in this chapter.

The onCreateOptionsMenu method

With a new Android activity comes a new menu. For older Android versions, a separate menu button is somewhere on (or near) the device’s screen. But starting with Honeycomb, apps put a menu icon in an action bar. (In Figure 4-1, the activity’s menu icon has three vertically-aligned dots. The icon appears in the screen’s upper-right corner.)

• In Listing 4-1, the call getMenuInflater().inflate(R.menu.menu_main, menu) does the same for the look of your menu items as a call to setContentView does for the overall look of your activity.

  The call puts items (and perhaps sub-items) in your app’s menu.

• The last statement inside the onCreateOptionsMenu method (the return true statement) tells Android to display your app’s menu.

  If, for some reason, you don’t want Android to display the menu, change this statement to return false.

In Listing 4-1, the onCreateOptionsMenu method creates your activity’s menu. That’s fine, but what happens when the user taps a menu item? When the user taps an item, Android calls your activity’s onOptionsItemSelected method.

The onOptionsItemSelected method

In Listing 4-1, the onOptionsItemSelected method doesn’t do too much.

• The call to item.getItemId() grabs the code number of whatever item the user tapped.

  For some good reading about Android’s use of code numbers, see the section “The R.java file,” later in this chapter.

• When your IDE creates a skeletal app, the app has one menu item named action_settings. The code in Listing 4-1 checks to find out if the user tapped this action_settings item.

  In a real-world app, the code would check to find out which of several menu items the user tapped.

• Returning true tells Android that the tapping of this menu item has been handled. No further action is necessary.

  A return value of false would mean that some other code should do something in response to the user’s tap.

• Finally, the super.onOptionsItemSelected(item) call tells Android to do, with this menu item tap, whatever Android normally does by default for any old menu item tap.

  This is no big deal because, by default, Android does almost nothing.

To make use of the code in Listing 4-1, you have to know something about Java. For a big blast of Java, visit Book II, Chapters 2, 3, and 4.

The res/drawable branch

The drawable branch contains images, shapes, and other such things. A single drawable item might come in several different sizes, each with its own dpi (dots per inch) level. The sizes include mdpi (a medium number of dots per inch), hdpi (a high number of dots per inch), xhdpi (extra high), and xxhdpi (extra-extra high). I wonder how many “xs” we’ll need when Android starts powering digital displays on Times Square!

For more reading about drawables, visit, Book IV, Chapter 1.

The res/layout branch

The layout branch contains descriptions of your activities' screens.

A minimal app’s layout branch contains an XML file describing an activity’s screen. (See the activity_main.xml branch in Figure 4-2.) Listing 4-2 shows the code in the simple activity_main.xml file.

Listing 4-2: A Small Layout File

<RelativeLayout xmlns:android=

      "http://schemas.android.com/apk/res/android"

    xmlns:tools="http://schemas.android.com/tools"

    android:layout_width="match_parent"

    android:layout_height="match_parent"

    android:paddingBottom="16dp"

    android:paddingLeft="16dp"

    android:paddingRight="16dp"

    android:paddingTop="16dp"

    tools:context=".MainActivity">

  <TextView

      android:layout_width="wrap_content"

      android:layout_height="wrap_content"

      android:text="Hello world!" />

</RelativeLayout>

An Android app consists of Java code, XML documents, and other stuff. The XML code in Listing 4-2 describes a relative layout. (In a relative layout, each element’s position is relative to the positions of other elements. So buttons and text fields appear to the right of one another, to the left of one another, below one another, and so on.) Because of its match_parent attributes, the layout is large enough to fill its surroundings. Its “surroundings” are the entire screen (minus a few doodads on the edges of the screen).

In Listing 4-2, the only item inside the relative layout is an instance of TextView — a place to display text on the screen. Because of the wrap_content attributes, the text view is only wide enough and only tall enough to enclose whatever characters it displays.

For more info about layouts, see Book IV, Chapter 1.

What you see isn’t what you get

When you look at the activity_main.xml text in Android Studio’s editor, you see the stuff in Listing 4-2. But you can also visit the activity_main.xml file using Windows File Explorer or Mac Finder. You can open this file with Windows Notepad or Mac TextEdit. When you do, you see the text in Listing 4-3.

Listing 4-3: The Real activity_main.xml File

<RelativeLayout xmlns:android=

      "http://schemas.android.com/apk/res/android"

    xmlns:tools="http://schemas.android.com/tools"

    android:layout_width="match_parent"

    android:layout_height="match_parent"

    android:paddingBottom="@dimen/activity_vertical_margin"

    android:paddingLeft="@dimen/activity_horizontal_margin"

    android:paddingRight="@dimen/activity_horizontal_margin"

    android:paddingTop="@dimen/activity_vertical_margin"

    tools:context=".MainActivity">

  <TextView

      android:layout_width="wrap_content"

      android:layout_height="wrap_content"

      android:text="@string/hello_world" />

</RelativeLayout>

What you see in Listing 4-3 is the text that’s really in the app’s activity_main.xml file. But what you typically see in Android Studio’s editor isn’t the same as the text in Listing 4-3. (In Listing 4-3, the text that I’ve set in bold is different from what you see in Android Studio’s editor.)

Android Studio’s editor doesn’t show you all the text (and only the text) in a file such as activity_main.xml. Instead, the editor replaces some expressions with the values of those expressions. It’s like displaying the number 42 when the actual file contains the text 20 + 22.

• In the activity_main.xml file, the value of the expression @dimen/activity_vertical_margin is 16.

  That’s why you see @dimen/activity_vertical_margin in Listing 4-3, but you see 16 in Listing 4-2.

  To be more precise, the expression @dimen/activity_vertical_margin stands for 16 device independent pixels (16dp). To find out what a device independent pixel is, see Book IV, Chapter 1.

• In the activity_main.xml file, the value of the expression @string/hello_world is Hello world!

  To find out why @dimen/activity_vertical_margin stands for 16dp and why @string/hello_world stands for Hello world, see the section “The res/values branch,” later in this chapter.

In Android Studio’s editor, things like "16dp" appear as light-gray characters. The light-gray shade indicates that the editor isn’t showing you the text that’s really in the activity_main.xml file (the text that you’d probably type if you were composing this code from scratch).

• If you hover over the light-gray text, a pop-up shows you the text that’s really in the file.
• If you click on the light-gray text, Android Studio replaces it with the text that’s really in the file. Instead of seeing Hello world! in light gray, you see @string/hello_world in an off shade of green.
• (Here’s the thing that drove me crazy until I figured out what was going on.) You can select the text in the Android Studio editor, copy that stuff to the Clipboard, and then paste it into a regular editor (Windows Notepad, Mac TextEdit, or whatever). When you do, you don’t necessarily see whatever you see in Android Studio’s editor. You see @dimen/activity_vertical_margin instead of 16dp, and you see @string/hello_world instead of Hello world! (As an author who regularly copies and pastes material into a Word document, this behavior sends me running and screaming!)

The res/menu branch

Each file in the menu branch describes a menu belonging to your app. The simple app that your IDE creates contains only one menu. The file to describe that menu is named menu_main.xml.

Listing 4-4 contains the bare-bones menu_main.xml file.

Listing 4-4: The menu_main.xml Menu File

<menu xmlns:android=

      "http://schemas.android.com/apk/res/android"

  xmlns:tools="http://schemas.android.com/tools"

  tools:context="com.example.myapplication.MainActivity" >

  <item

    android:id="@+id/action_settings"

    android:orderInCategory="100"

    android:showAsAction="never"

    android:title="Settings"/>

</menu>

The menu contains only one item, and in other parts of this app’s code, you refer to that item by the name action_settings.

Android Studio’s editor doesn’t show you exactly what’s in the menu_main.xml file. Where you see android:title="Settings" in Listing 4-4 (and in Android Studio’s editor), the file really contains the text android:title="@string/action_settings". The expression @string/action_settings has a value, and that value is the word Settings. For more information about @string expressions, see the “The res/values branch” section.

For more info about menus, see Book IV, Chapter 2.

The res/mipmap branch

The res/mipmap branch is like the res/drawable branch, except that the res/mipmap branch contains your app’s icons. The term mipmap stands for multum in parvo mapping. And the Latin phrase multum in parvo means “much in little.” A mipmap image contains copies of textures for many different screen resolutions.

The mipmap folder was introduced in Android 4.3, so you don’t see it in older Android apps (including some of this book’s apps).

The res/values branch

The files in the values branch describe miscellaneous things that an app needs to know. For example, Listing 4-3 shows you what’s actually in your app’s activity_main.xml file. In that file, the @string/hello_world attribute tells Android what text to display inside the TextView element. In Figure 4-1, these words happen to be Hello world! To find out how @string/hello_world gets turned into Hello world!, and how Hello world! gets to be displayed as part of your app, see Figure 4-4.

Why does the activity_main.xml file contain the following cryptic line?

android:text="@string/hello_world"

Why don’t you simply code

android:text="Hello World!"

in the activity_main.xml file (the way the editor displays the file in Listing 4-2)?

Here’s why: If you create a good Android app, people all around the world download your app. These people speak many different languages, so you don’t put actual words (like Hello world!) in your app’s Java code or even in your app’s activity_main.xml layout file. Instead, you put Hello world! in your res/values/strings.xml file. Then, to localize your app for French, you put Bonjour tout le monde! in a res/values-fr/strings.xml file. To localize your app for Romanian, you put Salut lume! in a res/values-ro/strings.xml file.

Listing 4-5 shows the code in the simple strings.xml file.

Listing 4-5: A Small strings.xml File

<?xml version="1.0" encoding="utf-8"?>

<resources>

  <string name="app_name">My Application</string>

  <string name="hello_world">Hello world!</string>

  <string name="action_settings">Settings</string>

</resources>

In Listing 4-5, the line

<string name="hello_world">Hello world!</string>

tells Android that, in other parts of the app’s code, the expressions @string/hello_world and R.string.hello_world refer to the words Hello world!

In an Android app, one string of characters, such as Hello world! goes by many different names. Listing 4-5 describes a "hello_world" string containing the characters Hello world!. To refer to that "hello_world" string in Listing 4-1 (a .java file), you type R.string.hello_world. To refer to the same "hello_world" string in another XML file (such as the file in Listing 4-2), you type @string/hello_world. With either @string/hello_world or R.string.hello_world, you refer to the thing named "hello_world" (the thing in Listing 4-5). And, either way, you point to the words Hello world! in Figure 4-1. (Yes, it can be confusing. I’ve dealt with this string-naming business for several years, but I still have to stop and think about it.)

In Listing 4-5, expressions such as @dimen/activity_horizontal_margin work the same way as the @string expression. The app/res/values branch in the Project tool window contains a dimens.xml branch. That dimens.xml branch typically contains two dimens.xml files. These dimens.xml files contain lines such as

<dimen name="activity_horizontal_margin">16dp</dimen>

When a device runs your app, the device substitutes an actual value (such as 16dp — 16 device independent pixels) for the expression @dimen/activity_horizontal_margin in your activity_main.xml file. With this substitution trick, a single activity_main.xml file works for screens of many shapes and sizes. To accommodate a certain screen size, a device consults one of your app’s dimens.xml files.

To read all about XML documents, like the ones in Listings 4-2 through 4-5, see Book II, Chapter 5.

The build.gradle file

Gradle is a software tool. When the tool runs, it takes a whole bunch of files and combines them to form a complete application. For example, a run of Gradle can use the files shown in Figure 4-2 to build a single .apk file for posting on Google’s Play store. Of course, Gradle can combine files in many different ways, so to get Gradle to do things properly, someone has to provide Gradle with a script of some kind.

A new Android app comes with its own ready-made script. In Figure 4-2, that script appears in the branch labeled build.gradle (Module: app).

Listing 4-6 shows the contents of a simple app’s build.gradle file.

Listing 4-6: A Little build.gradle File

apply plugin: 'com.android.application'

android {

    compileSdkVersion 21

    buildToolsVersion "21.1.2"

    defaultConfig {

        applicationId "com.example.myapplication"

        minSdkVersion 15

        targetSdkVersion 21

        versionCode 1

        versionName "1.0"

      }

    buildTypes {

        release {

            minifyEnabled false

            proguardFiles getDefaultProguardFile

              ('proguard-android.txt'), 'proguard-rules.pro'

        }

    }

}

dependencies {

compile fileTree(dir: 'libs', include: ['*.jar'])

}

I cover some build.gradle code in the section “Your app’s API levels,” later in this chapter. So, in this section, I describe only a few of the listing’s highlights.

An app’s versions

In Listing 4-6, the versionCode and versionName properties have similar (but slightly different) meanings.

• The versionCode property is an integer. For publication on the Google Play Store, the versionCode must increase from one version of your app to another. The numbers don’t have to be consecutive. So your first published version can have versionCode 47, and the next published version can be number 63. The app’s user doesn’t see the versionCode.
• The versionName can be any string of characters, so this attribute’s value is largely cosmetic. The user sees the versionName.

Listing 4-6 contains values for an app’s compileSdkVersion, minSdkVersion, and targetSdkVersion. To find out what these SDK versions are, see the section “Your app’s API levels,” later in this chapter.

The AndroidManifest.xml file

An app’s AndroidManifest.xml file describes some of the things a device needs in order to run the app. (See Listing 4-7.)

Listing 4-7: A Little AndroidManifest.xml File

<?xml version="1.0" encoding="utf-8"?>

<manifest xmlns:android=

    "http://schemas.android.com/apk/res/android"

  package="com.example.myapplication" >

  <application

    android:allowBackup="true"

    android:icon="@drawable/ic_launcher"

    android:label="@string/app_name"

    android:theme="@style/AppTheme" >

    <activity

      android:name=

        "com.example.myapplication.MainActivity"

      android:label="@string/app_name" >

      <intent-filter>

        <action android:name=

            "android.intent.action.MAIN" />

        <category android:name=

            "android.intent.category.LAUNCHER" />

      </intent-filter>

    </activity>

    </application>

</manifest>

What you see in Android Studio’s editor isn’t the same as what I show in Listing 4-7. Some of the text composed by Android Studio changes from one version of Android Studio to the next. In addition, Android Studio’s editor might display android:label="My Application" with My Application in light-gray text. But in place of that text, the AndroidManifest.xml file actually contains the reference android:label="@string/app_name".

All Android apps have AndroidManifest.xml files. But only newer Android apps have build.gradle files. For older apps, information about versionCode, versionName, and SDK versions lives in the AndroidManifest.xml file:

<manifest xmlns:android=

  "http://schemas.android.com/apk/res/android"

    package="com.example.myapplication "

    android:versionCode="1"

    android:versionName="1.0">

  <uses-sdk android:minSdkVersion="15"/>

… Etc.

The R.java file

Each Android project has an R.java file. Android Studio generates this file, and protects this file as if the file were made of gold. You, the developer, never create or modify the R.java file’s text.

You don’t see R.java in Figure 4-2 because the R.java file doesn’t appear in the Android Project view. If you want to see the R.java file, switch the Project tool window to its Packages view. Follow the instructions on switching views in the sidebar “The many faces of Android Studio.” When the Packages view replaces the Android Project view, visit the app/com.example.myapplication/test/R branch in the tree.

Listing 4-8 shows some of the lines in an R.java file.

Listing 4-8: Don’t Even Look at This File

/* AUTO-GENERATED FILE. DO NOT MODIFY.

  *

  * This class was automatically generated by the

  * aapt tool from the resource data it found. It

  * should not be modified by hand.

  */

package com.example.myapplication;

public final class R {

  public static final class attr {

  }

  public static final class drawable {

    public static final int ic_launcher=0x7f020000;

  }

  public static final class id {

    public static final int action_settings=0x7f080000;

  }

  public static final class layout {

    public static final int activity_main=0x7f030000;

  }

  public static final class menu {

    public static final int main=0x7f070000;

  }

  public static final class string {

    public static final int action_settings=0x7f050002;

    public static final int app_name=0x7f050000;

    public static final int hello_world=0x7f050001;

  }

  // … There’s more stuff here

}

The hexadecimal values in an R.java file are the jumping-off points for Android’s resource management mechanism. Android uses these numbers for quick and easy loading of the things you store in the res branch. For example, the code in Listing 4-1 sets the look of your activity to R.layout.activity_main, and according to Listing 4-8, R.layout.activity_main has the hex value 0x7f030000.

Android’s documentation tells you to put R.java and its hex values out of your mind, and that’s probably good advice (advice that I break in this section). Anyway, here are two things to remember about the role of R.java in an Android app:

• You cannot edit R.java.

  Long after the creation of a project, your IDE continues to monitor (and if necessary, update) the contents of the R.java file. If you delete R.java, Android Studio re-creates the file. If you edit R.java, Android Studio undoes your edit.

• Many of Android’s pre-declared methods expect numbers in R.java as their parameters.

  This can lead to some confusion. Consider the following (very bad) chunk of code:

  // THIS IS BAD CODE!

  System.out.println("42");

  System.out.println(42);

   

  textView.setText("42");

  textView.setText(42);

  Java’s two System.out.println calls (rarely used in Android apps) add text to a log file. In the bad code, the first System.out.println sends the string "42" to the file, and the second System.out.println converts the integer value 42 to the string "42" and then sends the string "42" to the log file. (Java’s System.out.println is prepared to print a string, an integer, and various other types of values.) So far, there’s nothing wrong with the code. So let’s move on …

  A text view’s setText method accepts a string parameter or an integer parameter. In the bad code, the call textView.setText("42") is okay. But here’s the gotcha: The integer version of setText doesn’t convert the integer 42 into a string. Instead, textView.setText(42) looks for a resource with code number 42 (in R.java, hex value 0x0000002A). When Android finds nothing with code number 42 in the R.java file, your app crashes.

The assets directory

When Android packages an app, a tool named aapt (short for Android Asset Packaging Tool) compiles the stuff in the app’s res directory. In other words, aapt prepares the res directory’s items for quick retrieval and use. So your application’s access to items in the res directory is highly optimized.

But before there was Android, there was plain old Java, and plain old Java has its own ways to fetch images and strings. Using Java’s techniques, you generally read byte by byte from the Internet or from a device’s file system. To make your Android code grab an image or some other data using Java’s standard tricks, put the image or data in the Android project’s assets directory.

By default, an Android Studio project (the kind of project that’s displayed in Figure 4-2) doesn’t have an assets directory. To create such a directory, do the following:

1. In the Project tool window (Figure 4-2) right-click the app branch at the top of the tree. (If you’re a Mac user, control-click that branch.)

   A context menu appears.

2. In the context menu, choose New ⇒ Folder ⇒ Assets Folder.

   A dialog box appears.

3. In the dialog box, click Finish.

As a result, you see a new assets branch in the Android Project tree.

The android.jar archive

Each Android project’s CLASSPATH includes Android’s pre-declared Java code, and this pre-declared code lives in an android.jar archive file.

In Android Studio, you can see android.jar by switching to the Project view. Follow the instructions on switching views in the sidebar “The many faces of Android Studio.” When the Project view replaces the Android Project view, visit the External Libraries/Android API branch of the tree.

A .jar file is a compressed archive containing a useful bunch of Java classes. In fact, a .jar file is a Zip archive. You can open any .jar file with WinZip, StuffIt Expander, or your operating system’s built-in unzipping utility. (You may or may not have to change the file’s name from whatever.jar to whatever.zip.) Anyway, an android.jar file contains Android’s Java classes for a particular version of Android.

For more information about .jar files and .zip files, see Book II, Chapter 4.

The android.jar file contains code grouped into Java packages, and each package contains Java classes. (Figures 4-5 and 4-6 show only the tip of the android.jar iceberg.) The android.jar file contains classes specific to Android and classes that simply help Java to do its job. Figure 4-5 shows a bunch of Android-specific packages, and Figure 4-6 displays some all-purpose Java packages.

The APK file

Android puts the results of all its compiling, packaging, and other “ings” into a single file with the .apk extension. This APK file contains everything a user’s device needs to know in order to run your app. When you install a new app on your Android device, you download and install a new APK file.

An important job of the Gradle tool is to combine your app’s file into one APK file. This happens each time you choose Run ⇒ Run ‘app' in Android Studio’s main menu.

You can find an app’s APK file using your Windows File Explorer or Macintosh Finder. For an Android Studio project, the APK file is in the project’s app/build/outputs/apk subdirectory.