Building your first ArcGIS Runtime SDK for Windows Mobile application

This walkthrough describes how to create and deploy a simple ArcGIS Runtime SDK for Windows Mobile application for the Windows Mobile platform. It uses step-by-step instructions to demonstrate how to create an application using the Map control, the 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; however, if you have a mobile device, you can use that.

Concepts

Even though this walkthrough does not require previous experience with ArcGIS Runtime SDK for Windows Mobile, there are some important concepts you should understand before starting this project. As a prerequisite, read the conceptual documentation in this Help system to gain an understanding of the mobile framework and architecture. Using the 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 API Reference. In addition, you should have a good understanding of Visual Studio .NET 2008 and how to create a Windows Mobile application for either an emulator or a device.

Where to get the sample

The sample is available for download from the ArcGIS.com code gallery.

ArcGIS Runtime SDK for Windows Mobile components

The mobile assembly provides several Visual Studio components to help you develop mobile applications. The primary components you'll work with are MobileServiceConnection, MobileCache, SyncAgent, and the Map. The MobileServiceConnection component represents the connection to the MobileService published on an ArcGIS Server, the MobileCache represents a local compressed copy of that data, and the SyncAgents control the flow of data in this connection. 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 system and how they 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 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 MobileCache that's included in the downloaded sample. 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, see the Developer Help.

Requirements

To complete this walkthrough, you need the following installed on your machine:

See 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 cache and display the map layers in a map control. Then you'll add controls to navigate the map and identify selected features.

Steps:
  1. Creating a new project using Visual Studio .NET 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 3.5 from the drop-down list at the top of the dialog box.
    5. Type a project name.
    6. Click OK. The Add New Smart Device Project dialog box appears.
    7. For the Target Platform, select Windows Mobile 6.0 Professional SDK.
    8. For the .NET Compact Framework version, select .NET Compact Framework Version 3.5.
    9. In the Templates pane, click Device Application.
    10. Click OK. A new project is created.

      Add New Smart Device Project dialog box

    Since the application was created as a 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 Runtime SDK for Windows Mobile. They are located on the ArcGIS Mobile Controls tab within the toolbox. To use the controls within your application, drag them from the toolbox to your Windows form.

    1. Double-click or drag the Map component from the toolbox onto the form.
    2. In the Properties Window, change the Dock property to Fill so that the Map control will utilize the full display area of the device as indicated by the previous screen shot.
    3. Add a MobileCache component to your project from the toolbox.

    Your form now contains a Map, called Map1, and a MobileCache component, called mobileCache1.

    Visual Studio IDE with the Map control added to the form

  3. Configuring the components

    You configure the components through code by setting a few required properties as described in the following steps.

    Add code to specify where the mobilecache is located on disk, then open it, which also draws the map to the display. Doing this as part of the form's Load event process is a common practice.

    1. In the Properties window of the form, select the Event tab, and double-click the Load event property.
    2. Add the following using statements to the existing list of using statements to include the ArcGIS Mobile assembly:

      using ESRI.ArcGIS.Mobile;
using ESRI.ArcGIS.Mobile.FeatureCaching;
using ESRI.ArcGIS.Mobile.FeatureCaching.Synchronization;

    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 of the local cache on disk  
      mobileCache1.StoragePath = Environment.GetFolderPath(Environment.SpecialFolder.Personal) + @"\MapCache";
      if (!mobileCache1.IsValid)
      {
        MessageBox.Show("Map Cache is not valid!");
        return;
      }

      try
      {
        mobileCache1.Open();
        map1.MapLayers.Add(mobileCache1);
      }
      catch
      {
        MessageBox.Show("Cannot open map cache");
      }
    }

  4. Compile the application
    1. Click Build > Build Solution. .

      The solution is compiled. If any errors appear in the Errors List window, use the messages to correct the problems.

  5. Configuring the Windows Mobile emulator

    You'll 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 box, locate the Windows Mobile 6 Classic Emulator, right-click, and select Connect. This starts the device emulator.
    3. Right-click the Windows Mobile 6 Classic Emulator entry again, and select Cradle. This cradles 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 manually connect in ActiveSync by selecting File > Connection Settings, then click the Connect button and follow the wizard.

      Device Emulator Manager dialog box

    NoteNote:

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

    NoteNote:

    You also need to install the ArcGIS Runtime SDK for Windows 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 can now compile and run the application. Select the Windows Mobile 6 Classic emulator as the target device. When the application starts, the form displays 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, the pan mouse action listens to the MouseDown, MouseMove, and MouseUp events to begin, execute, and complete the panning action.

    A map can have multiple map actions associated with it. However, by design, only one is active or current at a time. 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 active and can be executed. In this step, you'll add MapAction components to the project, which will provide navigation and alter the mouse behavior.

    1. At the bottom of the form, put the pointer into the softkey menu area 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 following screen shot.
    2. Double-click each of the menu items to create a code block for the Click event for each item.
    3. Switch to the code view for the form, and add the following using statement:

      using ESRI.ArcGIS.Mobile.WinForms;

    4. From the code window of your form, move to the top of the code to just above the Form1_Load() code block. Within the code for the Form class just below the InitialComponent() section, insert the following code block to create the MapActions:

      PanMapAction PanMapAction1 = new PanMapAction();
    ZoomInMapAction ZoomInMapAction1 = new ZoomInMapAction();
    ZoomOutMapAction ZoomOutMapAction1 = new ZoomOutMapAction();

    5. Add the following code to the Click events:

      private void menuItem3_Click(object sender, EventArgs e)
    {
      map1.MapAction = ZoomInMapAction1;
    }
    private void menuItem4_Click(object sender, EventArgs e)
    {
      map1.MapAction = ZoomOutMapAction1;
    }
    private void menuItem5_Click(object sender, EventArgs e)
    {
      map1.MapAction = PanMapAction1;
    }

    6. Compile and run your application.

    The application displays the map data from the MapCache, and you can change the mouse action by 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 Map control by querying the location identified by the mouse. In this step, you'll add custom code to enable the identify function.

    1. Select the Menu on the sample form, and add a new item. Name it identifyToolStripMenuItem.
    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.MapAction = 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 creates a code block for the event.
    6. Add the following code to the Map1_MouseDown event:

      if (map1.MapAction != 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 (FeatureSource FSource in mobileCache1.FeatureSources)
  {
    txtResult += "\r\n Layer " + FSource.Name;
    using (FeatureDataReader featReader = FSource.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-2015 Esri. All rights reserved.
1/7/2015