Overview
A map is basically an empty canvas onto which one or more layers are drawn. ArcGIS API for iOS provides a wide variety of pre-defined layers.
Layer types
Most layers display content from GIS server web services, such as ArcGIS Server, Bing Maps, etc. These layers fall into two broad categories – dynamic layers and tiled layers. Dynamic layers rely on web services that generate map images on-the-fly. Tiled layers rely on web services that provide pre-generated map images. Tiled layers provide much better performance than dynamic layers because they do not have to genereate map images when needed by the client, instead the map images are generated ahead of time based on some tiling scheme and readily available.
A Graphic layer is a special type of dynamic layer. It does not rely on any web service for its content. Its content is made up of graphics that are added to the layer.
Adding Layers to the Map
To add a layer to a map, you need to
1) Instantiate the layer. If the layer relies on a web service, you need to provide the URL of the service. If the web service is secured, you will also need to provide the necessary credentials to access the service.
NSURL* url = [NSURL URLWithString: @" http://server.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"];
AGSTiledMapServiceLayer* layer = [AGSTiledMapServiceLayer tiledMapServiceLayerWithURL: url];
2) Add the layer to the map view using the addMapLayer:withName method. By default, the layer is added on top of any existing layers. Layers are drawn in a bottom-up order. This means that a layer can potentially obscure the contents of other layers beneath it. If you wish to insert the layer at a specific position, you can use the insertMapLayer:withName:atIndex: method where an index of 0 will insert the new layer at the bottom. You need to provide a unique name while adding or inserting a layer. The map uses this to keep track of the layer incase you want to retrieve it later.
UIView<AGSLayerView>* lyrView = [mapView addMapLayer:layer withName:@"Streets"];
Once the layer is successfully added, its content will begin appearing in the map.
Accessing Layer properties
If a layer relies on a web service, it connects to the service when the layer is added to a map. The service usually provides, among other things, default values for the layer's properties. For example, an AGSTiledMapServiceLayer connects to an ArcGIS Server Map service to get information about the extent, tiling scheme, etc. Layer properties are initialized only after a response is recieved from the service. Depending upon factors such as the time a service takes to respond, the quality of the network connection, and so on, it may take a while before a layer's properties are initialized and it is successfully added to a map.
Layers connect to web services in the background. They do not block the thread on which they were added to a map. Hence, you should not assume that a layer was successfully added to a map when the addMapLayer method completes. For the same reason, you should not attempt to access the layer's proprties until it has been successfully added to a map.
When a layer is succcessfully added to a map, its loaded property is enabled. This means that the layer successfully contacted it's web service, if it needed to, and recieved a response. It also indicates that all properties on the layer have been fully initialized.
Verifying the Layer was added
A map informs its delegate when a layer is successfully added or if an error is encountered while adding a layer. To be notified of either of these events, you must set one of your classes as the map’s delegate. You do this by making your class (typically the view controller which manages the map) adopt the AGSMapViewDelegate protocol.
@interface MyViewController : UIViewController <AGSMapViewDelegate>
...
@end
The delegate class must also implement one or more methods defined in the protocol which pertain to the operation being performed. For example, the class must implement the mapView:didLoadLayerForLayerView: method to be notified when a layer is successfully added. To be notified when an error is encountered while adding a layer, the class must implement the mapView:failedLoadingLayerForLayerView:withError: method.
@implementation MyViewController
- (void) mapView:(AGSMapView*) mapView didLoadLayerForLayerView:(UIView<AGSLayerView>*) layerView {
NSLog(@"Layer added successfully");
}
- (void) mapView:(AGSMapView*) mapView failedLoadingLayerForLayerView:(UIView<AGSLayerView>*) layerView withError:(NSError*) error {
NSLog(@"Error: %@",error);
}
@end
Finally, an instance of the class must then be set as the map’s delegate. This will allow the map to inform your class when a layer is successfully added or not..
mapView.mapViewDelegate = self;
Once the layer is successfully added, its content will begin appearing in the map, and you can safely access the layer's properties.
Layer View objects
After adding or inserting a layer, a map returns a handle to a Vew object. This view object implements the AGSLayerView protocol and is responsible for displaying the layer’s contents on the screen. You should keep a reference to this view object if, for instance, you intend to adjust the layer’s transparency or hide the layer.
UIView<AGSLayerView>* lyrView = [mapView addMapLayer:layer withName:@"Streets"];
//hide the layer
lyrView.hidden = YES;
//or make it semi-transparent
lyrView.alpha = 0.5 ;
Map's spatial reference
The first layer you add to a map is considered to be the basemap layer. It dictates the overall spatial reference of a map. Any tiled layers you subsequently add to a map must also be in this spatial reference, otherwise their content will not be displayed. Dynamic layers, on the other hand, can be in any spatial reference. They will automatically re-project their content, if necessary, into the map's spatial reference.