HERE iOS SDK Developer's Guide

NMAMapView

Class Summary

class NMAMapView

Derived from: UIView

A UIView subclass used by an application to display a geographical map.

Include: NMAKit.framework/headers/NMAMapView.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAMapView

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, copy] NMAGeoBoundingBox boundingBox

The NMAGeoBoundingBox representing the current screen area of the NMAMapView

[readable, writable, assign] float  copyrightLogoHorizontalMargin

The distance in points that the copyright logo will be from the left or right edge of the NMAMapView.

[readable, writable, assign] NMALayoutPosition   copyrightLogoPosition

The copyright logo position for the NMAMapView.

[readable, writable, assign] float  copyrightLogoVerticalMargin

The distance in points that the copyright logo will be from the top or bottom edge of the NMAMapView.

[readable, writable, weak] id< NMAMapViewDelegate delegate

An event handler for the NMAMapView

[readable, assign] NSString *  displayLanguage

The language which the map is set to render

[readable, writable, assign] NMAGeoCoordinates geoCenter

The NMAGeoCoordinates of the world location corresponding to the current screen position of the transformCenter

[readable, writable, weak] id< NMAMapGestureDelegate gestureDelegate

An optional delegate to receive gestures events

[readable, writable, assign] BOOL  kineticPanningEnabled

Indicates the kinetic panning behaviour of the NMAMapView

[readable, writable, assign] NSTimeInterval  longPressDuration

The touch duration required to trigger a long press gesture

[readable, writable, assign] BOOL  mapCenterFixedOnZoom

Indicates whether the transform center is used on zoom gestures

[readable, writable, assign] BOOL  mapInteractionEnabled

Indicates the state of enabling and modifying map gesture interaction for the NMAMapView

[readable, writable, assign] NMAMapPPI   mapPPI

[readable, writable, strong] NSString *  mapScheme

The scheme for the NMAMapView

[readable, assign] NMAPositionIndicator positionIndicator

The position indicator for the NMAMapView

[readable, writable, assign] BOOL  renderAllowed

A flag which can be used to allow or disallow map rendering

[readable, assign] NSString *  secondaryDisplayLanguage

The secondary language which the map is set to render

[readable, writable, assign] CGPoint  transformCenter

The point at which map movements and animations are centered

[readable, writable, assign] BOOL  useHighResolutionMap

[readable, writable, assign] float  zoomLevel

The zoom level for the NMAMapView

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(BOOL) addMapObject:(add(_:)) NS_SWIFT_NAME

Adds a NMAMapObject to the NMAMapView

-(BOOL) addMapObjects:(add(objects:)) NS_SWIFT_NAME

Adds a NSArray of NMAMapObject objects to the NMAMapView

-(void) addMapTileLayer:(add(mapTileLayer:)) NS_SWIFT_NAME

Adds a NMAMapTileLayer to the map view for rendering custom raster tiles

-(void) disableMapGestures:(NSUInteger) gestures

Disable one or more NMAMapView gestures

-(void) enableMapGestures:(NSUInteger) gestures

Enable one or more NMAMapView gestures

-(nullable NMAGeoCoordinates *) geoCoordinatesFromPoint:(geoCoordinates(from:)) NS_SWIFT_NAME

Converts a specified on-screen point to an equivalent NMAGeoCoordinates object

-(BOOL) isMapGestureEnabled:( NMAMapGestureType ) gesture

Queries whether or not a gesture type is enabled on the NMAMapView

-(NSArray< NMAMapTileLayer * > *) mapTileLayers

Returns an array of NMAMapTileLayer instances that have been added to the map view

-(NSArray< __kindof NMAMapObject * > *) objectsAtPoint:(objects(at:)) NS_SWIFT_NAME

Returns a NSArray of all NMAMapObject objects that are selected at a specified point on the screen

-(double) pointDistanceFromGeoCoordinates:( NMAGeoCoordinates *) startCoordinates toGeoCoordinates:(pointDistance(from:to:)) NS_SWIFT_NAME

Calculates the point distance between two geo coordinates

-(CGPoint) pointFromGeoCoordinates:(point(from:)) NS_SWIFT_NAME

Converts a specified NMAGeoCoordinates object to its equivalent point in screen space.

-(BOOL) removeMapObject:(remove(_:)) NS_SWIFT_NAME

Removes an existing NMAMapObject from the NMAMapView

-(BOOL) removeMapObjects:(remove(objects:)) NS_SWIFT_NAME

Removes a NSArray of NMAMapObject objects from the NMAMapView

-(void) removeMapTileLayer:(remove(mapTileLayer:)) NS_SWIFT_NAME

Removes a NMAMapTileLayer from the map view

-(void) setBoundingBox:( NMAGeoBoundingBox *) boundingBox insideRect:(CGRect) screenRect withAnimation:(set(boundingBox:inside:animation:)) NS_SWIFT_NAME

Transforms the map to fit an arbitrary geo bounding box with the bounds of a specific screen region with optional animation

-(void) setBoundingBox:( NMAGeoBoundingBox *) boundingBox withAnimation:(set(boundingBox:animation:)) NS_SWIFT_NAME

Sets the geo bounding box of the map view with optional animation

-(void) setGeoCenter:( NMAGeoCoordinates *) geoCenter withAnimation:(set(geoCenter:animation:)) NS_SWIFT_NAME

Sets the geoCenter of the map with optional animation

-(void) setGeoCenter:( NMAGeoCoordinates *) geoCenter zoomLevel:(float) zoomLevel withAnimation:(set(geoCenter:zoomLevel:animation:)) NS_SWIFT_NAME

Simultaneously sets one or more map transformation properties with optional animation

-(void) setGeoCoordinates:( NMAGeoCoordinates *) coordinates toPoint:(CGPoint) point withAnimation:(set(coordinates:to:animation:)) NS_SWIFT_NAME

Positions the NMAMapView so that the specified world location coincides with the specified screen location

-(void) setGeoCoordinates:( NMAGeoCoordinates *) coordinates toPoint:(CGPoint) point withAnimation:( NMAMapAnimation ) animation zoomLevel:(set(coordinates:to:animation:zoomLevel:)) NS_SWIFT_NAME

Positions the NMAMapView so that the specified world location coincides with the specified screen location

-(void) setZoomLevel:(float) zoomLevel withAnimation:(set(zoomLevel:animation:)) NS_SWIFT_NAME

Sets the zoomLevel of the map with optional animation

-(BOOL) useDefaultDisplayLanguage

Set the map display language using the system default locale

-(BOOL) useDisplayLanguageFromLocale:(NSLocale *) locale

Set the map display language using the locale specifed

-(BOOL) useSecondaryDisplayLanguageFromLocale:(NSLocale *_Nullable) locale

Set the secondary map display language using the locale specifed

-(NSArray< __kindof NMAMapObject * > *) visibleObjectsAtPoint:(visibleObjects(at:)) NS_SWIFT_NAME

Returns a NSArray of all visible NMAMapObject objects that are selected at a specified point on the screen

Class Method Summary

Table 3. Class Methods
Class Methods

+(void) shouldBeginRenderingAutomatically:(BOOL) enabled

Used to control the default NMAMapView rendering behaviour

Class Details

A UIView subclass used by an application to display a geographical map.

Public Property Details

[readable, copy] NMAGeoBoundingBoxboundingBox

The NMAGeoBoundingBox representing the current screen area of the NMAMapView.

The boundingBox of the map is the smallest possible NMAGeoBoundingBox which contains all of the map area currently visible on the screen.

Note:

The bounding box may be slightly inaccurate if the method is invoked while the map is moving.

[readable, writable, assign] float copyrightLogoHorizontalMargin

The distance in points that the copyright logo will be from the left or right edge of the NMAMapView.

Note:

Values less than 10.0 will be ignored.

Note:

Does not apply when the copyrightLogoPosition is NMALayoutPositionTopCenter or NMALayoutPositionBottomCenter.

[readable, writable, assign] NMALayoutPosition  copyrightLogoPosition

The copyright logo position for the NMAMapView.

Note:

Valid values are NMALayoutPositionTopLeft, NMALayoutPositionTopCenter, NMALayoutPositionTopRight, NMALayoutPositionBottomLeft, NMALayoutPositionBottomCenter, and NMALayoutPositionBottomRight.

[readable, writable, assign] float copyrightLogoVerticalMargin

The distance in points that the copyright logo will be from the top or bottom edge of the NMAMapView.

Note:

Values less than 10.0 will be ignored.

[readable, writable, weak] id< NMAMapViewDelegatedelegate

An event handler for the NMAMapView.

An object may be installed as the NMAMapView's delegate in order to respond to certain map events, such as object selection or map movement. See the NMAMapViewDelegate protocol for the full list of events.

[readable, assign] NSString * displayLanguage

The language which the map is set to render.

[readable, writable, assign] NMAGeoCoordinatesgeoCenter

The NMAGeoCoordinates of the world location corresponding to the current screen position of the transformCenter.

[readable, writable, weak] id< NMAMapGestureDelegategestureDelegate

An optional delegate to receive gestures events.

See also:

NMAMapGestureDelegate

[readable, writable, assign] BOOL kineticPanningEnabled

Indicates the kinetic panning behaviour of the NMAMapView.

When kinetic panning is enabled, at the conclusion of a pan gesture (when the user's finger is removed from the device), the map will continue moving in the direction and with the speed of the original pan before gradually coming to a stop.

[readable, writable, assign] NSTimeInterval longPressDuration

The touch duration required to trigger a long press gesture.

Note:

The default value is 1 second.

[readable, writable, assign] BOOL mapCenterFixedOnZoom

Indicates whether the transform center is used on zoom gestures.

By default disabled. If enabled, zoom will always be applied using the current transform center, instead of a point relative the touch interaction. See the transformCenter property.

Note:

The transform center is usually the same as the screen's geometric center, except in cases where it makes sense to have it slightly modified (example: in guidance mode, the transform center is lowered a bit so that the route ahead is more visible in the map view).

[readable, writable, assign] BOOL mapInteractionEnabled

Indicates the state of enabling and modifying map gesture interaction for the NMAMapView.

If enabled, gesture handlers can be enabled to begin gesture handling. If disabled, all gesture handling is disabled and the gesture handler state cannot be modified.

[readable, writable, assign] NMAMapPPI  mapPPI

[readable, writable, strong] NSString * mapScheme

The scheme for the NMAMapView.

See NMAMapScheme for supported schemes.

[readable, assign] NMAPositionIndicatorpositionIndicator

The position indicator for the NMAMapView.

[readable, writable, assign] BOOL renderAllowed

A flag which can be used to allow or disallow map rendering.

Note:

Setting renderAllowed to NO guarantees that the map will not draw again (but it will finish if a frame is in the middle of rendering), but the map may not redraw with renderAllowed set to YES if it is prevented from drawing for another reason.

Note:

The map can be hinted to redraw (if allowed) by calling setNeedsDisplay.

[readable, assign] NSString * secondaryDisplayLanguage

The secondary language which the map is set to render.

[readable, writable, assign] CGPoint transformCenter

The point at which map movements and animations are centered.

The transformCenter is a point within the bounds of the map that is used to orient the map during transformations. For example, when one of the setGeoCenter:zoomLevel:withAnimation: and setGeoCenter:withAnimation: methods is used, the specified geocoordinates will be aligned with the transformCenter on the screen.

The transformCenter is specified in relative coordinates in the range {[0, 1], [0, 1]}, with {0, 0} representing the upper left corner of the map and {1, 1} the lower right corner.

Note:

The default value is {0.5, 0.5}.

Note:

The center point of map movements caused by gestures will depend on the touch locations of the gestures and not on the transformCenter.

Note:

Values on or very near the edge of the map will be ignored.

Note:

Values above the horizon will be ignored.

[readable, writable, assign] BOOL useHighResolutionMap

[readable, writable, assign] float zoomLevel

The zoom level for the NMAMapView.

Note:

Values must be in the range [NMAMapViewMinimumZoomLevel, NMAMapViewMaximumZoomLevel]; invalid values will be clamped to this range.

Instance Method Details

-(BOOL) addMapObject:(add(_:)) NS_SWIFT_NAME

Adds a NMAMapObject to the NMAMapView.

Note:

Returns NO if the object has already been added (duplicates are not allowed).

Parameters:

  • object

    A NMAMapObject to add

Returns:

YES if the map object was added successfully, NO otherwise

-(BOOL) addMapObjects:(add(objects:)) NS_SWIFT_NAME

Adds a NSArray of NMAMapObject objects to the NMAMapView.

Parameters:

  • objects

    A NSArray of NMAMapObject objects to add

Returns:

YES if all map objects were added successfully, NO otherwise

-(void) addMapTileLayer:(add(mapTileLayer:)) NS_SWIFT_NAME

Adds a NMAMapTileLayer to the map view for rendering custom raster tiles.

Note:

Attempting to add a single NMAMapTileLayer instance to multiple NMAMapView instances is not supported and will result in undefined behavior.

Parameters:

-(void) disableMapGestures:(NSUInteger) gestures

Disable one or more NMAMapView gestures.

Note:

Pass NMAMapGestureTypeAll to disable all gestures.

Note:

Disabling a gesture type will also disable that type for the NMAMapView's gestureDelegate.

Parameters:

  • gestures

    A bit-mask combination of one or more NMAMapGestureType values.

-(void) enableMapGestures:(NSUInteger) gestures

Enable one or more NMAMapView gestures.

Note:

All gestures are enabled by default.

Note:

Pass NMAMapGestureTypeAll to enable all gestures.

Parameters:

  • gestures

    A bit-mask combination of one or more NMAMapGestureType values.

-(nullable NMAGeoCoordinates *) geoCoordinatesFromPoint:(geoCoordinates(from:)) NS_SWIFT_NAME

Converts a specified on-screen point to an equivalent NMAGeoCoordinates object.

Parameters:

  • point

    A point on the screen to convert

Returns:

The NMAGeoCoordinates, or nil if the conversaion failed

-(BOOL) isMapGestureEnabled:( NMAMapGestureType ) gesture

Queries whether or not a gesture type is enabled on the NMAMapView.

Parameters:

  • gesture

    The gesture type to query.

-(NSArray< NMAMapTileLayer * > *) mapTileLayers

Returns an array of NMAMapTileLayer instances that have been added to the map view.

Returns:

NSArray of NMAMapTileLayer instances.

-(NSArray< __kindof NMAMapObject * > *) objectsAtPoint:(objects(at:)) NS_SWIFT_NAME

Returns a NSArray of all NMAMapObject objects that are selected at a specified point on the screen.

Note:

Use isKindOfClass: to further determine NMAMapObject type instead of isMemberOfClass:.

Parameters:

  • point

    An on-screen CGPoint specified in logical coordinates

Returns:

The NSArray of selected NMAMapObject objects

-(double) pointDistanceFromGeoCoordinates:( NMAGeoCoordinates *) startCoordinates toGeoCoordinates:(pointDistance(from:to:)) NS_SWIFT_NAME

Calculates the point distance between two geo coordinates.

Note:

The calculation will fail if the coordinates are too far apart or too far from the current location of the map.

Parameters:

  • startCoordinates

    Starting NMAGeoCoordinates

  • endCoordinates

    Ending NMAGeoCoordinates

Returns:

The point distance between the NMAGeoCoordinates, or -CGFLOAT_MAX if either of the coordinates parameters is nil or the calculation cannot be performed.

-(CGPoint) pointFromGeoCoordinates:(point(from:)) NS_SWIFT_NAME

Converts a specified NMAGeoCoordinates object to its equivalent point in screen space.

Valid geo coordinates will produce a valid point, even if the coordinates are not on the screen, as long as the coordinates are not too far from the current map location. To check if coordinates are within the bounds of the screen, use the CGRectContainsPoint method after making the conversion.

Parameters:

  • coordinates

    A NMAGeoCoordinates object to convert

Returns:

The on-screen CGPoint, or CGPoint.x = CGPoint.y = -CGFLOAT_MAX if the NMAGeoCoordinates object is nil

-(BOOL) removeMapObject:(remove(_:)) NS_SWIFT_NAME

Removes an existing NMAMapObject from the NMAMapView.

Parameters:

  • object

    A NMAMapObject to remove

Returns:

YES if the map object was removed successfully, NO otherwise

-(BOOL) removeMapObjects:(remove(objects:)) NS_SWIFT_NAME

Removes a NSArray of NMAMapObject objects from the NMAMapView.

Parameters:

  • objects

    A NSArray of NMAMapObject objects to remove

Returns:

YES if all map objects were removed successfully, NO otherwise

-(void) removeMapTileLayer:(remove(mapTileLayer:)) NS_SWIFT_NAME

Removes a NMAMapTileLayer from the map view.

Parameters:

  • tileLayer

    NMAMapTileLayer instance to be removed from the map view. Does nothing if tileLayer has not been added to the map view yet.

-(void) setBoundingBox:( NMAGeoBoundingBox *) boundingBox insideRect:(CGRect) screenRect withAnimation:(set(boundingBox:inside:animation:)) NS_SWIFT_NAME

Transforms the map to fit an arbitrary geo bounding box with the bounds of a specific screen region with optional animation.

Passing the bounds of the map view to this method is equivalent to calling setBoundingBox:withAnimation:.

Parameters:

  • boundingBox

    A NMAGeoBoundingBox to display after the transformation

  • screenRect

    The region of the view inside which the bounding box will be located.

  • animationType

    The animation method used to perform the transformation.

-(void) setBoundingBox:( NMAGeoBoundingBox *) boundingBox withAnimation:(set(boundingBox:animation:)) NS_SWIFT_NAME

Sets the geo bounding box of the map view with optional animation.

After this method completes, the full extents of the specified geo bounding box will be visible in the map view. Depending on map orientation, this means that the boundingBox property may return a different value than the one passed to this method, because the map may be displaying some areas outside of the input bounding box.

Parameters:

  • boundingBox

    A NMAGeoBoundingBox to display after the transformation

  • animationType

    A NMAMapAnimation to illustrate the transformation

-(void) setGeoCenter:( NMAGeoCoordinates *) geoCenter withAnimation:(set(geoCenter:animation:)) NS_SWIFT_NAME

Sets the geoCenter of the map with optional animation.

Parameters:

  • geoCenter

    The NMAGeoCoordinates at which the map is centered.

  • animationType

    The animation method used to display the transformation.

-(void) setGeoCenter:( NMAGeoCoordinates *) geoCenter zoomLevel:(float) zoomLevel withAnimation:(set(geoCenter:zoomLevel:animation:)) NS_SWIFT_NAME

Simultaneously sets one or more map transformation properties with optional animation.

Any combination of new properties may be passed to this method. To leave a property unchanged, pass nil (geoCenter) or NMAMapViewPreserveValue (zoomLevel) for that property.

Parameters:

  • geoCenter

    The new geoCenter.

  • zoomLevel

    The new zoomLevel.

  • animationType

    The animation method used to display the transformation.

-(void) setGeoCoordinates:( NMAGeoCoordinates *) coordinates toPoint:(CGPoint) point withAnimation:(set(coordinates:to:animation:)) NS_SWIFT_NAME

Positions the NMAMapView so that the specified world location coincides with the specified screen location.

Note:

The screen point must be within the bounds of the map view.

Note:

Due to the curvature of the Earth, positioning may be inaccurate at low zoom levels.

Parameters:

  • coordinates

    The world location

  • point

    The screen location

  • animation

    The NMAMapAnimation type to use while moving the map

-(void) setGeoCoordinates:( NMAGeoCoordinates *) coordinates toPoint:(CGPoint) point withAnimation:( NMAMapAnimation ) animation zoomLevel:(set(coordinates:to:animation:zoomLevel:)) NS_SWIFT_NAME

Positions the NMAMapView so that the specified world location coincides with the specified screen location.

Note:

The screen point must be within the bounds of the map view.

Note:

Due to the curvature of the Earth, positioning may be inaccurate at low zoom levels.

Parameters:

  • coordinates

    The world location

  • point

    The screen location

  • animation

    The NMAMapAnimation type to use while moving the map

  • zoomLevel

    Desired zoom level of the newly-centered NMAMapView (pass NMAMapViewPreserveValue to keep the current zoom level)

-(void) setZoomLevel:(float) zoomLevel withAnimation:(set(zoomLevel:animation:)) NS_SWIFT_NAME

Sets the zoomLevel of the map with optional animation.

Parameters:

  • zoomLevel

    The zoomLevel at which to set the map.

  • animationType

    The animation method used to display the transformation.

-(BOOL) useDefaultDisplayLanguage

Set the map display language using the system default locale.

Note:

If it fails, the map display language is set to English.

Returns:

True if the language is accepted by the map, false otherwise.

-(BOOL) useDisplayLanguageFromLocale:(NSLocale *) locale

Set the map display language using the locale specifed.

Parameters:

  • locale

    The NSLocale as described in <a href=" https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSLocale_Class/ .

Returns:

True if the locale is accepted by the map, false otherwise.

-(BOOL) useSecondaryDisplayLanguageFromLocale:(NSLocale *_Nullable) locale

Set the secondary map display language using the locale specifed.

Setting a secondary display language will cause the language to be displayed below the primary language for some map labels (e.g. countries).

Parameters:

  • locale

    Pass nil if you want to remove the secondary map display language. The NSLocale as described in <a href=" https://developer.apple.com/library/mac/documentation/Cocoa/Reference/Foundation/Classes/NSLocale_Class/ .

Returns:

True if the locale is accepted by the map, false otherwise.

-(NSArray< __kindof NMAMapObject * > *) visibleObjectsAtPoint:(visibleObjects(at:)) NS_SWIFT_NAME

Returns a NSArray of all visible NMAMapObject objects that are selected at a specified point on the screen.

Parameters:

  • point

    An on-screen CGPoint specified in logical coordinates

Returns:

The NSArray of selected NMAMapObject objects

Class Method Details

+(void) shouldBeginRenderingAutomatically:(BOOL) enabled

Used to control the default NMAMapView rendering behaviour.

This class method is used to set whether or not instances of NMAMapView will begin rendering immediately upon creation. Any map view created after passing NO to this method must have its renderAllowed property set to YES to begin rendering.

You cannot use this account to purchase a commercial plan on Developer Portal, as it is already associated to plans with different payment methods.

To purchase a commercial plan on Developer Portal, please register for or sign in with a different HERE Account.

Something took longer than expected.

The project should be available soon under your projects page.

Sorry, our services are not available in this region.

Something seems to have gone wrong. Please try again later.

We've detected that your account is set to Australian Dollars (AUD).
Unfortunately, we do not offer checkouts in AUD anymore.
You can continue using your current plan as normal, but to subscribe to one of our new plans,
please register for a new HERE account or contact us for billing questions on selfservesupport@here.com.