Customizing MapPage

MapPage is widely used throughout the application. It's essentially a form that contains a map component for visualizing geospatial information and allowing 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 screen capture shown below is the default map page within the View Map task.

Need alt text

How to create a map page

Technically you can create your own form with a map component, but this would be expensive because of limited resources on a mobile device. Instead, you should use the built-in MapPage when a map is needed in your application. The built-in map has been designed so that any instances created will share the same map component and thus save resources on the device.

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

MapPage myMapPage = new MapPage();

How to customize MapPage

MapPage comes with UI elements, such as Title, SmallIcon, LeftSoftKey, RightMenuItems, and SharedMap. 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 the map page in the View Map task

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 the title text of the map page and inserts 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;
mapPage.Title = "Building Inspection";
System.Windows.Forms.MenuItem mi = new System.Windows.Forms.MenuItem();
mi.Text = "Added Menu Item";
mapPage.RightMenuItems.Insert(0, mi);

Need alt text

Option 2: Customizing MapPage for every instance created (limited to menu items)

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

Need alt text

Notice that the menu items in RightMenuItems are broken into two sections: the default upper items and the default lower items. The default upper items are the navigation items plus the GPS menu item, and the lower menu items contain the layer visibility and help items. You can see these items separated by a single separator on many variations of MapPage within the application.

Keep in mind that 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.

need alt text

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

Need alt text

Option 3: Customizing a specific instance of MapPage you created

Very often you might want to have a map page with customization and not affect any other MapPage instances. To achieve this, you can simply 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/DefaultLowerItems and your own menu items. Esri recommends that you add your own menu items between DefaultUpperItems and DefaultLowerItems if they exist. The mobile application follows this guideline on various map pages.

To take it one step farther, you can also create your own 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.


9/20/2011