Displaying A Map
The primary way that you can display geographic information in your applications is by using a map view. A map view lets you mash up layers from different sources such as ArcGIS Server services, Bing Maps, Open Street Map, etc. or open preconfigured web maps from www.ArcGIS.com and your custom ArcGIS portal.
The steps below will guide you through displaying a map in your application. If you haven't already done so, configure your project to begin development with ArcGIS Runtime SDK for iOS. The steps below assume you have created a project named "MyFirstMapApp" using the Single View Application Xcode project template.
1. Add a map view to the user interface
The first step in displaying a map in your application is to add a map view to your application's user interface. The user interface of iOS applications is typically contained in a nib file (.xib extension). The nib file contains all the UI components that need to be displayed and information about their styling, positioning, layout, etc. Each nib file typically has an associated view controller which contains code to respond to user interaction with the UI components and optionally perform some setup and tear down tasks. This separation of view and controller objects is based upon the Model-View-Controller design pattern.
Note:If you are using Storyboard in your project, you won't have any nib files but you will have a storyboard file instead. Conceptually, both these files are similar because they both contain UI, however, a storyboard file contains many UI scenes and defines transitions or "segues" between them whereas a nib file contains only a single UI scene. Although the steps below describe how to add a map view to the UI in a nib file, you can follow the same steps to add it to a storyboard file.
Lets assume we will be adding a map view to the UI contained in the ViewController_iPhone.xib nib file. When you select this file in the Project Navigator pane on the left, its contents will be displayed in the Canvas section on the right where you can compose the UI visually. Between the Project Navigator and the Canvas lies the Dock which provides a convenient list of all the UI components currently in the nib file. The right most section in XCode is the Utility area which contains the Inspector pane (top) and Library pane (bottom). The Inspector allows you to inspect and change properties of UI components in the nib file, and the Library allows you to pick UI Components, media, code snippets, etc to add to your project.
To add a map view, select a generic UIView object from the Library pane and drag & drop it on to the view shown in the Canvas.
 |
Before this UIView can display our map, we need to change it to a map view. We do this by specifying AGSMapView as the class for this object in the Inspector.
 |
2. Connect the map view to the view controller
Now that we've added a map view to the UI, we need to connect is to the view controller such that we can programmatically add content to it and respond to user interaction. To do this, first we need to enable the Assistant Editor so that the view controller's header file (ViewController.h) is displayed along side the Canvas. We can then simply right click on the map view in the Dock and drag & drop it in the header file shown in the Assistant Editor.
 |
Upon doing so, Xcode will automatically prompt us for a name so that it can create a "outlet" connection from the view controller to the map view in the UI. Let's call this outlet "mapView".
 |
If we try to build our application at this stage, we will get compile errors because our view controller contains reference to the AGSMapView class but this class hasn't been defined yet. To fix these errors, we need to import the ArcGIS.h header file in our view controller's header file.
#import <UIKit/UIKit.h>
//Import the header file for ArcGIS API
#import "ArcGIS.h"
@interface ViewController: UIViewController
...
@end
3. Add content to the map view
Now that we have added a map view to the UI and connected it to the view controller, we can add content to be displayed in the map. Select the ViewController.m implementation file in the Navigator to open it in the source editor. Locate the viewDidLoad method. This method is executed when the user interface is displayed giving the view controller a chance to add some behavior or tweek the display. We will create a Tiled layer that uses an ArcGIS Online map service, and add it to the map:
- (void)viewDidLoad {
[super viewDidLoad];
AGSTiledMapServiceLayer *tiledLayer =
[AGSTiledMapServiceLayer
tiledMapServiceLayerWithURL:[NSURL URLWithString:@"http://server.arcgisonline.com/ArcGIS/rest/services/ESRI_StreetMap_World_2D/MapServer"]];
[self.mapView addMapLayer:tiledLayer withName:@"Tiled Layer"];
}
If we run the application now, the map should display contents from the ArcGIS Online map service.
4. Respond to map actions
A map view informs its delegates when certain actions take place on the map, for instance, when a layer loads, or a user touches the map. The delegate is responsible for responding to these actions. A map view also consults its delegate before performing certain actions, such as, displaying a callout. The delegate is responsible for instructing the map on what to do. This separation of responsibility between the map and its delegates is based upon the Delegation design pattern.
Depending upon the actions you're interested in handling, you can set one of your classes as the map view's delegate. A map view has three types of delegates .
Layer Delegate
The layer delegate is informed about layer related actions, such as when the map loads a layer successfully or fails to load a layer. Refer to the API reference documentation for the AGSMapViewLayerDelegate protocol to learn about the different actions conveyed to the layer delegate.
Any class wishing to serve as the layer delegate must adopt the AGSMapViewLayerDelegate protocol and implement the methods related to the actions it is interested in. For example, the following code snippet shows how the ViewController 1) adopts the delegate protocol 2) implements the method to be informed when a layer fails to load and 3) sets itself as the map view's layerDelegate
//1. Adopt the delegate protocol
@interface ViewController: UIViewController <AGSMapViewLayerDelegate>
...
@end
@implementation ViewController
//2. Implement the delegate method(s)
- (void)mapView:(AGSMapView *) mapView failedLoadingLayerForLayerView:(UIView *) layerView baseLayer:(BOOL) baseLayer withError:(NSError *) error {
//Inspect the error and then either ...
//A. Remove the layer if it's not essential
if(!baseLayer)
[self.mapView removeMapLayerWithName:layerView.name];
//B. Or, try resubmitting the layer, with different URL or credentials perhaps
AGSTiledMapServiceLayer* tiledLyr = (AGSTiledMapServiceLayer*)laverView.agsLayer;
[tiledLyr resubmitWithURL:url credential:cred];
}
//3. Set the map view's layerDelegate
- (void)viewDidLoad {
...
self.mapView.layerDelegate = self;
}
@end
Touch Delegate
The touch delegate is informed about user interaction with the map, such as when a user taps, or taps and holds on the map. Refer to the API reference documentation for the AGSMapViewTouchDelegate protocol to learn about the different actions conveyed to the touch delegate.
The procedure for assigning a touch delegate is similar to the procedure described above for layer delegate.
Callout Delegate
The callout delegate is informed when the map performs or is about to perform callout related actions, such as when it is about to display or dismiss a callout, or when a user interacts with the callout, for example, by tapping the callout's accessory button. Refer to the API reference documentation for the AGSMapViewCalloutDelegate protocol to lean about the different actions conveyed to the callout delegate.
The procedure for assigning a callout delegate is similar to the procedure described above for layer delegate