Previous  | Next  | Home

Installing Sample Packages

 

We want to get started writing our own programs as soon as possible, but let's begin by installing a sample Android application in the Eclipse IDE, compiling it, and running it. Installing and running a sample package will serve several useful purposes:

In addition, running a sample package will test the correctness of our Eclipse and Android plugin installation.

 

Getting Access to Sample Packages

There are two ways to get access to sample code in Android: downloads with the SDK and online browsing.

  1. Downloads with the SDK: In the downloads for various components of the Android SDK you may choose to include sample code. Then a whole set of sample applications can be found in the "samples" subdirectory of your SDK installation (in that subdirectory the samples will be divided further into subdirectories corresponding to different versions of the Android platform).

  2. Online Browsing: Go to the List of Sample Apps for a list of sample apps that can be browsed online. Additional open-source demo apps may be found at apps-for-android.

All of these sources provide working examples of how to do many things with Android.

 

Snake on a Phone

As noted above, a whole set of sample applications can be found in the "samples" subdirectory of your SDK installation (provided that you selected the samples when you installed SDK components). To illustrate we will install a simple game, Snake, from the samples. The other examples can be installed and explored in an similar way.


NOTE: For API level 7 and API level 8 the samples are under <sdk>/samples. For earlier versions of the API the samples may be found under <sdk>/platforms/<platform-name>/samples.

  1. Open Eclipse and select File > New > Project

  2. Select the Android wizard by choosing Android > Android Project (Note: after you do this once, you will have the shortcut option File > New > Android Project).

  3. This should give a window as in the following figure.


    Select Create project from existing source.

  4. Use the Browse button to navigate to the samples subdirectory of the Android SDK and choose the android-8/Snake subdirectory. Click OK.

  5. Select Android 2.2 for the Build Target. Your window should now be filled in like in the preceding figure.

  6. Click Finish.

This should add a project Snake to the left panel of Eclipse (see the following figure).



For the first few seconds after it is added there may be a red x on the Snake entry. This is because by default Eclipse is set to build on the fly as changes are made (if Project > Build Automatically is checked). The red x is an indication of an error in the project that results because as the various pieces are built from scratch for the first time resources needed by one part of the project may be detected as missing if they are not yet built. If all is well the red x should disappear after several seconds, indicating that the Snake project has built successfully.


Normally you will want to leave Eclipse in this build-on-the-fly mode, since this accelerates development time. Sometimes for debugging purposes you may want to turn off the automatic build by unchecking Project > Build Automatically. Whether Eclipse is in the build automatically mode or not, you can always force a manual build at any time by selected Project > Clean and then selecting either all projects or a single one. Whenever Eclipse is building, progress will be displayed in the lower bar.

To execute this project we need to configure an emulator. Follow these instructions to configure a basic Android 2.2 virtual device.

Once an emulator is configured, right-click on Snake in the left Eclipse pane and select Run As > Android Application. If the Simple2.2 emulator is in the list of running android devices select it. If not, select Launch a new Android Virtual Device, select Simple2.2 from the list (see the following figure),



and click OK. This should launch the Snake game on the Simple 2.2 emulator (it will take a while before the emulator displays the program; be patient), with instructions on the screen to start the game; see the following figure.



(The object of the game is to use the up-down and left-right arrows to guide the snake to eat one of the two yellow objects always on the screen. When an object is eaten the snake grows longer and it moves faster. The game is over if the snake touches the walls of the container or crosses its own body.)

Notes: (1) Because emulators are rather slow to launch, you will often want to leave them open once they are launched. (2) The Snake game requires access to the keyboard and full visibility of the display at the same time. Thus, if you install Snake on an actual phone rather than an emulator (see Installing on a Device), it will likely work as intended only if the phone has a physical keyboard since a soft (virtual) keyboard will typically obscure much of the screen.

 

Exploring other API Examples Using the Emulators

If the emulator is for Version 2.1 or later of Android, the Applications Menu (usually opened by a button with multiple squares on it) will likely contain a folder called API Demos that will allow you to explore examples of API applications without having to install them yourself as in the above Snake example. On the 2.2 emulator configured above, clicking the Home button should give a display as in the left figure below, and then clicking the central bottom button on the display with the multiple squares in it should give the applications folder illustrated in the right figure below.



If you click on the API Demos folder you should get a scrollable menu (drag it vertically with the mouse) as in the left figure below. Try selecting Graphics > Open GL ES > Kube, which should give you the example of Open GL 3D animated graphics illustrated in the right figure below.



You may explore other examples from the API by selecting other options from this menu.

Previous  | Next  | Home