Common Default Resources Folders

The most common of the default resources (/res) subfolders are shown in the Figure 4-1. The following are the eight provided when you create a project in Eclipse:

• layout: UI screen layouts go in the /res/layout folder, which holds XML files containing UI layout definitions written in XML.
• drawable-hdpi : high-resolution images in PNG format (which Google prefers) or the JPEG format (acceptable but not favored by Google) go into the /res/drawable-hdpi (high resolution screen-drawable imagery, usually 800 by 480 pixels) folder.
• drawable-ldpi : low-resolution images in PNG format (which Google prefers) or the JPEG format (acceptable but not favored by Google) go into the /res/drawable-ldpi (low resolution screen-drawable imagery, usually 320 by 240 pixels) folder.
• drawable-mdpi: medium-resolution images in PNG format (which Google prefers) or the JPEG format (acceptable but not favored by Google) go into the /res/drawable-mdpi (medium resolution screen-drawable imagery, usually 480 by 320 pixels) folder.
• drawable-xhdpi: extra-high-resolution images in PNG format (which Google prefers) or the JPEG format (acceptable but not favored by Google) go into the /res/drawable-xhdpi (high resolution screen-drawable imagery, usually 1,280 by 720 pixels or HD)  folder
• values: XML files that define constant values are in the res/values folder.
• values-v11 : honeycomb theme XML files that define new UI theme values are in the res/values-v11 (referencing API Level 11 through 13, also known as Android 3.x or 3.0, 3.1, and 3.2) folder.
• values-v14: Ice Cream Sandwich theme XML files that define new UI theme values are in the res/values-v14 (referencing API Level 14 through 16, also known as Android 4.x or 4.0, 4.0.3, and 4.1) folder.
• menu : XML files defining menu layouts are in the res/menu folder.

The Values Folder

Let’s examine the res/values folder from one of my current projects in more detail. This is where you place predefined application values in the form of XML files that define the variable names (x or y, for instance) and their values that are later referenced in your Java code. For example, these values might be strings (collections of text characters) or constants (hard-coded values that your Java code uses in its program logic and can’t change).

Think of the values folder as holding all of your constant values for your application in one place. This way, if you need to adjust them during application development and testing, you make the changes in a single location.

Figure 4-2 shows a few examples of files that can be placed in this folder as in the following:

• colors.xml: An XML file that will define the color values to be used in the app. These allow you to standardize the UI. For example, you would define your background color. Then, if you decide to tweak it later, you need to do the tweaking in only one place.
• dimens.xml: An XML file that defines dimension values, such as standard heights and font sizes for your UI. You can then use these values across your app to ensure it is consistent.
• arrays.xml: An XML file that defines a series of values to be used together (known as an array). For example, this could be a list of icon files or a list of options to display to the user.
• strings.xml: An XML file that defines text strings to be used in the application. For example, you can place any screen titles or the app’s name here and reference them in your code. If you need to change these items, you simply do it here rather than in your code.
• styles.xml: An XML file that defines styles to be used in the application. These styles are then applied to the UI elements that require them, so you separate the look of your app from the layout and functionality. This makes your app easier to maintain.

Notice the Android file name conventions for the different types of XML files in the values folder, adding another level of complexity.

Screen Sizes

Because UI designs can be defined precisely by an XML file, it’s easy to deal with the variety of screen sizes available on Android devices today. Let’s say that you want to do a custom layout for each of the four primary screen sizes used in Android phones:

• Quarter VGA (QVGA), 240 × 320 pixels also known as low DPI or LDPI
• Half VGA (HVGA), 320 × 480 pixels (the “sweet spot” for low-cost  Android phones) also known as medium DPI or MDPI
• Wide VGA (WVGA), 800 × 480 pixels (found on the newer phones and now a common tablet and e-reader resolution) also known as High DPI or HDPI
• Wide SVGA (WSVGA), 1,024 × 600 pixels (found on the newest smartphones and tablets) also known as extra high DPI or XHDPI
• HDTV 1280 x 720 and 1920 x 1080 (found on HD smartphones, tablets, e-readers and iTVs) also known as TVDPI

How does XML provide a solution? Simply create a UI design in XML for each size and use Java to determine the screen resolution of the phone. We also noted in the previous section that Android provides drawable folders for the graphics file assets for each of these standard screen resolutions, so be aware that you must develop graphics for at least four different screen size targets for your Android applications. No one said that Android applications development was going to be easy!

Desktop Clocks

As another example of how XML can be leveraged, let’s take a look at a few lines of code that define an important utility: Android’s popular desktop clock. (In Chapter 6, you’ll learn how to create your own custom desktop clocks.)

The XML tag for an Android program function usually has the same name as its Java counterpart, so you can access the power of the programming language from simple XML. For example, here is the XML tag that corresponds to Java’s AnalogClock:

<AnalogClock />

Android’s XML tags start with a left-angle bracket (<), followed immediately (no space) by a class name, a space, a slash mark, and a right-angle bracket (/>).

To customize an AnalogClock, you must add attributes to the AnalogClock tag, inserting them before the closing part of the tag (/>). Suppose you want to add an ID to reference the utility from other parts of the application. Here’s how:

<AnalogClock android:id="@+id/AnalogClock" />

This adds an ID to your AnalogClock with the name AnalogClock, which you can use to reference it elsewhere in your application.

For each XML tag in Android, there are dozens of parameters that allow you to control the tag’s appearance and implementation, including its positioning, naming (used in the Java code), and other options.

In real-life, for readability, programmers usually write this code with each configuration parameter indented on a separate line, like this:

<AnalogClock
        android:id="@+id/AnalogClock"
        android:layout_width="fill_parent"
        android:layout_height="wrap_content"
/>

Bitmap Images

Let’s look at an example of a common application resource: the bitmap image. Your PNG or JPEG bitmap image goes into its proper /res/drawable folder depending on its pixel dimensions. It can then be referenced by its file name only (excluding its extension) in the Java code, as well as in XML. For this important reason, be sure not to give a PNG file and a JPG file the same name, or you will have problems when it comes time to compile your code.

Also, contrary to normal file-naming conventions, image file names can contain only numbers, an underscore character, and lowercase letters, so make sure to remember this rule (one of the many anomalies of Android programming).

In summary, to set up bitmap images to be used in your application, do the following:

• Name them correctly, using only numbers, underscores, and lowercase letters.
• Use the PNG or JPG format, or WebP if you are creating apps for the Android 4 or later (4.0, 4.0.4, and 4.1) platforms only.
• Make sure they are in the proper /res/drawable folder, based on their pixel dimensions, so that Android can find them.

Alternate Resource Folders

Another great example of resource usage is supplying different UI screen layouts for portrait and landscape orientations. Usually, we will set our default screen UI for phones to portrait mode, as most people use their phone in this way (turning it sideways only to view video).

Android provides support for alternate resources. If you set them up correctly, Android will determine the current settings and use the correct resource configurations automatically. In other words, you provide resources for each orientation, and Android uses the correct resources as the user changes from one orientation to another.

Each set of alternative resources is in its own folder, where it can be referenced and located later on in your Java code. We can provide resources for different screen orientations and resolutions in this fashion, and have Android decide which folders to look in for our application resources based on each user’s smartphone, tablet, or e-reader model.

Android currently offers four screen resolutions: low resolution (320 × 240), medium resolution (480 × 320), high resolution (800 × 480) and extra high resolution (1,024 × 600 or 1,280 × 720). Look for a fifth TVDPI resolution 1,920 × 1,080 classification to be added in Android 4.2 to accommodate Google TV and HD iTVs. Note that you can always add your own alternate resources folders now, Android just creates the /drawable-ldpi folders for you as a convenience and to remind you to provide graphics for all the common device screen sizes, but if you were doing an iTV app you could create a /drawable-tvdpi folder yourself and reference it from your app.

To add an alternate resource folder, create a directory under /res with the form <resource_name>−<config-qualifier>. For instance, android created /res/drawable-hdpi for you in its New Project Creation Process, to hold your high DPI resolution drawables or images.

This created an alternate resource folder for high-density dots per inch (hdpi) images. The alternate folder will be used automatically if the Android smartphone screen uses a WVGA (800 × 480) screen high-end model. Otherwise, it will use the normal HVGA (320 × 480) screen images, located in the default /res/drawable-mdpi folder, if the device screen resolution is not automatically detected.

If you want to also support low-end screens, you can use the low-density dots per inch qualifier, ldpi. There is a medium-density dots per inch qualifier, mdpi, as well as an extra high dots per inch qualifier called xhdpi.

So, to have images for QVGA, HVGA, WVGA, and WSVGA screens arranged into folders in a way that allows Android to automatically recognize the folder hierarchy, set up your folder structure as follows:

• /res, with only subfolders, place NO individual files in this folder
• /res/drawable-ldpi, with the following low-density DPI (120 DPI) screen images (QVGA):

• ic_launcher.png (application icon file), 36 × 36 pixels
• background.png (application background), 320 × 240 pixels

• /res/drawable-mdpi, with the following medium-density DPI (160 DPI) screen images (HVGA):

• ic_launcher.png, 48 × 48 pixels
• background.png, 320 × 480 pixels

• /res/drawable-hdpi, with the following high-density DPI (240 DPI) screen images (WVGA):

• ic_launcher.png, 72 × 72 pixels
• background.png, 800 × 480 pixels

• /res/drawable-xhdpi, with the following extra-high-density DPI (320 DPI) screen images (WSVGA or HDTV):

• ic_launcher.png, 96 × 96 pixels
• background.png, 1,024 × 600 or 1,280 × 720 pixels

Note that there are two HDTV resolution graphics standards, HDTV 1,280 by 720 and True HD 1,920 by 1,080. You’re well on your way to correctly setting up your Android application’s resources. One more file we need to examine is AndroidManifest.xml.

Launching Eclipse

The first step is to launch Eclipse Juno 4.2 for Java EE. From there, you’ll create an Android project to house the application code, markup, and assets.

To launch Eclipse, find and click the Eclipse shortcut launch icon on your workstation. If a security warning dialog like the one shown in Figure 4-3 appears, click Run. If you don’t want to see this dialog every time you start Eclipse, uncheck the box that reads “Always ask before opening this file.”

Next you will see the Eclipse Juno startup screen. Then, in a few more seconds, a dialog will appear, allowing you to tell Eclipse where your projects folder is kept on your hard disk drive. I’m going to accept the default User Directory with my nickname, so the entry is C:UsersWallsworkspace, as shown in Figure 4-4. If you don’t want to specify this each time you start Eclipse, you can check the “Use this as the default and do not ask again” option. Once you click the OK button, Eclipse will start, and the IDE will appear.

Creating an Android Project

1. Once the IDE has launched, select File New Project in the Eclipse main menu to create a new project just like we did in Chapter 3 to see if Android Development Tools had installed correctly inside of Eclipse. This is shown in Figure 4-5 using two screenshots combined into one (to save space) the File New Project menu sequence as well as the resulting New Project Dialog.
2. In the New Project dialog, open the Android folder using the arrow just to the left.
3. Next, select Android Application Project from the list of wizards to tell Eclipse the type of project you wish to create, as shown on the right in Figure 4-5. Click the Next button to continue.

Next you’ll see the New Android Application dialog, which allows you to specify all types of important variables for your applications. Let’s address them one by one.

• Application Name: This is the name of the application and will be displayed on the top of the screen on the Android device. Let’s give this the same name as our Project name (note that the dialog does this for you as you type it in, entering it into both fields): HelloAbsoluteBeginner.

• Project Name: This is the name of the folder in your C:UsersYourNameworkspace folder that holds your Hello Absolute Beginner application folders and files. Let’s give this folder the same name as our application: HelloAbsoluteBeginner
• Package name: This is the name you want to use for your Java package. For now, we will simply define this as the name of the container that will hold all of the Java code our application uses. Let’s name this package first.example.helloabsolutebeginner. (Java package names are separated by periods, much like file pathnames are separated by back slashes.)
• Build SDK: This panel allows you to specify the version of Android that your application will support. The more you support, the more users will be able to use your application, so usually we would use a build target of Android 1.6. That version has everything that we will need to build most applications that work across all current Android smartphones. For now, however, let’s just accept the default current API Level 16, which means we’re developing this first application to run on the current Android 4.1 Jelly Bean platform and 4.1 phone and tablet emulator we just installed in Chapter 3.
• Minimum Required SDK: I am also going to accept the default Minimum Required SDK of API Level 8, which means your application will be compatible back to Android 2.2 smartphones and tablets, meaning users with Android 2.2, 2.3.7, 3.0, 3.1, 3.2, 4.0, 4.0.4, and 4.1 compatible hardware will be able to run the application.
• Create Custom Launcher Icon: Leave this box selected so that we can see the dialog (next) that helps to automate creation of an App Icon for the Launch Area on your Android smartphone or tablet. We also will see how to create these icons manually later on in this chapter as well.
• Create Project in Workspace: Leave this box selected as well so that Android will create the project folder structure for this application under your C:/Users/Name/workspace/ folder on your system’s hard disk drive.

Figure 4-6 shows the completed New Android Application dialog for this example. When you are finished filling it out, click the Next button.

After you click the Next button in the New Android Application dialog, you will get the Configure Launcher Icon Dialog as shown in Figure 4-7. Because we haven’t created our Application Launch Icons as yet, just accept the default settings and click on the Next button to advance on into the new Android App project creation process.

Next you will see the Create Activity Type Dialog shown in Figure 4-8 and for which we will be selecting a settings value of “Blank Activity,” so that we can create a Blank (basic) Activity and see the basic (minimum) code that the New Android App functionality in Eclipse will create for us automatically. This auto-code generation is just what we need right now as an absolute beginner, and as you will see Android Development Tools in Eclipse does a great job at giving new developers a head start by writing some of the basic application bootstrapping code for them! Let’s hit the Next button shown in Figure 4-8 and continue the New Android App project creation process to set the parameters for our Activity as shown in Figure 4-9.

The New Blank Activity Dialog allows us to set the parameters for our apps activity, which is essentially the user interface or “front end” of our app that the users will use to control and utilize the app. Let’s use “HelloActivity” for our Activity Name and Title and “activity_hello” as our layout (user interface) name as shown in Figure 4-9. Leave the Navigation Type and Hierarchical Parent settings at their defaults for now, and let’s see how Android inserts our naming conventions into the Java code and XML markup for our app. Click on the Next button to continue the process.

Normally the New Android Application process would now create your New Android Project for you, but before it does so, it checks the state of your current Android Development Environment Installation (which we created in Chapter 3) to make sure that you have all of the SDKs, APIs, and so on that will be needed for the New Project you are specifying. In this case, Android found a missing API that would be needed to be installed for this Application to work (compile) properly, so it brings up the following dialog to let you know it needs something to be added to your current development environment. Again I am combining two screens into one in Figure 4-10 to show both the alert dialog and the repository search and fetch progress after you click the “Install/Update” button, to OK the addition of Android 2.2 support to your collection of SDKs and APIs. Make sure you are connected to the Internet before clicking the Install/Update button shown in Figure 4-10! Note that if your Android installation is 100% up to date that you will not get the Install Dependencies dialog and will not have to go through the process shown here in Figures 4-10 through 4-12.

After you click the Install/Upgrade button in the New Android Application dialog, and the necessary files are located and fetched from the repository, you will get the Choose Packages to Install Dialog as shown in Figure 4-11. Select the Accept All Radio Button as we have in the past and then click on the Install button to have the Froyo Android 2.2 API packages installed via your Internet connection.

After you click Install in the Choose Packages to Install dialog, you will get the progress bar dialog shown in Figure 4-12 showing you the speed and progress of your installation.

Once the Android 2.2 API installations are complete you will be finished with the New Android Application Project Creation and returned to Eclipse where the IDE will now be populated with your new (empty) project ready for development!

Inspecting and Editing the Android Application Files

After you click Finish in the New Android Application dialog, you are returned to Eclipse. In the IDE, you can navigate through the new (empty) project structure using the Package Explorer pane.

Let’s look at the folder hierarchy that Eclipse has automatically created for our project. Click the arrow icons next to the HelloAbsoluteBeginner folder, and then click the arrow icons next to the src and res folders under it.

Going further, click the open folder arrows next to the first.example.helloabsolutebeginner, menu, layout, and values folders, so you can see the Java and XML files that Eclipse has so kindly created for us. Figure 4-13 shows the Package Explorer pane at this point.

Now let’s open some of these files and see just how much coding Eclipse has done for this project.

To open any of the files listed in the Package Explorer, select the file by clicking once on it (the icon will turn blue), and then press F3. Alternatively, right-click the file name to get a context-sensitive menu, and then select the Open option. You will see that the activity_hello.xml file is already open, to see the markup code click the activity_hello.xml tab at the bottom right of the center coding area of Eclipse as shown in Figure 4-13. A later screen will show the Graphical Layout view of this XML file.

package first.example.helloabsolutebeginner;
 
import android.os.Bundle;
 
public class HelloActivity extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_hello);
    }
    @Override
    public boolean onCreateOptionsMenu(Menu menu) {
        getMenuInflater().inflate(R.menu.activity_hello, menu);
        return true;
    }
}

<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"
    >
<TextView
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_centerHorizontal="true"
    android:layout_centerVertical="true"
    android:text="@string/hello_world"
    tools:context=".HelloActivity"
    />
</RelativeLayout>

Setting a Variable Value in strings.xml

To set the value of hello_world, all you need to do is to click its name in the left pane of the Resources view and edit its text in the right pane of the Resources view. Once you click hello_world, two fields will appear. One contains the string variable name (hello_world), and the other has its value. In the Value field, type Hello Absolute Beginner!, as shown in Figure 4-17. This is the value (the text) that will appear on the screen of our App when we run it later on in this chapter.

Once you have entered a new string value for the hello_world variable, click the strings.xml tab at the bottom of the editing pane, and take a look at the XML code that Eclipse has generated for you, as shown in Figure 4-18.

In this view, you can see the actual XML code for the string tags, which are nested inside the <resources> tags that allow us to define resources for our Android application.

<resources>
    <string name="app_name">HelloAbsoluteBeginner</string>
    <string name="hello_world">Hello Absolute Beginner!</string>
    <string name="menu_settings">Settings</string>
    <string name="title_activity_hello">HelloActivity</string>
</resources>

Each <string> tag has a variable name attribute so we can refer to it by name in our Java code. Tags end with the same tag that they started with, but they have an added forward slash, like this: < string> XXX</ string>.

As you can see in the XML code, Eclipse has created the correct XML code for us to use to write our Hello World message to the smartphone, tablet, e-reader, or iTV screen. The code reads as follows:

<string name="hello_world">Hello Absolute Beginner!</string>

Now it’s time to save the strings.xml file you just edited using the CTRL-S shortcut (File Save) and then we can compile and run your first app, the Hello Absolute Beginner application.

Running the App

To compile and run the application, right-click the HelloWorldAndroid folder icon in the Eclipse Package Explorer and select Run As Android Application as shown in Figure 4-19.

The first thing Eclipse will do when you try to run your app is to make sure your files are all saved. If they are not, you will see a dialog like the one shown in Figure 4-20, which appears in this case because we modified the hello_world variable but did not hit the CTRL-S (Save) keystroke afterward that saves the file. Therefore, we’ll let Android Development Tools do it for us by clicking the “Yes” option in the dialog that asks us if we want to save the file before running the app.

Eclipse will then compile your app, and will open a version 4.1 emulator window to display a virtual Android device (smartphone or tablet) representation (emulator) on which to run it. When the emulator first starts up, it will display the standard smartphone (or it could be a tablet) screen, simulating an Android OS background image and the standard Android icons for system time, signal strength, battery charge level, network type (3G, 4G, etc.) and so on. Note that it may take some time for the emulator to load into memory (especially the first time) and to load your app and run it once it is in memory.

The app should launch automatically once the emulator starts, but if for some reason it doesn’t, to actually run the app in the emulator, you may need to click the Menu button in the center-bottom area of the screen, or use the Home button to display your application icons and then select an icon to run. Usually your application will just run automatically, you just need to wait long enough for this to happen. You can also use the phone interface, finding and running the app as you would in real life because this is a test environment. Give it a shot now. Figure 4-21 shows the Hello Absolute Beginner App running in the Android 4.1 emulator.

After you exit the 4.1 Emulator for the first time by clicking the Red X at the top right of the window, you will probably get an “Auto Monitor Logcat” error dialog as shown in Figure 4-22, which suggests that you enable ADT to automatically monitor the Logcat output for messages (usually error messages) from the Android Applications run in the Emulator. Select the “Yes, Monitor Logcat” option, and click on the OK button to continue.

After you click OK you will be returned to Eclipse where you will see what no programmer or developer wants to see in his or her IDE—Red Ink! The red text at the bottom of the IDE In the Console tab will show feedback on the compile and run process, and in this case it related not to problems in our code but to the fact that the Logcat was not set up, which we rectified in our previous step by telling the ADT to set it up for us. You can see the Logcat error messages in Figure 4-23.

To make sure that these error messages will go away once we have enabled the Logcat, let’s practice our right-click (on the project name) Run As Android Application menu sequence again, and see if we can get some black text in the console window this time, which is what we want to see and represents feedback on what ADT is doing to compile and run your app each time you invoke this Run As Android App menu sequence. The results are shown in Figure 4-24.

Congratulations, you have created your first error-free Android 4.1 application. Next, we’ll customize its Android icon.

Adding an Application Icon

The final item that we are going to do in this chapter is give our application an icon that will show up on users’ Android devices and can be used by them to launch the application. We’ll use what you have learned about defining alternate resources by creating an icon that works on small, medium, large, and extra large screens. We’ll add the appropriate ic_launcher.png files into the correct alternate dpi resolution folders provided by our Android Application project we just created, so that Android automatically finds and uses the correct application launcher icon for each type of Android device screen size and density:

• /res/drawable-ldpi for small low density dot per inch (LDPI) screens
• /res/drawable-mdpi for average medium density dot per inch (MDPI) screens
• /res/drawable-hdpi for large high density dot per inch (HDPI) screens
• /res/drawable-xhdpi for extra large extra-high density dot per inch (XHDPI) screens

Not surprisingly, this is done by giving your icon an exact name and file format, and putting it into an exact directory. When Android finds an icon file there, it automatically puts it into play as your application’s icon. The files must follow these rules precisely:

• Be placed in the correct /res/drawable-dpi folder, which holds all of the drawable resources for that screen resolution
• Be named ic_launcher.png
• Be a 24-bit PNG file with an alpha channel (transparency), also known as a 32-bit PNG, so that the icon overlays on any system background wallpaper seamlessly

Here, I’ll use my 3D company logo in an Android Green hue, but you can use any image that you like. Also, I will use open source GIMP 2.8 for this image editing example, because all readers will have it installed, but you can use any image-editing program you prefer, such as Photoshop CS6 or Corel Painter. So let’s fire up the GIMP 2.8 software package that we installed earlier in the book and prepare a 24-bit PNG file with transparency (alpha channel).