Reference

For the most part, QuickStart methods are added to categories on AGSMapView (assume so in the following documentation unless stated otherwise).

Classes, constants, #defines and types provided by the QuickStart library use the three-letter EQS prefix.

Public category methods do not use a prefix.

Basemaps

Set the basemap of the AGSMapView to one of the standard basemap types (defined by the EQSBasemapType enumeration). Note that Bing Maps are not currently supported.

@property (nonatomic, assign) EQSBasemapType basemap;

The EQSBasemapType enumeration is defined as follows:

typedef enum {
    EQSBasemapTypeStreet = 1,
    EQSBasemapTypeSatellite = 2,
    EQSBasemapTypeHybrid = 3,
    EQSBasemapTypeCanvas = 4,
    EQSBasemapTypeNationalGeographic = 5,
    EQSBasemapTypeTopographic = 6,
    EQSBasemapTypeOpenStreetMap = 7,
    
    EQSBasemapTypeFirst = EQSBasemapTypeStreet,
    EQSBasemapTypeLast = EQSBasemapTypeOpenStreetMap
} EQSBasemapType;

The following notification is raised on the AGSMapView when the basemap has changed successfully:

kEQSNotification_BasemapDidChange

And the following can be read from the notification's NSNotification parameter, which represent the new basemap.

@property (nonatomic, readonly) AGSPortalItem *basemapPortalItem;
@property (nonatomic, readonly) EQSBasemapType basemapType;

The following convenience method is also provided. This will set the core runtime's corresponding property on any basemap layer(s). See documentation here.

@property (nonatomic, assign) BOOL renderBasemapsAtNativeResolution;

Navigation

The following methods augment the core runtime's navigation methods on AGSMapView. Specifically they support zoom and pan using lat/lon and an integer zoom level.

- (void) centerAtLat:(double)latitude lon:(double)longitude animated:(BOOL)animated;

- (void) zoomToLevel:(NSUInteger)level withLat:(double)latitude lon:(double)longitude animated:(BOOL)animated;
- (void) zoomToLevel:(NSUInteger)level withCenterPoint:(AGSPoint *)centerPoint animated:(BOOL)animated;
- (void) zoomToLevel:(NSUInteger)level animated:(BOOL)animated;

- (void) zoomToPlace:(NSString *)searchString animated:(BOOL)animated;

@property (nonatomic, assign) AGSPoint *centerPoint; // Setting is animated
@property (nonatomic, assign) NSUInteger zoomLevel; // Setting is animated

The following convenience methods pan or zoom the map to the device's current location without displaying any GPS symbology on the map or turning on the runtime's GPS tracking.

- (void) centerAtMyLocation;
- (void) centerAtMyLocationWithZoomLevel:(NSUInteger)level;

Geoservices

A Geoservices object of type EQSGeoServices is created on the AGSMapView. This encapsulates all GeoServices operations into one place, rather than embedding directly into the AGSMapView.

A single property is added to the AGSMapView to reference this GeoServices provider object.

@property (nonatomic, readonly) EQSGeoServices *geoServices;

GeoServices Object

The EQSGeoServices class provides the following functionality:

- (NSOperation *) findPlaces:(NSString *)singleLineAddress;
- (NSOperation *) findPlaces:(NSString *)singleLineAddress withinEnvelope:(AGSEnvelope *)env;
- (NSOperation *) findAddressFromPoint:(AGSPoint *)mapPoint;
- (NSOperation *) findDirectionsFrom:(AGSPoint *)startPoint to:(AGSPoint *)endPoint;
- (NSOperation *) findDirectionsFrom:(AGSPoint *)startPoint named:(NSString *)startPointName
                                  to:(AGSPoint *)endPoint named:(NSString *)endPointName;

@property (nonatomic, readonly) BOOL geolocationEnabled;
- (void) findMyLocation;

and raises the following notifications:

kEQSGeoServicesNotification_FindPlaces_OK
kEQSGeoServicesNotification_FindPlaces_Error

kEQSGeoServicesNotification_AddressFromPoint_OK
kEQSGeoServicesNotification_AddressFromPoint_Error

kEQSGeoServicesNotification_FindDirections_OK
kEQSGeoServicesNotification_FindDirections_Error

kEQSGeoServicesNotification_Geolocation_OK
kEQSGeoServicesNotification_Geolocation_Error

A convenience method is provided to register for both success and failure notifications for each geoservice:

- (void) registerHandler:(id)object forFindPlacesSuccess:(SEL)successHandler andFailure:(SEL)failureHandler;
- (void) registerHandler:(id)object forFindAddressFromPointSuccess:(SEL)successHandler andFailure:(SEL)failureHandler;
- (void) registerHandler:(id)object forFindDirectionsSuccess:(SEL)successHandler andFailure:(SEL)failureHandler;
- (void) registerHandler:(id)object forFindMyLocationSuccess:(SEL)successHandler andFailure:(SEL)failureHandler;

GeoServices helpers on NSNotification and AGSLocatorFindResult

When notifications are raised, an NSNotification object is passed to the handler. Convenience methods are added to NSNotification to help the developer read relevant information from the GeoService result.

Results and original parameters are exposed where relevant.

Note: Notifications are raised on the EQSGeoServices instance, not on the AGSMapView.

Common: All success or failure notifications include the NSOperation that was returned when the operation was requested.

@property (nonatomic, readonly) NSOperation *geoServicesOperation;

And failure notifications also include an NSError.

@property (nonatomic, readonly) NSError *geoServicesError;

Find Places: The following can be read on a Find Places (forward geocode) result.

Source parameters for kEQSGeoServicesNotification_FindPlaces_OK, kEQSGeoServicesNotification_FindPlaces_Error

@property (nonatomic, readonly) NSString *findPlacesSearchString;
@property (nonatomic, readonly) AGSEnvelope *findPlacesSearchExtent; // may be nil

Results for kEQSGeoServicesNotification_FindPlaces_OK

@property (nonatomic, readonly) NSArray *findPlacesResults;
@property (nonatomic, readonly) NSArray *findPlacesResultSortedByScore;

The following convenience readonly properties are added to AGSLocatorFindResult objects returned from Find Places success, (access with findPlacesCandidates or findPlacesCandidatesSortedByScore).

@property (nonatomic, readonly) CGFloat score;
@property (nonatomic, readonly) AGSPoint *location;

Find Address: The following can be read on a Find Address (reverse geocode) result.

Source parameters for kEQSGeoServicesNotification_AddressFromPoint_OK, kEQSGeoServicesNotification_AddressFromPoint_Error

@property (nonatomic, readonly) AGSPoint *findAddressSearchPoint;
@property (nonatomic, readonly) double findAddressSearchDistance;

Results for kEQSGeoServicesNotification_AddressFromPoint_OK

@property (nonatomic, readonly) AGSAddressCandidate *findAddressCandidate;

Find Directions: The following can be read on a Find Directions result.

Results for kEQSGeoServicesNotification_FindDirections_OK

@property (nonatomic, readonly) AGSRouteTaskResult *routeTaskResults;

Geolocate: The following can be read on a GeoLocate result.

Results for kEQSGeoServicesNotification_Geolocation_OK

@property (nonatomic, readonly) CLLocation *geolocationResult;
@property (nonatomic, readonly) AGSPoint *geolocationMapPoint;

Graphics

Methods are added to AGSMapView to abstract the addition of graphics to the Map View. The creation and management of underlying AGSGraphicsLayer objects is hidden from the developer. This provides a zero-config option for new developers who just want to "put a pin on a map".

// Create and add a graphic at lat/lon
- (AGSGraphic *) addPointAtLat:(double)latitude lon:(double)longitude;
- (AGSGraphic *) addPointAtLat:(double)latitude lon:(double)longitude withSymbol:(AGSMarkerSymbol *)markerSymbol;

// Create and add a graphic given a geometry
- (AGSGraphic *) addPoint:(AGSPoint *)point;
- (AGSGraphic *) addPoint:(AGSPoint *)point withSymbol:(AGSMarkerSymbol *)markerSymbol;

- (AGSGraphic *) addLineFromPoints:(NSArray *) points;
- (AGSGraphic *) addPolygonFromPoints:(NSArray *) points;

// Add a pre-created graphic
- (AGSGraphicsLayer *) addGraphic:(AGSGraphic *)graphic;
- (AGSGraphicsLayer *) addGraphic:(AGSGraphic *)graphic withAttribute:(NSString *)attributeName withValue:(id)value;

// Remove graphics
- (AGSGraphicsLayer *) removeGraphic:(AGSGraphic *)graphic;
- (NSSet *) removeGraphicsMatchingCriteria:(BOOL(^)(AGSGraphic *graphic))checkBlock;
- (NSSet *) removeGraphicsByAttribute:(NSString *)attributeName withValue:(id)value;
- (void) clearGraphics:(EQSGraphicsLayerType)layerType;
- (void) clearGraphics;

The following convenience accessor is provided to get hold of any of the managed AGSGraphicsLayer objects if need be:

- (AGSGraphicsLayer *) getGraphicsLayer:(EQSGraphicsLayerType)layerType;

And EQSGraphicsLayerType is defined as

typedef enum {
    EQSGraphicsLayerTypePoint = 1,
    EQSGraphicsLayerTypePolyline = 2,
    EQSGraphicsLayerTypePolygon = 4
} EQSGraphicsLayerType;

Editing Graphics

Editing graphics is abstracted to the AGSMapView by providing convenience methods and hooking into the AGSSketchGraphicsLayer and its NSUndoManager.

// Edit new graphics with the AGSSketchGraphicsLayer
- (void) createAndEditNewPoint;
- (void) createAndEditNewMultipoint;
- (void) createAndEditNewLine;
- (void) createAndEditNewPolygon;

// Edit an existing graphic
- (void) editGraphic:(AGSGraphic *)graphic;

// Convenience method to call from mapView:didClickAtPoint
// Will find an existing graphic on the map and start editing it if possible.
- (AGSGraphic *) editGraphicFromMapViewDidClickAtPoint:(NSDictionary *)graphics;

// Editing commands
- (AGSGraphic *) saveGraphicEdit;
- (AGSGraphic *) cancelGraphicEdit;
- (void) undoGraphicEdit;
- (void) redoGraphicEdit;

To handle Undo and Redo operations, the following convenience methods are provided to hook into notifications from the NSUndoManager exposed by the underlying AGSSketchGraphicsLayer.

- (NSUndoManager *) registerListener:(id)object ForEditGraphicUndoRedoNotificationsUsing:(SEL)handlerMethod;
- (void) stop:(id)listener ListeningForEditGraphicUndoRedoNotificationsOn:(NSUndoManager *)manager;

@property (nonatomic, readonly) NSUndoManager *undoManagerForGraphicsEdits;

Should the developer need access to the graphic or geometry being edited they can make use of these convenience methods.

@property (nonatomic, readonly) AGSGeometry *currentEditGeometry;
@property (nonatomic, readonly) AGSGraphic *currentEditGraphic;

Graphics helpers on AGSGraphicsLayer

For consistency with the above abstraction, the following methods are also presented on AGSGraphicsLayer.

- (void) addGraphic:(AGSGraphic *)graphic withAttribute:(id)attribute withValue:(id)value;

- (void) addGraphic:(AGSGraphic *)graphic withID:(NSString *)graphicID;
- (AGSGraphic *) getGraphicForID:(NSString *)graphicID;

- (NSSet *) removeGraphicsMatchingCriteria:(BOOL(^)(AGSGraphic *graphic))checkBlock;
- (NSSet *) removeGraphicsByAttribute:(id)attribute withValue:(id)value;
- (NSSet *) removeGraphicsByID:(NSString *)graphicID;

Note: A quick review of AGSMapView and AGSGraphicsLayer is needed to bring them into line with one-another.

General Extensions

AGSPoint and AGSMutablePoint

The following methods are added to AGSPoint for lat/lon operations:

+ (AGSPoint *) pointFromLat:(double)latitude lon:(double)longitude;
@property (nonatomic, readonly) double latitude;
@property (nonatomic, readonly) double longitude;

And to AGSMutablePoint

-(void) updateWithLat:(double)latitude lon:(double)longitude;

And the following convenience methods for getting an AGSPoint in a relevant spatial reference

- (AGSPoint *) getWebMercatorAuxSpherePoint;
- (AGSPoint *) getWGS84Point;

Directions Display

A convenience object is provided to help with user interaction in finding and displaying directions.

@property (nonatomic, readonly) EQSRouteDisplayHelper *routeDisplayHelper;

For more details, see the Directions Display documentation.