Add a map to your app

The primary way to display geographic information in your applications is through a map. This SDK contains a map view component that lets you view map layers from different map sources such as ArcGIS Server services, Bing Maps, Open Street Map, and so on, or open preconfigured web maps from ArcGIS Online or your Portal for ArcGIS.

The steps below guide you through displaying a map in your application. If you haven't already done so, configure your Xcode project then follow the steps below. In this tutorial a project named MyFirstMapApp has been created using Apple's Cocoa Application Xcode project template.

1. Add a map view to the user interface

The first step to display a map in your application is to add a map view to your application's user interface. This map view acts as an empty placeholder to which you will later add map content.

The user interface of a Mac application is typically contained in nib files (.xib extension). The nib file contains all the UI components that need to display, and information about their styling, positioning, layout, and so on. Each Mac xib file typically has an associated Window contains code to respond to user interaction with the UI components, and optionally perform some setup and tear down tasks.

When you select this file in the MainMenu.xib file the Project Navigator pane on the left and the xib's UI contents are displayed in the Canvas section on the right. Between the Project Navigator and the Canvas lies the Dock, which provides a convenient list of all the UI components currently in the xib file. The rightmost 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 the UI components in the xib file, and the Library allows you to pick UI components to add to your project.

To add a map view, select a Custom View object from the Object Library in the Library pane, then drag and drop it on to the view shown in the Canvas.

Note:

The Library pane is located at the bottom right of the Xcode window. The screenshot below is for Xcode 6.1 but note that it is displayed in different ways depending on the version of Xcode. Make sure you have selected the Object Library that contains the Custom View.

Adding a custom view

This NSView object acts as a placeholder for the map that needs to display in the application. Resize the NSView, if necessary, for your application.

Before this NSView can display your map, change it to a map view. Do this by specifying AGSMapView as the class for this object in the Inspector.

Setting the AGSMapView class

2. Connect the map view to the view controller

You have added a map view to the UI. Now connect it to the swift file so it can be programmatically accessed.

To do this, enable the Assistant Editor so that the the swift file displays alongside the Canvas. Locate the map view in the Canvas, then drag and drop it in the swift file as shown in the Assistant Editor.

Connect map view to window

Upon doing so, Xcode automatically prompts for a name so that it can create an "outlet" connection from the view controller to the map view in the UI. In this topic, this outlet is called mapView.

Set the map view name

If you try to build the application at this stage, you will get compile errors because your application contains a reference to the AGSMapView class that has not been defined yet. Import the ArcGIS module into your swift file. You can now reference any class in the ArcGIS Runtime SDK for OS X.

import Cocoa
import ArcGIS

class AppDelegate: NSObject, NSApplicationDelegate {
                            
    @IBOutlet weak var window: NSWindow!
    @IBOutlet weak var mapView: AGSMapView!
...

}

3. Add content to the map view

You have added a map view to the UI and connected it to the code files. You can now add the map content and specify how the users interact with the map. This tutorial describes how you can add individual map layers to the map view. Remember, you can also display content by opening a preconfigured web map.

Select the swift file in the Navigator. Open it in the source editor. Locate the applicationDidFinishLaunching method and add the code to create an instance of a tiled map service layer. Add this tiled layer to the map.

func applicationDidFinishLaunching(aNotification: NSNotification?) {

 // Insert code here to initialize your application
        
 //Create an instance of a tiled map service layer
 var tiledLayer = AGSTiledMapServiceLayer(URL: NSURL(string: "http://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"))
        
 //Add it to the map view
 self.mapView.addMapLayer(tiledLayer, withName: "Basemap Tiled Layer")
        
 ...
}
    }

If you build and run the application the map will display the content of the ArcGIS Online map service.

Add a map to your app

4. Respond to map actions

A map view informs its delegates when certain actions take place on the map, for instance, when a user taps the map. The map's delegates are responsible for responding to these actions. In addition, a map view also consults its delegates before performing certain actions, for example, 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 on the delegation design pattern.

Depending on the actions you want to handle, set one of your classes as the map view's delegate. A map view has three types of delegates.

Map view layer delegate

The layer delegate is informed about layer related actions, such as when the map loads. Refer to the API reference documentation for the AGSMapViewLayerDelegate protocol to learn about the information conveyed to the layer delegate.

Any class wanting to serve as the layer delegate must adopt the AGSMapViewLayerDelegate protocol and implement the methods related to the actions it is interested in.

Any class wanting to serve as the layer delegate must adopt the AGSMapViewLayerDelegate protocol and implement the methods related to the actions it is interested in. First, adopt the AGSMapViewLayerDelegate protocol in the AppDelegate swift file.

class AppDelegate: NSObject, NSApplicationDelegate, AGSMapViewLayerDelegate {
 ...
}

Implement the mapViewDidLoad method in the swift file. This method is invoked when the map loads.

func mapViewDidLoad(mapView: AGSMapView!) {

 //perform some function once the map has been loaded
 ...

}

Set the map view's layerDelegate.

func applicationDidFinishLaunching(aNotification: NSNotification?) {

 // Insert code here to initialize your application
 ...

 // set the delegate for the map view   
 self.mapView.layerDelegate = self
}

Map view touch delegate

The touch delegate is informed about user interaction with the map, such as when a user taps, or taps and holds 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 delegates: adopt the delegate protocol (AGSMapViewTouchDelegate) in your class; implement the relevant methods of the protocol; set your class as the map view's touchDelegate.

Map view 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. Refer to the API reference documentation for the AGSMapViewCalloutDelegate protocol to learn about the different actions conveyed to the callout delegate.

The procedure for assigning a callout delegate is similar to the one described above for the layer and touch delegates.