AGSMapView Class Reference

Description

An instance of this class represents a map component. It is a container for layers, graphics, gps display and a callout. It responds to user interaction by providing behavior for map navigation, displaying the callout, etc.

The component informs its layerDelegate, touchDelegate, and calloutDelegate whenever certain events take place and also consults the delegates before performing certain actions.

For example, the mapViewDidLoad: method on AGSMapViewLayerDelegate is invoked after the first layer has been added to the map. At this point, the component is fully functional. The mapView:didClickAtPoint:mapPoint:graphics: method on AGSMapViewTouchDelegate is invoked when a user taps on the map.

You can customize the behavior of the map and respond to events by attaching your own delegate classes. Your delegate classes must adopt the necessary protocols.

The map component also broadcasts four notifications - MapViewDidLoad, MapTimeExtentChanged, MapDidEndPanning and MapDidEndZooming. Observers interested in these notifications can register for them using the default NSNotificationCenter.

The first layer added to the map is treated as a basemap layer. It defines the spatialReference of the entire map, and the initial and full extents. The map will not load until this layer loads. When the basemap layer fails to load, other layers in the map are still loaded, but the map does not display any layers.If this When the basemap layer fails to load, you can either remove it from the map or possibly resubmit it if the credentials were incorrect or the network was temporarily down. If the basemap layer is removed the map will treat the next layer as the basemap layer. The next layer chosen will be the layer that is at the bottom-most position, or the layer at index zero.

See also:: Conceptual Doc: Creating a Map

Since:: 1.0

Inheritance diagram for AGSMapView:

List of all members.

Public Member Functions
(AGSEnvelope *envelope)	- __attribute__
(NSArray *mapLayerNames)	- __attribute__
(id< AGSMapViewDelegate > mapViewDelegate)	- __attribute__
(UIView< AGSLayerView > *)	- addMapLayer:withName:
(void)	- calloutDidClickAccessoryButton:
(void)	- centerAtPoint:animated:
(UIView< AGSLayerView > *)	- insertMapLayer:withName:atIndex:
(void)	- removeMapLayerWithName:
(void)	- reset
(void)	- setRotationAngle:animated:
(void)	- setRotationAngle:aroundMapPoint:animated:
(void)	- setRotationAngle:aroundScreenPoint:animated:
(void)	- showCalloutAtPoint:
(void)	- showCalloutAtPoint:forGraphic:animated:
(AGSEnvelope *)	- toMapEnvelope:
(AGSPoint *)	- toMapPoint:
(CGPoint)	- toScreenPoint:
(CGRect)	- toScreenRect:
(void)	- zoomIn:
(void)	- zoomOut:
(void)	- zoomToEnvelope:animated:
(void)	- zoomToGeometry:withPadding:animated:
(void)	- zoomToResolution:withCenterPoint:animated:
(void)	- zoomToScale:withCenterPoint:animated:
(void)	- zoomWithFactor:atAnchorPoint:animated:
Properties
BOOL	allowRotationByPinching
BOOL	animating
AGSCallout *	callout
id< AGSMapViewCalloutDelegate >	calloutDelegate
UIDeviceMachineType	deviceMachineType
AGSEnvelope *	fullEnvelope
AGSGPS *	gps
id< AGSMapViewLayerDelegate >	layerDelegate
BOOL	limitedDeviceCapabilities
BOOL	loaded
NSArray *	mapLayers
UIView *	mapLayersView
NSDictionary *	mapLayerViews
double	mapScale
UIView *	masterView
AGSEnvelope *	maxEnvelope
BOOL	panning
double	resolution
float	rotationAngle
BOOL	showMagnifierOnTapAndHold
AGSSpatialReference *	spatialReference
AGSTimeExtent *	timeExtent
id< AGSMapViewTouchDelegate >	touchDelegate
AGSUnits	units
AGSPolygon *	visibleArea
BOOL	wrapAround
BOOL	zooming

Member Function Documentation

- (AGSEnvelope* envelope) __attribute__ ((deprecated))

The current extent of the map in map units.

Since:: 1.0

Deprecated:: Deprecated at 2.1. Use visibleArea polygon instead.

- (NSArray* mapLayerNames) __attribute__ ((deprecated))

Names of layers currently available in the map. The order of the layer names reflects the order of the layers displayed in the map; layer at index 0 is the bottom-most.

Since:: 1.0

Deprecated:: Deprecated at 1.8. No direct replacement. You can use mapLayers to access the layers.

- (id<AGSMapViewDelegate> mapViewDelegate) __attribute__ ((deprecated))

Delegate to be notified when the map's state is changed.

Since:: 1.0

Deprecated:: Deprecated at 1.8. Use layerDelegate, touchDelegate and calloutDelegate.

- (UIView<AGSLayerView> *) addMapLayer:	(AGSLayer *)	mapLayer
withName:	(NSString *)	name

Add a layer to the map using the specified name. The first layer added to the map is treated as a basemap layer. It defines the full extent and spatialReference of the map.

Parameters:

	mapLayer	Map Layer to be added to the map.
	name	Name of layer. You can pass nil, in which case a name will be provided. If specified, this name must be unique. If the name is not unique, nil will be returned and the layer will never be added to the map.

Returns:: AGSLayerView object used to draw the layer

Since:: 1.0

- (void) calloutDidClickAccessoryButton: (AGSCallout *) callout [optional, inherited]

Tells the delegate the user tapped on the accessory button in the callout

Parameters:

callout

containing accessory button.

Since:: 1.0

- (void) centerAtPoint:	(AGSPoint *)	point
animated:	(BOOL)	animated

Center map at specified location.

Parameters:

	point	Map point to center map. Point must have the same spatial reference as the map. Point must be in map units.
	animated	Determines if the centering should be animated or immediate.

Since:: 1.0

- (UIView<AGSLayerView> *) insertMapLayer:	(AGSLayer *)	mapLayer
withName:	(NSString *)	name
atIndex:	(NSUInteger)	index

Inserts a layer to the map with specified name at index.

Parameters:

	mapLayer	Map Layer of type `AGSLayer` to be added to map.
	name	Name of layer. You can pass nil, in which case a name will be provided. If specified, this name must be unique. If the name is not unique, nil will be returned and the layer will never be added to the map.
	index	Index where layer will be inserted.

Returns:: AGSLayerView used to draw layer

Since:: 1.0

- (void) removeMapLayerWithName: (NSString *) name

Remove a layer from the map with specified name. Even when the basemap layer is removed, the map's envelope , fullEnvelope, and spatialReference properties remain unchanged.

Parameters:

name

Name of the layer to be removed.

Since:: 1.0

- (void) reset

Resets the map to an original and unloaded state. Will remove any and all layers from the map. The spatial reference, extents, and othe properties related to the layer will be cleared. The first layer subsequently added to the map after invoking this method will be treated as a basemap layer.

Since:: 1.8

- (void) setRotationAngle:	(float)	angle
animated:	(BOOL)	animated

Rotate the map in counter-clockwise direction based on the angle (degrees) specified.

Parameters:

	angle	to rotate the map by
	animated	flag indicating if the map should animate to new rotation angle

Since:: 2.1

- (void) setRotationAngle:	(float)	angle
aroundMapPoint:	(AGSPoint *)	mapPoint
animated:	(BOOL)	animated

Rotate the map in counter-clockwise direction based on the angle (degrees) specified.

Parameters:

	angle	to rotate the map by
	mapPoint	the location on the map around which the map should be rotated. The point should have the same spatial reference as the map.
	animated	flag indicating if the map should animate to new rotation angle

Since:: 2.1

- (void) setRotationAngle:	(float)	angle
aroundScreenPoint:	(CGPoint)	screenPoint
animated:	(BOOL)	animated

Rotate the map in counter-clockwise direction based on the angle (degrees) specified.

Parameters:

	angle	to rotate the map by
	screenPoint	the location on screen around which the map should be rotated
	animated	flag indicating if the map should animate to new rotation angle

Since:: 2.1

- (void) showCalloutAtPoint: (AGSPoint *) point

Show callout at specified location. The callout's content will need to be specified through its (AGSCallout) title and detail properties.

Parameters:

point

Map point to display callout at. Point must be in map units and must have the same spatial reference as the map.

Since:: 1.0

- (void) showCalloutAtPoint:	(AGSPoint *)	mapPoint
forGraphic:	(AGSGraphic *)	graphic
animated:	(BOOL)	animated

Show callout at specified location for a specific graphic. The graphic's attributes and infoTemplateDelegate will be used to display content in the callout.

Parameters:

	mapPoint	Map point that will be used for the callout. You can pass `nil` if you want the center of the graphic to be used. If the graphic is represented by a marker symbol, then the `mapPoint` is ignored in order to best place the callout.
	graphic	Graphic that the callout is displaying for.
	animated	Determines whether or not the callout should animate when it is shown.

Since:: 1.0

- (AGSEnvelope *) toMapEnvelope: (CGRect) rect

Converts a rectangle in screen coordinates to an envelope in map units.

Parameters:

rect

Rectangle in screen coordinates to convert from.

Returns:: Envelope in map units. Envelope will have the same spatial reference as the map.

Since:: 1.0

- (AGSPoint *) toMapPoint: (CGPoint) point

Convert the specified point in screen units to a point in map units.

Parameters:

point

Point in screen units.

Returns:: Point in map units. Point will have the same spatial reference as the map.

Since:: 1.0

- (CGPoint) toScreenPoint: (AGSPoint *) point

Convert the specified point in map units to a point in screen units.

Parameters:

point

Point in map units. Point must have the same spatial reference as the map.

Returns:: Point in screen units.

Since:: 1.0

- (CGRect) toScreenRect: (AGSEnvelope *) envelope

Convert the specified envelope in map units to a CGRect in screen units.

Parameters:

envelope

Envelope in map units. Envelope must have the same spatial reference as the map.

Returns:: CGRect in screen coordinates

Since:: 1.0

- (void) zoomIn: (BOOL) animated

Zooms in to the current center of the map by a factor of .5.

Parameters:

animated

Determines if the zooming in should be animated or immediate.

Since:: 1.0

- (void) zoomOut: (BOOL) animated

Zooms out to the current center of the map by a factor of 2.

Parameters:

animated

Determines if the zooming out should be animated or immediate.

Since:: 1.0

- (void) zoomToEnvelope:	(AGSEnvelope *)	envelope
animated:	(BOOL)	animated

Zoom/Pan the map to specified envelope.

Parameters:

	envelope	Map envelope to zoom/pan to. Envelope must have the same spatial reference as the map. Envelope must be in map units.
	animated	Determines if the scrolling should be animated or immediate.

Since:: 1.0

- (void) zoomToGeometry:	(AGSGeometry *)	geometry
withPadding:	(float)	padding
animated:	(BOOL)	animated

Zooms the map such that the given geometry fits the bounds of the map.

Parameters:

	geometry	to zoom to
	padding	in points so that the geometry may not touch any edges of the map
	animated	flag indicating whether to animate the zoom action

Since:: 2.1

- (void) zoomToResolution:	(double)	res
withCenterPoint:	(AGSPoint *)	centerPoint
animated:	(BOOL)	animated

Zooms the map to the given resolution

Parameters:

	res	The resolution (map units per pixel) to zoom to
	centerPoint	to zoom around. If nil and the gps autoPanMode is `AGSGPSAutoPanModeNavigation` or `AGSGPSAutoPanModeCompassNavigation`, the map zooms around the location symbol. If the gps is not in those modes, but the centerPoint is nil, map zooms around its center.
	animated	flag indicating whether to animate the zoom action

Since:: 2.1

- (void) zoomToScale:	(double)	scale
withCenterPoint:	(AGSPoint *)	centerPoint
animated:	(BOOL)	animated

Zooms the map to the given scale

Parameters:

	scale	to zoom to
	centerPoint	to zoom around. If nil and the gps autoPanMode is `AGSGPSAutoPanModeNavigation` or `AGSGPSAutoPanModeCompassNavigation`, the map zooms around the location symbol. If the gps is not in those modes, but the centerPoint is nil, map zooms around its center.
	animated	flag indicating whether to animate the zoom action

Since:: 2.1

- (void) zoomWithFactor:	(double)	factor
atAnchorPoint:	(CGPoint)	anchorPoint
animated:	(BOOL)	animated

Zooms map by a factor. Anchor Point is in screen coordinates of the map view.

Parameters:

	factor	Used to determine the amount to zoom. For example, use 0.5 to zoom in twice as far and 2.0 to zoom out twice as far.
	anchorPoint	Point in screen coordinates around which to zoom. This is ignored if the gps autoPanMode is `AGSGPSAutoPanModeNavigation` or `AGSGPSAutoPanModeCompassNavigation` in which case map zooms around the location symbol.
	animated	Determines if the zooming should be animated or immediate.

Since:: 1.0

Property Documentation

- (BOOL) allowRotationByPinching [read, write, assign]

Flag to indicate if a user should be allowed to rotate the map using a two finger twist gesture. Default is NO.

Since:: 2.1

- (BOOL) animating [read, assign]

Flag to indicate if the map is animating.

Since:: 1.0

- (AGSCallout*) callout [read, retain]

A callout view for displaying information on the map.

Since:: 1.0

- (id<AGSMapViewCalloutDelegate>) calloutDelegate [read, write, assign]

Delegate to be notified when map callout actions occur.The delegate class must adopt the AGSMapViewCalloutDelegate protocol.

Since:: 1.8

- (UIDeviceMachineType) deviceMachineType [read, assign]

Returns the type of device currently running the application. This is useful if we want to disable certain features to gain performance on older devices.

Since:: 1.0

- (AGSEnvelope*) fullEnvelope [read, retain]

The full extent of map.

Since:: 1.0

- (AGSGPS*) gps [read, retain]

The display that shows the current location of the device, which is updated from the CLLocationManager.

Since:: 1.0

- (id<AGSMapViewLayerDelegate>) layerDelegate [read, write, assign]

Delegate to be notified when map layer actions occur. The delegate class must adopt the AGSMapViewLayerDelegate protocol.

Since:: 1.8

- (BOOL) limitedDeviceCapabilities [read, assign]

Flag to indicate if the current device has been limited to gain performance.

Since:: 1.0

- (BOOL) loaded [read, assign]

After the first layer added to the map is loaded, this value is set to true.

Since:: 1.0

- (NSArray*) mapLayers [read, retain]

Array of AGSLayer objects representing the layers in the map. Depending upon the type of layer, each object will be specific sub-class of AGSLayer.

Since:: 1.8

- (UIView*) mapLayersView [read, retain]

View that contains the layer views. Do not modify the contents of this view directly. It is for informational purposes only.

Since:: 1.0

- (NSDictionary*) mapLayerViews [read, retain]

Dictionary providing access to AGSLayerView objects for each layer in the map. View object can be retrieved using layer's name as the key.

See also:: - addMapLayer:withName:

Since:: 1.0

- (double) mapScale [read, assign]

The current scale of the map. Will return 0 if it cannot be calculated.

Since:: 1.0

- (UIView*) masterView [read, retain]

Master view for child views of the map. Do not modify the contents of this view directly. It is for informational purposes only.

Since:: 1.0

- (AGSEnvelope*) maxEnvelope [read, write, retain]

Limits the amount by which the map can be panned such that its anchor point (typically the center) never goes outside this envelope. By default, this is the full envelope of the basemap layer. If you set a custom extent, the envelope must have the same spatial reference as the map.

Since:: 2.1

- (BOOL) panning [read, assign]

Flag to indicate if the map is panning.

Since:: 1.0

- (double) resolution [read, assign]

The map's current resolution (map units per Point).

Since:: 1.0

- (float) rotationAngle [read, write, assign]

The rotation angle (in degrees). The map is rotated in a counter-clockwise direction by the amount specified. To specify a new angle, see

See also:: - setRotationAngle:animated:; - setRotationAngle:aroundMapPoint:animated:; - setRotationAngle:aroundScreenPoint:animated:

Since:: 2.1

- (BOOL) showMagnifierOnTapAndHold [read, write, assign]

Flag to indicate if the map should show the magnifier when the user performs a tap and hold gesture on the map. Default is NO

- (AGSSpatialReference*) spatialReference [read, retain]

The spatial reference of the map. Defined by the basemap layer.

Since:: 1.0

- (AGSTimeExtent*) timeExtent [read, write, retain]

The time extent for the map. Will be used only for time-aware layers.

Availability:: This feature is only available with services from ArcGIS Server 10.0 or above

See also:: Conceptual Doc: Viewing Temporal Data; Sample: Temporal

Since:: 1.0

- (id<AGSMapViewTouchDelegate>) touchDelegate [read, write, assign]

Delegate to be notified when touch events occur on the map.The delegate class must adopt the AGSMapViewTouchDelegate protocol.

Since:: 1.8

- (AGSUnits) units [read, assign]

The units the map is in. Possible values include

AGSUnitsCentimeters
AGSUnitsDecimalDegrees
AGSUnitsDecimeters
AGSUnitsFeet
AGSUnitsInches
AGSUnitsKilometers
AGSUnitsMeters
AGSUnitsMiles
AGSUnitsMillimeters
AGSUnitsNauticalMiles
AGSUnitsPoints
AGSUnitsUnknown
AGSUnitsYards

Since:: 1.0

- (AGSPolygon*) visibleArea [read, retain]

A polygon representing the map's visible area. The polygon always contains 1 ring with 4 vertices, each representing a corner of the map.

This is a replacement for envelope. An envelope is no longer be used to represent the visible area because the map may be rotated and each corner of the map may contain unique x-y coordinates, where as an envelope only permits 2 unique x coordinates (xmin, xmax) and 2 unique y coordinates (ymin, ymax).

Since:: 2.1

- (BOOL) wrapAround [read, write, assign]

Flag to indicate if the map should wrap around. Default is NO. When YES, the map may need to zoom depending on the resolution. The map also may reset this property back to NO if the layers don't conform to certain properties.

See also:: Conceptual Doc: Enabling Wrap Around

Since:: 1.8

- (BOOL) zooming [read, assign]

Flag to indicate if the map is zooming.

Since:: 1.0

AGSMapView Class Reference

Description

Public Member Functions

Properties

Member Function Documentation

Property Documentation