MKTileOverlay Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MapKit.framework
Availability
Available in iOS 7.0 and later.
Companion guide
Declared in
MKTileOverlay.h

Overview

The MKTileOverlay class implements an overlay that is optimized for covering an area of the map using individual bitmap tiles. (In general, a map tile is a prerendered map image that covers a specific geographic area.) You can use tile overlay objects to represent your own tile-based content and to coordinate the display of that content in a map view. Your tiles can supplement the underlying map content or replace it completely. A tile overlay object coordinates the loading and management of the tiles while a corresponding MKTileOverlayRenderer object handles the actual drawing of the tiles on the map.

You can use a single tile overlay object to represent all of the tiles at one or more zoom levels of the map. The default tile overlay object uses a template string to build URLs so that it can locate the map tiles it needs. Each URL incorporates the x and y index of the map tile, the zoom level it is intended for, and the scale factor corresponding to the screen resolution on which to display the tile. The default class lets you specify map tiles whose indexes start in either the upper-left corner or lower-left corner of the map. If you use a different indexing scheme for your tiles, you can also subclass and override the URLForTilePath: or loadTileAtPath:result: methods to map between the requested tile and your custom indexing scheme.

Tasks

Initializing a Tile Overlay

Accessing the Tile Attributes

Customizing the Loading of Tiles

Properties

canReplaceMapContent

A Boolean value that indicates whether the tile content is fully opaque.

@property (nonatomic) BOOL canReplaceMapContent
Discussion

If the tile content you provide can cover the entire drawing area with opaque content, set this property to YES. Doing so serves as a hint to the map view that it does not need to draw any additional content underneath your tiles. Set this property to NO if your tiles contain any transparency.

The default value for this property is NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

geometryFlipped

A Boolean value that indicates the orientation of tile indexes along the y axis.

@property(getter=isGeometryFlipped) BOOL geometryFlipped
Discussion

When set to NO, tile indexes start in the upper-left corner of the map and proceed down and to the right. Thus, the tile at (0, 0)is in the upper-left corner of the map, the tile at (1, 0) is to its immediate right and the tile at (0, 1) is immediately below it. Setting this property to YES causes the map to start indexes at the lower-left corner of the map and proceed up and to the right.

The default value of this property is NO.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

maximumZ

The maximum zoom level supported by the tiles of this overlay object.

@property NSInteger maximumZ
Discussion

If you use different overlay objects to represent different tiles at different zoom levels, use this property to specify the maximum zoom level supported by this overlay’s tiles. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on. The map never tries to load tiles for a zoom level greater than the value specified by this property.

The default value of this property is 21. Setting the value of this property to a number greater than the default does not guarantee the use of those extra zoom levels.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
MKTileOverlay.h

minimumZ

The minimum zoom level supported by the tiles of this overlay object.

@property NSInteger minimumZ
Discussion

If you use different overlay objects to represent different tiles at different zoom levels, use this property to specify the minimum zoom level supported by this overlay’s tiles. At zoom level 0, tiles cover the entire world map; at zoom level 1, tiles cover 1/4 of the world; at zoom level 2, tiles cover 1/16 of the world, and so on. The map never tries to load tiles for a zoom level less than the value specified by this property.

The default value of this property is 0.

Availability
  • Available in iOS 7.0 and later.
See Also
Declared In
MKTileOverlay.h

tileSize

The size (in pixels) of your tile images.

@property CGSize tileSize
Discussion

On Retina displays, the images are rendered pixel for pixel and are not scaled. This means that if the tile size is 256 x 256 pixels and the scale factor is 2.0, the image would be rendered as if it were 128 x 128 points in size. This behavior causes the tile to appear smaller but preserves the original image data.

The default tile size is set to 256 x 256 pixels.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

URLTemplate

The template for generating tile image URLs. (read-only)

@property(readonly) NSString *URLTemplate
Discussion

You specify this string at initialization time.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

Instance Methods

initWithURLTemplate:

Initializes and returns a tile overlay object using the specified tile-access template.

- (id)initWithURLTemplate:(NSString *)URLTemplate
Parameters
URLTemplate

A string that can be used to build a URL to access your tile images. The string you specify can point to a local file or to an image on a remote server. To facilitate retrieving multiple tiles using the string, use the placeholder values {x}, {y}, {z}, and {scale} as stand-ins for the x and y tile indexes, the zoom level, and the resolution of the tile image. If this parameter is nil, you must provide custom implementations for the tile-loading methods of this class.

Return Value

An initialized tile overlay object.

Discussion

The default tile overlay object uses the template string you specify to request tiles. This template string should incorporate the {x}, {y}, {z}, and {scale} placeholder strings to facilitate the creation of a URL for requesting the appropriate tile. For example, if you have a server that vends tiles when you provide a URL of the form http://myserver/tile?x=0&y=0&z=0&scale=1.0, you would specify a template string of http://myserver/tile?x={x}&y={y}&z={z}&scale={scale}. The tile overlay object substitutes actual index values in for your template’s placeholders before requesting the actual tile.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

loadTileAtPath:result:

Loads the specified tile asynchronously.

- (void)loadTileAtPath:(MKTileOverlayPath)path result:(void (^)(NSData *tileData, NSError *error))result
Parameters
path

The path structure that identifies the specific tile you want. This structure incorporates the tile’s X-Y coordinate at a given zoom level and scale factor.

result

The completion block to call when the tile data is available. This block is executed on your app’s main thread and takes the following parameters:

  • The tileData parameter contains the raw data loaded from the corresponding image file. You can use this data to initialize an image object. If an error occurred, this parameter is nil.

  • The error parameter contains an error object if there was a problem loading the tile image. If no errors occurred, this parameter is nil.

Discussion

The default implementation of this method uses the URLForTilePath: method to retrieve the URL for the specified tile and then loads that tile into memory asynchronously using an NSURLConnection object. The specified tile may be located either on the local file system or on a remote server. Subclasses may override this method and implement their own custom tile-loading behavior.

When a tile overlay renderer (that is, an instance of MKTileOverlayRenderer) needs to display tiles, it uses this method to request the data for each tile.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

URLForTilePath:

Returns the URL to use to access the specified tile.

- (NSURL *)URLForTilePath:(MKTileOverlayPath)path
Parameters
path

The path structure that identifies the specific tile you want. This structure incorporates the tile’s X-Y coordinate at a given zoom level and scale factor.

Return Value

The URL to use to retrieve the tile.

Discussion

The default implementation of this method uses the template string you provided at initialization time to build a URL to the specified tile image. Subclasses can override this method and use a different scheme to provide URLs for tiles. Tiles can be located either on a local file system or on a remote server.

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h

Constants

MKTileOverlayPath

Use this structure to specify the index values for a single tile.

typedef struct {
   NSInteger x;
   NSInteger y;
   NSInteger z;
   CGFloat contentScaleFactor;
} MKTileOverlayPath;
Fields
x

The index of the tile along the x axis of the map.

y

The index of the tile along the y axis of the map.

z

The zoom level number for the tile. At level 0, the map displays the entire world; at level 1, the map displays 1/4 of the world; at level 2, the map displays 1/16 of the world, and so on.

contentScaleFactor

The screen scale factor for which the tile is intended. This value is typically either 1.0 (for standard resolution displays) or 2.0 (for Retina displays).

Availability
  • Available in iOS 7.0 and later.
Declared In
MKTileOverlay.h