HERE iOS SDK Developer's Guide

NMAMapTileLayer

Class Summary

class NMAMapTileLayer

Derived from: NSObject

A layer of custom raster tiles for display in an NMAMapView.

Include: NMAKit.framework/headers/NMAMapTileLayer.h

Inheritance Diagrams

Figure 1. Public inheritance diagram for NMAMapTileLayer

[For complete information, see the section Class Details]

Public Property Summary

Table 1. Public Properties
Public Properties

[readable, writable, assign] NMAGeoBoundingBox boundingBox

Specifies the NMAGeoBoundingBox within which tiles will be requested and rendered.

[readable, assign] BOOL  cacheEnabled

Specifies whether tile bitmaps will be cached to disk by the framework.

[readable, assign] NSString *  cacheIdentifier

Identifier used to associate disk cached tile data with a NMAMapTileLayer instance to prevent clashes in the cache folder.

[readable, writable, assign] NSUInteger  cacheSizeLimit

Specifies the maximum size the cache will consume on disk.

[readable, writable, assign] NSTimeInterval  cacheTimeToLive

Specifies the cache expiration time in seconds.

[readable, writable, weak] id< NMAMapTileLayerDataSource dataSource

[readable, writable, assign] BOOL  fadingEnabled

Specifies whether tiles are faded in when they are rendered for the first time.

[readable, writable, assign] BOOL  fallbackEnabled

Specifies whether tiles from lower zoom levels may be rendered at the current zoom level if a tile for the current zoom level is unavailable.

[readable, assign] BOOL  locked

Indicates if the tile layer is locked

[readable, writable, assign] NMAMapLayerType   mapLayerType

Specifies the map layer (NMAMapLayerType) at which the tile bitmaps will be rendered.

[readable, writable, assign] NMAPixelFormat   pixelFormat

Specifies the pixel format of the tile bitmaps.

[readable, writable, assign] NSUInteger  tileSize

Specifies the width and height (in pixels) of the tile bitmaps, this must be a power of 2 value.

[readable, writable, assign] BOOL  transparent

Specifies whether the tile bitmaps are transparent.

[readable, writable, assign] NSUInteger  zIndex

Specifies the Z-index (stacking order) for the bitmap tiles within the map layer specified by the mapLayerType property.

Instance Method Summary

Table 2. Instance Methods
Instance Method Summary

-(void) clearCache

Clear the file system cache identified by the cacheIdentifier property

-(void) hideAtZoomLevel:(int) zoomLevel

Hide the raster tiles at the specified zoom level.

-(void) hideFromZoomLevel:(int) fromLevel toZoomLevel:(int) toLevel

Hide the raster tiles at the specified zoom level range.

-(BOOL) isShownAtZoomLevel:(int) zoomLevel

Returns whether tiles are visisble at the specified zoom level.

-(void) setCacheEnabled:(BOOL) cacheEnabled withIdentifier:(NSString *) cacheIdentifier

/brief Enable/Disable caching of tile data to disk

-(void) showAtZoomLevel:(int) zoomLevel

Show the raster tiles at the specified zoom level.

-(void) showFromZoomLevel:(int) fromLevel toZoomLevel:(int) toLevel

Show the raster tiles at the specified zoom level range.

Class Details

A layer of custom raster tiles for display in an NMAMapView.

Raster tiles are supplied as bitmap data and can be supplied synchronously, asynchronously or simply by providing a URL from which to download the tiles from.

To use this class create an instance, configure the properties and call NMAMapView::addMapTileLayer.

Note:

IMPORTANT! The properties of this interface should not be modified after the instance has been added to an NMAMapView. See the NMAMapTileLayer::locked property.

Public Property Details

[readable, writable, assign] NMAGeoBoundingBoxboundingBox

Specifies the NMAGeoBoundingBox within which tiles will be requested and rendered.

Tiles falling fully outside the boundingBox will not be requested.

This property defaults to an unbounded value - i.e. tiles are rendered across the world.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, assign] BOOL cacheEnabled

Specifies whether tile bitmaps will be cached to disk by the framework.

File system caching is provided as a convenience. If caching is enabled tiles will not be re-requested via NMAMapTileLayerDelegate until they have expired.

This property defaults to NO. Caching is enabled by calling setCacheEnabled:withIdentifier:.

[readable, assign] NSString * cacheIdentifier

Identifier used to associate disk cached tile data with a NMAMapTileLayer instance to prevent clashes in the cache folder.

You must use unique cache identifiers to ensure there will be no filename clashes in the cache folder structure. It also allows you to easily identify the cache in the filesystem.

This property is set when you enable caching. See setCacheEnabled:withIdentifier:.

[readable, writable, assign] NSUInteger cacheSizeLimit

Specifies the maximum size the cache will consume on disk.

The framework may allow the cache size to grow an additional 5MB to the size specified in order to reduce disk access.

This property defaults to 0 which means the cache size is not limited.

Note:

This property has no effect if the cacheEnabled property is set to NO. Also, this property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] NSTimeInterval cacheTimeToLive

Specifies the cache expiration time in seconds.

Tile bitmaps will expire cacheTimeToLive seconds after they have been downloaded causing them to be re-requested via NMAMapTileLayerDataSource when the map needs to render them.

This property defaults to 0 which means the cached tiles never expire.

Note:

This property has no effect if the cacheEnabled property is set to NO. Negative values will be reset to 0.

[readable, writable, weak] id< NMAMapTileLayerDataSourcedataSource

Data source that provides tile bitmap data for the NMAMapTileLayer

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] BOOL fadingEnabled

Specifies whether tiles are faded in when they are rendered for the first time.

This property defaults to NO.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] BOOL fallbackEnabled

Specifies whether tiles from lower zoom levels may be rendered at the current zoom level if a tile for the current zoom level is unavailable.

This property defaults to YES.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, assign] BOOL locked

Indicates if the tile layer is locked.

The tile layer is locked when it is added to an NMAMapView instance. While the tile layer is locked attempts to set any properties will be ignored. The tile layer is unlocked when it is removed from an NMAMapView instance.

[readable, writable, assign] NMAMapLayerType  mapLayerType

Specifies the map layer (NMAMapLayerType) at which the tile bitmaps will be rendered.

This property defaults to NMAMapLayerTypeArea.

Attempts to set NMAMapLayerTypePointOfInterest or NMAMapLayerTypeTransitStop will be ignored.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] NMAPixelFormat  pixelFormat

Specifies the pixel format of the tile bitmaps.

If you are implementing mapTileLayer:urlForTileAtX:y:zoomLevel: then the framework will convert the png/jpg data downloadeded from the URL to the format specified.

If you are implementing requestTileAtX then the tile data you supply must be in the format specified.

This property defaults to NMAPixelFormatRGBA.

NMAPixelFormatUnknown is an invalid value for this property and will be ignored if you try to set it.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] NSUInteger tileSize

Specifies the width and height (in pixels) of the tile bitmaps, this must be a power of 2 value.

This property defaults to 256 - i.e. you are expected to supply tiles sized 256 x 256 pixels via the NMAMapTileLayerDataSource methods.

Changing the tile size effects the number of tiles you are expected to supply at each NMAMapView zoom level. For example, a tile size of 128 will result in 4 times as many tiles being requested for each NMAMapView zoom level than for a tile size of 256.

IMPORTANT: The size unit is pixels, not points, and MUST be a power of 2 value (32, 64, 128, 256, 512 etc) otherwise there will be problems regarding map rendering behaviour and performance. Tiles smaller than 128 will not be rendered at higher NMAMapView zoom levels and may degrade map rendering performance.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] BOOL transparent

Specifies whether the tile bitmaps are transparent.

If your tiles do not support transparency then setting this property to NO allows for rendering optimizations such as not loading data for lower layers covered by the raster tile.

This property defaults to NO. Only set this to YES if your tiles support transparency.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

[readable, writable, assign] NSUInteger zIndex

Specifies the Z-index (stacking order) for the bitmap tiles within the map layer specified by the mapLayerType property.

All objects within a map layer have a Z-index associated with them. Objects with the highest value are placed at the top of the stacking order. If two or more objects within a map layer have the same z-index value the their stacking order is undefind.

Z-index values range from NMAMapObjectMinimumZIndex to NMAMapObjectMaximumZIndex. The property will be clamped to this range if invalid values are specified.

This property defaults to NMAMapObjectMinimumZIndex.

Note:

This property cannot be set when the instance is locked. See NMAMapTileLayer::locked.

Instance Method Details

-(void) clearCache

Clear the file system cache identified by the cacheIdentifier property.

Note:

To guarantee the cache is cleared this method should be called after the NMAMapTileLayer instance has been removed from the NMAMapView

-(void) hideAtZoomLevel:(int) zoomLevel

Hide the raster tiles at the specified zoom level.

You can control the tile visibility for each zoom level independently. For example, tiles may be visible at levels 0, 5, 7 only. Tiles are shown at all zoom levels by default.

Note:

This method does nothing when the instance is locked. See NMAMapTileLayer::locked.

Parameters:

  • zoomLevel

    Zoom level at which to hide the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored

-(void) hideFromZoomLevel:(int) fromLevel toZoomLevel:(int) toLevel

Hide the raster tiles at the specified zoom level range.

You can control the tile visibility for each zoom level independently. This method allows you set the visibility for a range of zoom levels in one call. Tiles are shown at all zoom levels by default.

The method will do nothing if ANY parameters fall outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel or if fromLevel > toLevel.

Note:

This method does nothing when the instance is locked. See NMAMapTileLayer::locked.

Parameters:

  • fromLevel

    Lower zoom level index at which to hide the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored

  • toLevel

    Upper zoom level index at which to hide the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored

-(BOOL) isShownAtZoomLevel:(int) zoomLevel

Returns whether tiles are visisble at the specified zoom level.

You can control the tile visibility for each zoom level independently. This method allows you set the visibility for a range of zoom levels in one call. Tiles are shown at all zoom levels by default.

Parameters:

  • zoomLevel

    Zoom level. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will return NO.

Returns:

YES if tiles are shown at the specified zoom level, NO otherwise

-(void) setCacheEnabled:(BOOL) cacheEnabled withIdentifier:(NSString *) cacheIdentifier

/brief Enable/Disable caching of tile data to disk.

File system caching is provided as a convenience. If caching is enabled tiles will not be re-requested via NMAMapTileLayerDelegate until they have expired.

It's important to always use the same cache identifier for your tile data. Otherwise, multiple disassociated cache folders will be created in the file system. This wastes disk space, and you will not benefit from persistent disk caching across sessions.

Note:

Calling this method changes the values of the cacheEnabled and cacheIdentifier properties.

Parameters:

  • cacheEnabled

    YES to enable caching, NO to disable.

  • cacheIdentifier

    You must use a unique cache identifier to ensure there will be no filename clashes in the cache folder structure. Passing a nil or empty string will result in caching NOT being enabled. The identifier is set the first time you call this method and will not be changed by subsequent calls to this method for the lifetime of the instance. If the identifier you supply contains non alphanumeric characters they will be stripped from the identifier, with the exception of "_" and "-".

-(void) showAtZoomLevel:(int) zoomLevel

Show the raster tiles at the specified zoom level.

You can control the tile visibility for each zoom level independently. For example, tiles may be visible at levels 0, 5, 7 only. Tiles are shown at all zoom levels by default.

Note:

This method does nothing when the instance is locked. See NMAMapTileLayer::locked.

Parameters:

  • zoomLevel

    Zoom level at which to show the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored

-(void) showFromZoomLevel:(int) fromLevel toZoomLevel:(int) toLevel

Show the raster tiles at the specified zoom level range.

You can control the tile visibility for each zoom level independently. For example, tiles may be visible at levels 0, 5, 7 only. Tiles are shown at all zoom levels by default.

The method will do nothing if ANY parameters fall outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel or if fromLevel > toLevel.

Note:

This method does nothing when the instance is locked. See NMAMapTileLayer::locked.

Parameters:

  • fromLevel

    Lower zoom level index at which to show the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored

  • toLevel

    Upper zoom level index at which to show the tiles. Values outside the range NMAMapViewMinimumZoomLevel..NMAMapViewMaximumZoomLevel will be ignored