Simplified API Part 2: ArcGIS Android Application Framework

In part 1 of our Simplified API programming pattern for ArcGIS Android we discussed how the MapOptions class can define a basemap, zoom level, and center of a MapView to simplify the programmatic workflow in setting up your map.  In this post we will discuss using the ArcGIS Android Application Framework to further simplify programmatic workflows related to adding geometries with callouts and reverse geocoding.

Working with the ArcGIS Android Application Framework

The application framework for ArcGIS Android provides simplification classes to assist in supporting some Mapping and Locator workflows.  The easiest way to integrate the framework is with the Eclipse plugin:

  1. Right click your ArcGIS for Android project and choose ArcGIS Tools > Add Application Framework to Project. This option is only available on ArcGIS for Android projects.

This will add the arcgis-android-app-framework.jar file to your project and you can begin taking advantage of the helper classes it provides.  If you are not using Eclipse you can get the arcgis-android-app-framework.jar file from your SDK on disk in the <arcgis-install-dir>/libs/ directory which you can add to your project.


The MapViewHelper class provided by the ArcGIS Andriod Application Framework provides a simplified pattern for adding geometries, callouts, and popups to a MapView.  We are going to focus on adding a geometry and working with the callout on the resulting graphic.  Using the MapViewHelper class allows you to add simple geometries intuitively to the MapView without dealing with GraphicsLayer, Spatial References, etc.

A simplified pattern of adding a point to a GraphicsLayer with an custom icon symbol for the graphic and a title and text for the Callout is defined below:

// Retrieve the map and map options from XML layout 
// Using MapOptions 
mMapView = (MapView) findViewById(; 
// Create a MapView Helper 
mvHelper = new MapViewHelper(mMapView); 
// Create drawable icon 
icon = getResources().getDrawable(R.drawable.route_destination);
// Make sure map has loaded before adding geometries 
mMapView.setOnStatusChangedListener(new OnStatusChangedListener() { 
  private static final long serialVersionUID = 1L; 
  public void onStatusChanged(Object source, STATUS status) { 
    // Add a graphic to represent ESRI Headquarters 
    int loaded = mvHelper.addMarkerGraphic(34.056695, -117.195693, 
                 "ESRI", "World Headquarters", null, icon, false, 0); 
    if (loaded < 0) { 
      Log.d("TAG", "Marker Graphic not added to MapView"); 

The code above will place a custom icon for the graphic at the provided latitude and longitude provided. When the graphic is tapped it will show a callout with the title and snippet provided. The returned int is a unique id representing the added Graphic. It will return -1 if the graphic failed to be added to the MapView.


The GeocodeHelper class provides static methods to generate candidates for an address or find an address for a given location. These methods simplify the workflow of setting parameters and getting result from a Locator. The operation can be cancelled through Future. When an operation is cancelled, the the callback won’t be invoked. However, the request to the operation may be sent before the operation is cancelled.

// initialize online locator
locator = Locator.createOnlineLocator();
// array of fields to be shown in the callout
final String[] fields = { "Address", "City", "Region", "Postal" };

// single tap on map to get the address of the location tapped
mMapView.setOnSingleTapListener(new OnSingleTapListener() {
  private static final long serialVersionUID = 1L;

  public void onSingleTap(float x, float y) {
    // remove all previous graphics
    // show address using screen coords
    Future result = GeocodeHelper.showAddress(x, y, locator, mvHelper, null, fields,
			new CallbackListener() {
                          // handle any errors returned
                          public void onError(Throwable e) {
                            Toast.makeText(SimpleMapActivity.this, "Error",
                           // handle successful results
                          public void onCallback(LocatorReverseGeocodeResult objs) {
                            Log.d("TAG", "Reverse Geocode success!");

In the code above we are able to single tap on the map and get returned an icon representing the location where we tapped.  When you tap on the icon you get a CallOut with the address fields we sent in as a parameter.

Please refer to the SimpleMap sample to see the full programmatic pattern in use by an app.  You can use the New Sample Wizard in your Android SDK 10.2 Eclipse plugin to import the project.

This entry was posted in App Developers, Developer, Mobile and tagged , , , , , . Bookmark the permalink.

Leave a Reply

One Comment

  1. Eric Bader says:

    Great post.