Building your first ArcGIS Mobile application for Windows Mobile

This walkthrough is for developers who wish to learn about creating and deploying a simple ArcGIS Mobile application for the Windows Mobile platform. It uses step-by-step instructions to demonstrate how to create an application using the ArcGIS Mobile Map Control, the ArcGIS Mobile assembly and parts of ADO.NET.

Project description

This application will display map data using a Map Control, provide basic navigation tools such as zoom and pan, and include an identify function to show feature attributes. Once you complete this walkthrough, you can extend the application with additional functionality, or use what you learned to build your own application. This walkthrough is written in C# and will be deployed to the Windows Mobile 6 Classic emulator installed with Windows Mobile 6 SDK or if you have a mobile device, you can use that.

Concepts

Even though this walkthrough does not require previous experience with ArcGIS Mobile, there are some important concepts you should understand before starting. As a prerequisite, please read the Mobile SDK conceptual documentation, found in this help, to gain an understanding of the mobile framework and architecture. Using the ArcGIS Mobile class diagrams while proceeding through this walkthrough will help you learn about the classes and their relationships. You can find the class diagrams in the Mobile Assembly book of the ArcGIS Mobile Developer Help. In addition, you should have a good understanding of Visual Studio .NET 2008 and how to create a Windows Mobile application.

Where to get the sample

The sample is available for download from here.

ArcGIS Mobile SDK components

The ArcGIS Mobile SDK provides several Visual Studio components to help you develop mobile applications. The primary components that you will work with are the MobileServiceConnection, MobileCache, SyncAgent and the Map. The MobileServiceConnection component represents the MobileService published on an ArcGIS Server, the MobileCache represents a local copy of that data compressed and stored in a folder set with the StoragePath property, and the SyncAgents represents the flow of data between them. While this sample can run without a connection to a server, it is important to understand the role each of these components play in the ArcGIS Mobile system. Notice how the components are linked together and operate as a group to reflect the unique tasks each of them perform. The local data used in this walkthrough was previously extracted from a web service that was published with mobile capabilities. You do not need to create a mobile web service to complete this walkthrough or have a mobile device. The Map component will display the contents of the included MobileCache without connecting to a server. Additional components are used to navigate the map and identify attribute information for given features. For more information on the components used in this walkthrough, please refer to the ArcGIS Mobile Developer Help.

Requirements

In order to complete this walkthrough you will need the following installed on your machine:

Go to the Developer Requirements topic for more details and links to downloads and instructions.

Implementation

In this walkthrough, you will create a simple application for the Windows Mobile platform that allows you to open a mobile map cache and display the map layers in a map control. Then you will add additional controls that will let you navigate the map and identify features within the layers.

Steps:
  1. Creating a new project using Visual Studio 2008
    1. Start Visual Studio .NET 2008.
    2. On the main menu, go to File > New > Project.
    3. In the New Project dialog box, under Project Types, expand Visual C#, click Smart Device and select Smart Device Project from the Templates pane.
    4. Select .NET Framework 2.0, from the dropdown list at the top of the dialog.
    5. Enter a project name.
    6. Click OK. This will bring up the Add New Smart Device Project dialog.
    7. For the Target Platform select Windows Mobile 6.0 Professional SDK.
    8. For the .NET Compact Framework version select .NET Compact Framework Version 2.0.
    9. In the Templates pane click Device Application.
    10. Click OK. This will create a new project for you.

      Add New Smart Device Project Dialog

    Since the application was created as Windows Mobile 6.0 Application, Visual Studio will create the proper solution files and structure, and display a form for a Windows Mobile device.

  2. Adding a Map Control

    The ArcGIS Mobile controls are added to the Visual studio toolbox when you install the ArcGIS Mobile SDK. They are located within the ArcGIS Mobile Controls tab within the toolbox. To use the controls within your application you simply drag and drop them from the Toolbox to your windows form.

    1. Double-Click, or Drag-and-Drop the Map component from the toolbox onto the form.
    2. In the Properties Window change the Dock property to Fill so that the mapcontrol will utilize the full display area of the device as indicated by the screen shot above.

    When the Map component is added to the form, a MobileCache component will be added to your project automatically. Your form should now contain a Map, called Map1, and a MobileCache component called mobileCache1.

    Visual Studio IDE with the Map control added to the form

  3. Configure the components

    You can configure the components via their properties in the IDE or though code. The steps below can be used to set the properties, or you can use the code listed in the next section.

    1. Right click the Map Control and choose DataSources... on the context menu to display the DataSources Collection Editor dialog.
    2. Within the DataSources Collection Editor dialog, ensure that the mobileCache1 is in the members list and is selected. If it is not there, use the Add button to add it.
    3. Select the StoragePath property and set the the location of the MobileCache.

    Add code to specify where the mobilecache is located on disk, and then open it, which also draws the map to the display.

    1. Doing this as part of the Form's Load event process is a common practice, in the Properties window of the Form select the Event tab and Double-Click on the Load event property.
    2. Add the using statements below to the existing list of using statements to include the ArcGIS Mobile assembly.

      using ESRI.ArcGIS.Mobile;
using ESRI.ArcGIS.Mobile.MobileServices;

    3. Add the following code to the class for the Form1_Load() method.

      private void Form1_Load(object sender, EventArgs e)
{ 
  // Specify the storage location on disk  
  mobileCache1.StoragePath = Environment.GetFolderPath(Environment.SpecialFolder.Personal) + @"\MapCache";
  if (!mobileCache1.IsValid) 
  {
    MessageBox.Show("Map Cache is not valid!"); 
    return;
  }
  if (mobileCache1.IsEmpty) 
  {
    try
    {
    // Uncomment the following line and replace URL with your own mobile service if you 
    // decide to use your own Mobile service map data 
    //mobileServiceConnection1.Url = @"http://YourServer/YourArcGISServerInstance/services/YourMobileServiceName/MapServer/MobileServer";
    mobileCache1.DeleteCache();
    MobileCacheSyncAgent mobilesync = new MobileCacheSyncAgent(mobileCache1,mobileServiceConnection1);
    mobileServiceConnection1.CreateCache(mobileCache1);
    mobilesync.Synchronize();
    }
    catch 
    {
      MessageBox.Show("Cannot synchronize with this service"); 
    }
  }
  try 
  {
    mobileCache1.Open(); 
  }
  catch
  { 
    MessageBox.Show("Cannot open map cache");
  }
}

  4. Compile the application. Go to Build > Build Solution. The solution should compile fine but if any errors appear in the Errors List window, use the messages to correct the problems.
  5. Configuring the Windows Mobile emulator

    You will use the Windows Mobile 6 Classic Emulator to test the application, but before you can deploy your application, you must start the emulator and virtually cradle it.

    1. From the Visual Studio menu, choose Tools > Device Emulator Manager.
    2. In the Device Emulator Manager dialog, locate the Windows Mobile 6 Classic Emulator, right click and select Connect. This will start the device emulator.
    3. Right click again on the Windows Mobile 6 Classic Emulator entry and select Cradle.This will cradle the emulator via ActiveSync or Windows Mobile Device Center. Select a Guest partnership if asked for the type of ActiveSync relationship.
      TipTip:

      If ActiveSync does not automatically connect to the device, you can try to manually connect in ActiveSync by selecting File > Connection Settings, then click the Connect button and follow the wizard.

      Device Emulator Manager Dialog

    NoteNote:

    Before running the application, you will need to copy the supplied map cache from the sample directory to the emulators' \My Documents folder. From the Tools menu in ActiveSync, click Explore Device and navigate to \My Documents and paste the MapCache folder from the sample directory.

    NoteNote:

    You will need to install the ArcGIS Mobile runtime onto the emulator or device. The easiest way to do this is to copy the Runtime.cab file onto the device or emulator and execute it to unpack.

    You may now compile and run the application. Select the Windows Mobile 6 Classic emulator as the target device. When the application starts, the form should display layers from the map service in the map control.

  6. Changing the mouse behavior

    Map actions are components designed to listen and react to events raised by the mouse, keyboard, and other input devices against the map surface. For instance pan mouse action listens to the MouseDown, MouseMove, and MouseUp events to begin, execute, and complete panning action.

    A map can have multiple map actions associated with it. However, by design only one is active or current. For instance a map can have zoom in, zoom out, pan, identify, and polygon sketch actions available, but at any given time only one action is executed. In this section, you will add mapaction components to the project, which will provide navigation and alter the mouse behavior.

    MapAction Collection Editor Dialog

    1. From the Properties window of the Map control, find the MapActions item and click the button appearing in the cell next to (Collection), or use the context menu on the Map control. In the MapAction Collection Editor window, use the Add button to add PanMapAction, ZoomInMapAction and ZoomOutMapAction to the collection as shown in the graphic above. The Add button becomes a dropdown list when a right mouse click is used to expand the button, or the dropdown arrow is selected.
    2. Each of the components default their Map property to Map1, ensure they are set correctly and press OK to dismiss the window.
    3. At the bottom of the form put the cursor into the softkey menuarea and click to begin adding menu items, which will be linked to the MapActions. The text for the menu items should be ZoomIn, ZoomOut and Pan to standardize their appearance and look similar to the screenshot below.
    4. Double click on each of the menu items to create a code block for the Click Event for each item.
    5. Switch to the code view for the form and add the following using statement.

      using
ESRI.ArcGIS.Mobile.MapActions;

    6. Add the following code to the Click Events.

      private void menuItem2_Click(object sender, EventArgs e)
{
  map1.CurrentMapAction = zoomInMapAction1;
} 
private void menuItem3_Click(object sender, EventArgs e)
{ 
  map1.CurrentMapAction = zoomOutMapAction1;
}
private void menuItem4_Click(object sender,EventArgs e)
{ 
  map1.CurrentMapAction = panMapAction1;
}

    7. Compile and run your application.

    The application should display the map data from the MapCache and you should be able to change the mouse action by simply selecting the menu items. Zoom in on the map and notice how the data being displayed changes automatically using scale-dependent drawing properties embedded in the map document.

  7. Adding identify capability

    Similar to the functionality within other ArcGIS applications, you can identify features inside the MapControl by querying the location identified by the mouse. In this section, we will add some custom code to enable identify.

    1. Select the Menu on the sample form, and add a new item.
    2. Set the text to Identify.
    3. Add the using statement to the code.

      using ESRI.ArcGIS.Mobile.Geometries;

    4. Add the following code to the Click event.

      private void identifyToolStripMenuItem_Click(object sender,EventArgs e)
{
  map1.CurrentMapAction = null; 
}

    5. Add a MouseDown event to the Map Control. With the Map Control active in the form, click Events in the Properties window. Find the MouseDown event in the list of events and double click it. This will create a code block for the event.
    6. Add the following code to the Map1_MouseDown event.

      if (map1.CurrentMapAction != null)
  return; 
Cursor.Current = Cursors.WaitCursor;
MapMouseEventArgs me = e as MapMouseEventArgs;
Envelope qEnv = new Envelope(me.MapCoordinate, me.MapCoordinate);

double mapTolerance = map1.ToMap(3); 
qEnv.Resize(mapTolerance,mapTolerance); 
QueryFilter qFilter = new QueryFilter(qEnv,GeometricRelationshipType.Intersect); 
string txtResult = "IdentifyResults: ";
int intFields; 
{ 
foreach (MobileCacheLayer MCLayer in mobileCache1.Layers) 
{ 
  //Only Feature layers are used in identify
  if (MCLayer is FeatureLayer) 
  {
    txtResult += "\r\n Layer " + MCLayer.Name; 
    FeatureLayer FLayer; 
    //cast the MobileServiceLayer to a featureLayer 
    FLayer = (FeatureLayer)MCLayer; 
    using (FeatureDataReader featReader = FLayer.GetDataReader(qFilter)) 
    {
      intFields = featReader.FieldCount; 
      while (featReader.Read()) 
      {  
      for (int i = 0; i < intFields; i++)
        txtResult += "\r\n" + featReader.GetName(i) + ": " + featReader.GetValue(i).ToString(); }
      } 
    }
  }
}
Cursor.Current = Cursors.Default;
MessageBox.Show(txtResult.ToString());
}

    7. Compile and run the application.

    The new application running on a Windows Mobile device


Copyright © 1995-2011 Esri. All rights reserved.
9/20/2011