Hello World Map

Complexity: Beginner Data Requirement: ArcGIS.com Goal: Build a mapping application that has an initial extent and properly handles orientation changes.

The following will guide you through the process of creating a Hello Map app using the SDK Eclipse plugin. The instructions and discussion below ultimately culminate in an application that is available as a sample (see Hello World). This topic's purpose is to help developers understand the basics of working with the ArcGIS for Android plug-ins in the Eclipse integrated development environment (IDE) to build a basic map application as well as fundamental principles to guide future application building. The discussion will concern how to add a map to your application with an initial extent and how to best address orientation changes.

Prerequisites

The workflows presented here assume that you have a development environment set up based on the system requirements, have the ArcGIS for Android SDK plug-in installed, and have Eclipse open with your workspace set. This topic also assumes a basic understanding of the Android platform. Throughout this topic, Android-specific terms are used with the understanding that you are familiar with the terminology of the Android platform. When possible, references are provided to Google's documentation for further reading for those who are less familiar with Android development. If some terminology is unfamiliar to you, it is strongly encouraged that you follow the supplied links and familiarize yourself with the language used in mobile development.

Create new ArcGIS Project for Android

Once you have your developer environment set you can start a new ArcGIS Project for Android in Eclipse.

Steps:
  1. In Eclipse, select File > New > Project
  2. Select "ArcGIS Project for Android" and click Next.
    New Project dialog box
  3. Fill the New Project form with the Project Name and click Next.
    New Android Project dialog
  4. In the Application info window enter a valid Package Name and click Finish.
    New Android Project dialog

You have now successfully created a new ArcGIS project for Android. Next, you will add a map service to the application and set up an initial extent for that map.

Adding a map and setting an initial extent

Now that you have created a new ArcGIS project for Android, the next step is to add a map to the application. The map you will add to this particular application is the worldwide street map available from ArcGIS.com. However, you will not display the street map for the entire world when the map is initialized. It is often more desirable for the application to initially display a map for a specific region instead of its entire extent—in this instance, a specific region of Southern California as opposed to the entire world. The following discussion will guide you through the process of adding a map and specifying an initial extent for the application:

Steps:
  1. In your new project, expand the newly created HelloWorld project in the Eclipse package explorer. We will edit 2 source files for the HelloWorld project.
    1. HelloWorld/src/com.esri.android.samples/HelloWorldActivity.java:
    2. HelloWorld/res/layout/main.xml
  2. Open up the HelloWorld/res/layout/main.xml file by double clicking on the file name. This will open the layout xml file in graphical laytout by default. Select the main.xml tab, lower left hand corner of file view. This will open up the raw xml contents..

    By default, there are two tags in main.xml. The first is Android's linear layout, which arranges its children views in a single column or a single row. To understand this layout template further, see the LinearLayout documentation provided by Google. Linear layout is just another Android view, but since its purpose is to organize children views that are added to it, it can be referred to as a parent view. For a detailed explanation of the Android view hierarchy, see the User Interface documentation. The second tag is the TextView tag, considered the child view in this example. This tag is used to add text to the application, in this case "Hello World, HelloWorld!". If you follow Android's Hello, World tutorial, this project in its current form represents Android's first basic application.

  3. Remove the <TextView> element and all it's attributes from the file. 
    /* Remove this section */
<TextView
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:text="@string/hello"
/>
  4. Add a MapView XML Layout and it's initial extent. Add the following code snippet where you removed the <TextView> element in main.xml.
    <!-- MapView layout and initial extent -->
<com.esri.android.map.MapView
android:id="@+id/map"
android:layout_width="fill_parent"
android:layout_height="fill_parent"
initExtent = "-1.3296373526814876E7 3930962.41823043 -1.2807176545789773E7 4201243.7502468005">
</com.esri.android.map.MapView>
  5. Save main.xml.
  6. Open HelloWorld/src/com.esri.android.samples/HelloWorldActivity.java file by double clicking on the file name. This will open the Java source file in the Java Editor. Add the code in Bold to your HelloWorldActivity class:
    public class HelloWorldActivity extends Activity {
	MapView map = null;

	/** Called when the activity is first created. */
	public void onCreate(Bundle savedInstanceState) {
		super.onCreate(savedInstanceState);
		setContentView(R.layout.main);

		// Retrieve the map and initial extent from XML layout
		map = (MapView)findViewById(R.id.map);
		// Add dynamic layer to MapView
		map.addLayer(new ArcGISTiledMapServiceLayer("" +
		"http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"));

	}

	protected void onPause() {
		super.onPause();
		map.pause();
	}

	protected void onResume() {
		super.onResume();
		map.unpause();
	}
}
  7. Save HelloWorldActivity.java source file.

Your application is now ready for deployment. Before we go through the deployment steps let's take a look at some of the features the New Project wizard automated for our project:

Every Android application must have an AndroidManifest.xml (located at the root folder of every Android project in Eclipse) file as part of the Android package (APK) file, which is used to distribute and install applications onto an Android device. One important aspect of this file is the declaration of permissions that your application must have to execute on a device. The New Project wizard feature included the addition of three specific permissions to the Android manifest file. The following are descriptions of each of these permissions that are added to the manifest file:

The ArcGIS for Android API uses the OpenGL ES subset specification for high performance graphics designed for embedded systems. We declare this hardware feature in the <uses-feature> declaration.

The ArcGIS for Android API supports Android 2.2 Platform and above. To distinguish this in your app we include <uses-sdk> declartion in the manifest.

You have now completed the steps necessary to add a map to and set an initial extent for a new ArcGIS project for Android. For a deeper understanding of the declarative approach to user interface (UI) design, see Declaring Layout. Next, you will learn how to take this basic application and deploy to a device.

Executing the application

It is easy to run your application from within Eclipse

Steps:
  1. Right click on the HelloWorld project in Project Explorer panel and select 'Run As > Android Application'. Be sure to have an Android device connected to the machine. We do not support running in an Emulator.
  2. When the app opens on your device, double click on the map to zoom in.

The Eclipse plugin automatically creates a new run configuration and launches the ArcGIS for Android application on your device. You should now see something like this:

This concludes the development of your first ArcGIS for Android API application. As stated at the beginning of this topic, this project is available to you as a sample. Learn about how to work with samples, and read more in-depth sample documentation.

Copyright © 1995-2012 Esri. All rights reserved.
5/31/2012