ArcGIS Runtime SDK for Windows Mobile

MapPage displays geographic data and is widely used throughout the application. It is used by View Map Task for viewing and navigating the map, it is used in data collection or geometry editing where geometry is collected or edited with various collecting/editing methods, and it is used by search/identify result or worklist task for viewing the location of the selected feature. It's essentially a form that contains a map component for visualizing geospatial information and allows you to interact with it. It also provides a set of menu items with built-in functions for map navigation, layer visibility, help tips, and so on.

The following screen capture is the default map page within the View Map task:

How to create a map page

While you can create your own form with a map component, you should use the built-in MapPage when a map display is needed in your application. The built-in MapPage has been designed so that any instances created will share the same map component and thus save resources on the device.

To use it, create a new instance of MapPage and customize it to your requirements.

MapPage myMapPage = new MapPage();

How to customize MapPage

MapPage comes with user interface (UI) elements, such as Title, SmallIcon, LeftSoftKey, RightMenuItems, SharedMap, ToolWidgets, InfoText, and so on. You can customize these UI elements to fit your needs. There are three levels of customization that you can have with the application framework:

Option 1: Customizing a specific MapPage in the application
Option 2: Customizing MapPage for every instance created
Option 3: Customizing your own MapPage

Option 1: Customizing a specific MapPage in the application

The mobile application has a View Map task that has a map page associated with it. You can customize this map page so that your customizations can be seen only in this task.

To accomplish this level of customization, get MapPage through MobileApplication.Current.Project.ViewMapTask.MapPage. You can customize the title of the page, change its icon, change the right menu items, and so on. Again, this customization will be applied to the map page that's associated with the View Map task only.

The following code will change insert a new menu item at the top of the default right menu items:

// Customize the MapPage in ViewMapTask
MapPage mapPage = MobileApplication.Current.Project.ViewMapTask.MapPage;
System.Windows.Forms.MenuItem mi = new System.Windows.Forms.MenuItem();
mi.Text = "Added Menu Item";
mapPage.RightMenuItems.Insert(0, mi);

Map page with modified menu

For customizing map pages in other tasks, you can add an event handler for the MapPage.OnShowing event. The OnShowing event is raised before a map page is shown. Here, you can first check if the map page instance is the one you want to modify, then you can modify its UI controls for this specific map page instance. See the geometry samples for more details.

Option 2: Customizing MapPage for every instance created

As a second option, you can customize MapPage so that the changes will be effective for each instance created from it (before or after).

The menu items in RightMenuItems are broken into two sections: the default upper items and the default lower items. The default upper items include the Global Positioning System(GPS) menu item and the layer visibility, and the lower menu items contain the Identify, Measure, Navigate and help items. You can see these items divided by a single separator on many variations of MapPage within the application.

If you change the menu items from MapPage.DefaultUpperMenuItems or MapPage.DefaultLowerMenuItems, the changes will be effective for all map pages that have been instantiated or will be instantiated. Since these collections are binding lists, any previously instantiated items can listen to the change events off this collection and decide how to deal with them accordingly.

The following code removes the Zoom To Entire Map menu item from DefaultUpperItems and adds an About menu item to the end of DefaultLowerItems. The screen capture shows the change on the map page within the View Map task.

// page menuitem
      MenuItem mycustomizedMenuItem;
      RightMenuItems.Remove(ZoomFullExtentMenuItem);

      mycustomizedMenuItem = new MenuItem();
      mycustomizedMenuItem.Text = "About...";
      RightMenuItems.Add(mycustomizedMenuItem);

Option 3: Customizing your own MapPage

To customize a specific map page and not affect any other MapPage instances, you can create an instance of MapPage and customize it to your needs. You can change Title or SmallIcon or customize the RightMenuItems collection with a mixture of DefaultUpperItems and DefaultLowerItems as well as your own menu items. Add your own menu items between DefaultUpperItems and DefaultLowerItems, if they exist, to follow the pattern used by the mobile application on its various map pages.

Optionally, you can create your own custom MapPage class by subclassing MapPage. BrowseMapPage is such an example as it needs to add layers to the map when the page is shown and remove layers when the page is hidden. You can also do this if you are constantly setting the same properties on a map page and you want to encapsulate all that logic in a class that can easily be reused. See the Geometry samples for more details on customizing tool widgets, rocker menus, and graphic layers, within your own map page class, and to see the code in action.

1/7/2015