Problem

You’ve read the previous introduction to Android and are eager to develop your first Android app. However, you must install the Android SDK before you can develop apps.

Solution

Google provides the latest release of an Android SDK distribution file for each of the Windows, Intel-based Mac OS X, and i386-based Linux operating systems. Download and unarchive the appropriate file for your platform and move its unarchived home directory to a convenient location. You might also want to update your PATH environment variable so that you can access the SDK’s command-line tools from anywhere in your filesystem.

Before downloading and installing this file, you must be aware of SDK requirements. You cannot use the SDK when your development platform doesn’t meet these requirements.

The Android SDK supports the following operating systems:

• Windows XP (32-bit), Vista (32- or 64-bit), or Windows 7 (32- or 64-bit).
• Mac OS X 10.5.8 or later (x86 only).
• Linux (tested on Ubuntu Linux, Lucid Lynx). GNU C Library (glibc) 2.7 or later is required. On Ubuntu Linux, version 8.04 or later is required. 64-bit distributions must be able to run 32-bit applications. To learn how to add support for 32-bit applications, see the Ubuntu Linux installation notes at http://developer.android.com/sdk/installing/index.html#Troubleshooting.

You’ll quickly discover that the Android SDK is organized into various separately downloadable components, which are known as packages. You will need to ensure that you have enough disk storage space to accommodate the various packages that you want to install. Plan for around 2 gigabytes of free storage. This figure takes into account the Android API documentation and multiple Android platforms (also known as Android software stacks).

Finally, you should ensure that the following additional software is installed:

• JDK 6 or JDK 7: You need to install one of these Java Development Kits (JDKs) to compile Java code. It’s not sufficient to have only a Java Runtime Environment (JRE) installed.
• Apache Ant: You need to install Ant version 1.8 or later so that you can build Android projects from the command line using the current build system.
• Gradleware Gradle: Although it’s currently in beta, you may need to install Gradle version 1.6 or later to experiment with the new command-line build system that will be replacing Ant.

How It Works

Point your browser to http://developer.android.com/sdk/index.html and download one of the android-sdk_r22-windows.zip (Windows), android-sdk_r22-macosx.zip (Mac OS X), or android-sdk_r22-linux.tgz (Linux) distribution archives for Release 22 of the Android SDK. (Release 22 is the latest release at the time of this writing.)

For example, if you run Windows (the assumed platform in this chapter), you might choose to download android-sdk_r22-windows.zip. After unarchiving this file, move the unarchived android-sdk-windows home directory to a convenient location in your filesystem; for example, you might move the unarchived C:unzippedandroid-sdk_r22-windowsandroid-sdk-windows home directory to the root directory on your C: drive, resulting in C:android-sdk-windows.

To complete the installation, add the tools and platform-tools subdirectories to your PATH environment variable so that you can access the SDK’s command-line tools from anywhere in your filesystem.

A subsequent examination of android-sdk-windows (or android) shows that this home directory contains the following subdirectories and files:

• add-ons: This initially empty directory stores add-ons (additional SDKs beyond the core platform that apps can target) from Google and other vendors; for example, the Google APIs add-on is stored here.
• platforms: This initially empty directory stores Android platforms in separate subdirectories. For example, Android 4.1 would be stored in one platforms subdirectory, whereas Android 2.3.4 would be stored in another platforms subdirectory.
• tools: This directory contains a set of platform-independent development tools, such as the emulator. The tools in this directory, known as basic tools, may be updated at any time and are independent of Android platform releases.
• platform-tools: This directory contains the Android Debug Bridge (ADB), the utility used to connect to a device or emulator for the purposes of installing applications, pushing/pulling files, and accessing the device shell.
• AVD Manager.exe: This tool is used to manage Android Virtual Devices (AVDs), device configurations that are run with the Android emulator.
• SDK Manager.exe: This tool is used to manage SDK packages and runs AVD Manager in response to a menu selection.
• SDK Readme.txt: This text file welcomes you to the Android SDK and tells you that, in order to start developing apps, you need to use SDK Manager to install platform tools and at least one Android platform.

The tools directory contains various useful basic tools, including the following:

• android: Creates and updates Android projects; updates the Android SDK with new Android platforms and more; and creates, deletes, and views AVDs.
• emulator: Runs a full Android software stack down to the kernel level; includes a set of preinstalled apps (such as Browser) that you can access.
• hierarchyviewer: Provides a visual representation of a layout’s view hierarchy (the Layout view) and a magnified inspector of the display (the Pixel Perfect view) so that you can debug and optimize your activity screens.
• sqlite3: Manages SQLite databases created by Android apps.
• zipalign: Performs archive alignment optimization on APK files.

You will look at many of these tools in greater detail throughout the book.

Problem

Installing the Android SDK is insufficient for developing Android apps; you must also install at least one Android platform.

Solution

Use the SDK Manager tool to install an Android platform. If SDK Manager doesn’t display its Android SDK Manager dialog box, you probably need to create a JAVA_HOME environment variable that points to your JDK’s home directory (for example, set JAVA_HOME=C:Program FilesJavajdk1.7.0_04) and try again.

Alternatively, you can use the android tool to install an Android platform. If android shows Failed to convert path to a short DOS path: C:Windowssystem32java.exe, locate a file named find_java.bat (see C:android oolslibfind_java.bat) and remove -s from each of the following lines:

for /f %%a in ('%∼dps0find_java.exe -s') do set java_exe=%%a
for /f %%a in ('%∼dps0find_java.exe -s -w') do set javaw_exe=%%a

How It Works

Run SDK Manager or android. Either tool presents the Android SDK Manager dialog box that is shown in Figure 1-1.

The Android SDK Manager dialog box presents a menu bar and a content area. The menu bar presents Packages and Tools menus:

• Packages: Use this menu to display a combination of updates/new packages, installed packages, and obsolete packages; to show archive details (or not); to sort packages by API level or repository; and to reload the list of packages shown in the content area.
• Tools: Use this menu to manage AVDs and add-on sites, to specify the proxy server and other options, and to display an About dialog box.

The content area shows you the path to the SDK, a table of information on packages, check boxes for choosing which packages to display, radio buttons for sorting packages by API level or repository, buttons for installing and deleting packages, and a progress bar that shows the progress of a scan of repositories for package information.

The Packages table classifies packages as tools, specific Android platforms, or extras. Each of these categories is associated with a check box that, when checked, selects all of the items in the category. Individual items can be deselected by unchecking their corresponding check boxes.

Tools are classified as SDK tools or SDK platform tools:

• SDK tools are the basic tools that are included in the SDK distribution file and that are stored in the tools directory. This fact is borne out by the Installed message in the status column for the Android SDK Tools item.
• SDK platform tools are platform-dependent tools for developing apps. These tools support the latest features of the Android platform and are typically updated only when a new platform becomes available. They are always backward-compatible with older platforms, but you must make sure that you have the latest version of these tools when you install a new platform. If you don’t select the Android SDK Platform tools item (which is not selected by default), the platform tools will be installed automatically.

The only platform that you need to install for this book is Android 4.4 (Level 19). This category and all of its items are selected, so leave them as is. As well as this platform, you will install the documentation, samples, ARM and/or x86 system image (for creating emulator instances), Google APIs, and source code.

Finally, you can install extras, which are external libraries or tools that can be included or used when building an app. For example, the Google USB Driver item is already selected in the Extras section. However, you need to install this component only when developing on a Windows platform and testing your apps on an actual Android device.

Click the Install Packages button (the number will differ should you choose to install more or fewer packages). You’ll encounter the Choose Packages to Install dialog box shown in Figure 1-2.

The Choose Packages to Install dialog box shows a Packages list that identifies those packages that can be installed. It displays green check marks beside packages that have been accepted for installation, and it displays question marks beside those packages that have not yet been selected.

For the highlighted package, Package Description & License presents a package description, a list of other packages that are dependent on this package being installed, information on the archive that houses the package, and additional information. Click the Accept or Reject radio button to accept or reject the package.

Click the Install button to begin installation. Android proceeds to download and install the chosen packages; you may also track the download progress by using the Android SDK Manager Log dialog box, which is accessible using the icon on the far right of the progress bar at the bottom of the window. This dialog box appears in Figure 1-3.

Upon completion, you should observe a “Done loading packages” message at the bottom of the Android SDK Manager Log and Android SDK Manager dialog boxes. Click the Close button on the former dialog box; the Status column in the Packages table on the latter dialog box will tell you which packages have been installed.

You should also observe several new subdirectories of the home directory, including the following:

• platform-tools (in android)
• android-19 (in android/platforms)

Problem

After installing the Android SDK and an Android platform, you’re ready to start creating Android apps. However, you won’t be able to run those apps via the emulator tool until you create an Android Virtual Device (AVD), a device configuration that represents an Android device.

Solution

Use the AVD Manager or android tool to create an AVD.

How It Works

Run AVD Manager (or select Manage AVDs from the Android SDK Manager dialog box’s Tools menu). Figure 1-4 shows the Android Virtual Device Manager dialog box.

Click the New button. Figure 1-5 shows the resulting Create New Android Virtual Device (AVD) dialog box.

Figure 1-5 reveals that an AVD has a name, targets a specific Android platform, targets a specific CPU/ABI (Application Binary Interface, such as ARM/armeabi-v7a), can emulate an SD card, provides a skin with a certain screen resolution, and has various hardware properties.

Enter a name, target device, target platform (you may have only one choice), and any other device options you would like. If your machine has an attached or built-in webcam, this can be used to emulate the device’s front or rear cameras as well.

After making all the appropriate selections, finish the AVD creation by clicking Create AVD. Figure 1-4’s AVD pane now includes an entry for your new AVD.

Although it’s easier to use AVD Manager to create an AVD, you can also accomplish this task via the android tool by specifying android create avd -nname-ttargetID[-optionvalue].... Given this syntax, name identifies the device configuration (such as target_AVD), targetID is an integer ID that identifies the targeted Android platform (you can obtain this integer ID by executing android list targets), and [-optionvalue]... identifies a series of options (such as SD card size).

If you don’t specify sufficient options, android prompts to create a custom hardware profile. Press the Enter key when you don’t want a custom hardware profile and prefer to use the default hardware emulation options. For example, the android create avd -n AVD1 -t 1 command line causes an AVD named AVD1 to be created. This command line assumes that 1 corresponds to the Android 4.1 platform and prompts to create a custom hardware profile.

Problem

You must start the emulator with the AVD so that you can install and run apps. You want to know how to accomplish this task.

Solution

Use the AVD Manager tool to start the AVD. Or start the AVD by using the emulator tool.

How It Works

Refer to Figure 1-4 and you’ll notice a disabled Start button. This button is no longer disabled after an AVD entry is created (and highlighted). Click Start to run the emulator tool with the highlighted AVD entry as the emulator’s device configuration.

A Launch Options dialog box appears. This dialog box identifies the AVD’s skin and screen density. It also provides unchecked check boxes for scaling the resolution of the emulator’s display to match the physical device’s screen size, for wiping user data, for launching from a previously saved snapshot, and for saving device state to a snapshot upon device exit.

Click the Launch button to launch the emulator with AVD1. AVD Manager responds by briefly displaying a Starting Android Emulator dialog box followed by the emulator window. See Figure 1-6.

Figure 1-6 shows that the emulator window is divided into a left pane, which displays the Android logo on a black background followed by the home screen, and a right pane, which displays phone controls. If, when creating the AVD, you unchecked the box for including hardware controls, the emulator will start up showing just the device display.

A status bar appears above the home screen (and every app screen). The status bar presents the current time, amount of battery power remaining, and other information; it also provides access to notifications.

The home screen initially appears in locked mode. To unlock this screen, drag the lock icon to its right until it touches an unlock icon. You should end up with the unlocked home screen shown in Figure 1-7.

The home screen presents the following items:

• Wallpaper background: Wallpaper appears behind everything else and can be dragged to the left or right. To change this background, press and hold down the left mouse button over the wallpaper, which causes a wallpaper-oriented pop-up menu to appear.
• Widgets: The Google Search widget appears near the top, the Clock widget appears upper-centered, and the Camera widget appears near the bottom left. A widget is a miniature app view that can be embedded in the home screen and other apps, and receives periodic updates.
• App launcher: The app launcher (along the bottom) presents icons for launching the commonly used Browser, Contacts, Messaging, and Phone apps; it also displays a rectangular grid of all installed apps, which are subsequently launched by single-clicking their icons. Figure 1-8 shows some of these icons.

The app launcher organizes apps and widgets according to the tabs near the top left of the screen. You can run apps from the APPS tab, and select additional widgets to display on the home screen from the WIDGETS tab. (If you need more room for widgets on the home screen, drag its wallpaper in either direction.)

The phone controls include the following commonly used buttons:

• The house icon phone control button takes you from wherever you are to the home screen.
• The MENU phone control button presents a menu of app-specific choices for the currently running app.
• The curved arrow icon phone control button takes you back to the previous activity in the activity stack.

While the AVD is running, you can interact with it by using your mouse to “touch” the touch screen, and your keyboard to “press” the AVD keys. Table 1-2 shows you the mappings between AVD keys and keyboard keys.

Table 1-2 refers to the -trace startup option in the context of toggle code profiling. This option lets you store profiling results in a file when starting the AVD via the emulator tool.

For example, emulator -avd AVD1 -trace results.txt starts the emulator for device configuration AVD1, and it also stores profiling results in results.txt when you press F9—press F9 again to stop code profiling.

Figure 1-6 displays 5554:AVD on the title bar. The 5554 value identifies a console port that you can use to dynamically query and otherwise control the environment of the AVD.

You can connect to the AVD’s console by specifying telnet localhostconsole-port. For example, specify telnet localhost 5554 to connect to AVD1’s console. Listing 1-1 shows you the resulting commands.

Listing 1-1. Typing a Command Name by Itself for Command-Specific Help

Android Console: type 'help' for a list of commands
OK
help
Android console command help:
 
    help|h|?         print a list of commands
    event            simulate hardware events
    geo              Geo-location commands
    gsm              GSM related commands
    cdma             CDMA related commands
    kill             kill the emulator instance
    network          manage network settings
    power            power related commands
    quit|exit        quit control session
    redir            manage port redirections
    sms              SMS related commands
    avd              control virtual device execution
    window           manage emulator window
    qemu             QEMU-specific commands
    sensor           manage emulator sensors
 
try 'help <command>' for command-specific help
OK

Problem

You prefer to develop apps by using the Eclipse IDE.

Solution

To develop apps with Eclipse, you need to install an IDE such as Eclipse Classic 4.2. Furthermore, you need to install the Android Development Tools (ADT) plug-in.

How It Works

Before you can develop Android apps with Eclipse, you must complete at least the first two of the following three tasks:

1. Install the Android SDK and at least one Android platform. JDK 6 or JDK 7 must also be installed.
2. Install a version of Eclipse that’s compatible with the Android SDK and the ADT plug-in for the Eclipse IDE.
3. Install the ADT plug-in.

You should complete these tasks in the order presented. You cannot install the ADT plug-in before installing Eclipse, and you cannot configure or use the ADT plug-in before installing the Android SDK and at least one Android platform.

The Eclipse.org website makes available for download several IDE packages that meet different requirements. Google places the following stipulations on which IDE package you should download and install:

• Install an Eclipse 3.6.2 (Helios) or greater IDE package.
• Make sure that the Eclipse package being downloaded includes the Eclipse Java Development Tools (JDT) plug-in. Most packages include this plug-in.

Complete the following steps to install Eclipse Classic 4.2, which is the latest version of this IDE at the time of this writing:

1. Point your browser to the Eclipse Classic 4.2 page at http://eclipse.org/downloads/packages/eclipse-classic-42/junor.
2. Select the appropriate distribution file by clicking one of the links in the Download Links box on the right side of this page. For example, you might click Windows 64-bit platform.
3. Click a download link and save the distribution file to your hard drive. For example, you might save eclipse-SDK-4.2-win32-x86_64.zip to your hard drive.
4. Unarchive the distribution file and move the eclipse home directory to a convenient location. For example, on 64-bit Windows 7, you would move eclipse to your C:Program Files directory, which organizes 64-bit programs.
5. You might also want to create a desktop shortcut to the eclipse application located in the eclipse home directory.

Complete the following steps to install the latest revision of the ADT plug-in:

1. Start Eclipse.
2. The first time you start Eclipse, you will discover a Workspace Launcher dialog box following the splash screen. You can use this dialog box to select a workspace folder in which to store your projects. You can also tell Eclipse to not display this dialog box on subsequent startups. Change or keep the default folder setting and click OK.
3. Once Eclipse displays its main window, select Install New Software from the Help menu.
4. Click the Add button in the resulting Install dialog box’s Available Software pane.
5. In the resulting Add Repository dialog box, enter a name for the remote site (for example, Android Plugin) in the Name field, and enter
   https://dl-ssl.google.com/android/eclipse/ into the Location field. Click OK.
6. You should now see Developer Tools and NDK Plugins in the list that appears in the middle of the Install dialog box.
7. Select the check box next to these categories, which will automatically select the nested items underneath. Click Next.
8. The resulting Install Details pane lists Android DDMS, Android Development Tools, Android Hierarchy Viewer, Android Native Development Tools, Android Traceview, and Tracer for OpenGL ES. Click Next to read and accept the various license agreements, and then click Finish.
9. An Installing Software dialog box appears and takes care of installation. If you encounter a Security Warning dialog box, click OK.
10. Finally, Eclipse presents a Software Updates dialog box that prompts you to restart this IDE. Click Yes to restart.

To complete the installation of the ADT plug-in, you may have to configure it by modifying the ADT preferences in Eclipse to point to the Android SDK home directory. Accomplish this task by completing the following steps:

1. Select Preferences from the Window menu to open the Preferences dialog box. For Mac OS X, select Preferences from the Eclipse menu.
2. Select Android from the left panel.
3. If the SDK Location text field presents the SDK’s home directory (such as C:android), close the Preferences dialog box. You have nothing further to do.
4. If the SDK Location text field does not present the SDK’s home directory, click the Browse button beside this text field and locate your downloaded SDK’s home directory on the resulting Browse For Folder dialog box. Select this location, click OK to close this dialog box, and click Apply in the Preferences dialog box to confirm this location, which should result in a list of SDK Targets (such as Android 4.1) appearing below the text field.

Problem

You want to create a library that stores Android-agnostic code and that can be used in your Android and non-Android projects.

Solution

Create a JAR-based library that accesses only Java 5 (and earlier) APIs via JDK command-line tools or Eclipse.

How It Works

Suppose you plan to create a simple library of math-oriented utilities. This library will consist of a single MathUtils class with various static methods. Listing 1-2 presents an early version of this class.

Listing 1-2. MathUtils Implementing Math-Oriented Utilities via static Methods

package com.androidrecipes.lib;
 
public class MathUtils {
   public static long factorial(long n) {
      if (n <= 0)
         return 1;
      else
         return n*factorial(n-1);
   }
}

MathUtils currently consists of a single long factorial(long n) class method for computing and returning factorials (perhaps for use in calculating permutations and combinations). You might eventually expand this class to support fast Fourier transforms and other math operations not supported by the java.lang.Math class.

Problem

You want to create a library that stores Android-specific code, such as custom widgets or activities with or without resources.

Solution

You can create Android library projects, which are projects containing shareable Android source code and resources and which you can reference in other Android projects. This is useful when you want to reuse common code. Library projects cannot be installed onto a device. They are pulled into the APK file at build time.

How It Works

Suppose you want to create a library that contains a single reusable custom view describing a game board (for playing chess, checkers, or even tic-tac-toe). Listing 1-3 reveals this view’s GameBoard class.

Listing 1-3. GameBoard Describing a Reusable Custom View for Drawing Different Game Boards

public class GameBoard extends View {
   private int nSquares, colorA, colorB;
 
   private Paint paint;
   private int squareDim;
 
   public GameBoard(Context context, int nSquares, int colorA,
         int colorB) {
      super(context);
      this.nSquares = nSquares;
      this.colorA = colorA;
      this.colorB = colorB;
      paint = new Paint();
   }
 
   @Override
   protected void onDraw(Canvas canvas) {
      for (int row = 0; row < nSquares; row++) {
         paint.setColor(((row & 1) == 0) ? colorA : colorB);
         for (int col = 0; col < nSquares; col++) {
            int a = col*squareDim;
            int b = row*squareDim;
            canvas.drawRect(a, b, a+squareDim, b+squareDim,
                  paint);
            paint.setColor(
                  (paint.getColor() == colorA) ? colorB : colorA);
         }
      }
   }
 
   @Override
   protected void onMeasure(int widthMeasuredSpec,
         int heightMeasuredSpec) {
      // keep the view squared
      int width = MeasureSpec.getSize(widthMeasuredSpec);
      int height = MeasureSpec.getSize(heightMeasuredSpec);
      int d = (width == 0) ? height : (height == 0) ? width :
              (width < height) ? width : height;
      setMeasuredDimension(d, d);
      squareDim = width/nSquares;
   }
}

In Android, a custom view extends android.view.View or one of its subclasses (such as android.widget.TextView). GameBoard extends View directly because it doesn’t need any subclass functionality. We'll talk more about creating custom views in Chapter 2.

GameBoard declares the following fields:

• nSquares stores the number of squares on each side of the game board. Typical values include 3 (for a 3-by-3 board) and 8 (for an 8-by-8 board).
• colorA stores the color of even-numbered squares on even-numbered rows, and the color of odd-numbered squares on odd-numbered rows—row and column numbering starts at 0.
• colorB stores the color of odd-numbered squares on even-numbered rows, and the color of even-numbered squares on odd-numbered rows.
• paint stores a reference to an android.graphics.Paint object that is used to specify the square color (colorA or colorB) when the game board is drawn.
• squareDim stores the dimension of a square—the number of pixels on each side.

GameBoard’s constructor initializes this widget by storing its nSquares, colorA, and colorB arguments in same-named fields, and it also instantiates the Paint class for use in drawing.

android create lib-project --targettarget_ID
                     --nameyour_project_name
                     --path /path/to/your/project/project_name
                     --packageyour_library_package_namespace

android.library=true

android create lib-project -t 1 -p <path/to/project/directory>
                           -k com.androidrecipes.gameboard

Problem

Google keeps improving Android by offering new features (such as fragments) in SDK upgrades. Furthermore, Google lets you use some of these features on older Android platforms where they are not supported. You want to use Google’s solution to retrofit your apps to support fragments and/or other previously unsupported features.

Solution

How It Works

public class UseGridLayout extends Activity {
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
 
        GridLayout gl = new GridLayout(this);
        gl.setRowCount(2);
        gl.setColumnCount(2);
 
        Button btn = new Button(this);
        btn.setText("1");
        gl.addView(btn);
 
        btn = new Button(this);
        btn.setText("2");
        gl.addView(btn);
 
        btn = new Button(this);
        btn.setText("3");
        gl.addView(btn);
 
        btn = new Button(this);
        btn.setText("4");
        gl.addView(btn);
 
        setContentView(gl);
    }
}

android create project -t 2 -p <path/to/project/directory>
-a UseGridLayout -k com.androidrecipes.usegridlayout

android update project -t 2 -p <path/to/project/directory>
-l <path/to/android-sdk>/extras/android/support/v7/gridlayout

ant debug

Invalid file: <androidsdk>/extras/android/support/v7/gridlayout/build.xml

android update lib-project -t 2 -p.

adb install UseGridLayout-debug.apk