MKOverlay Protocol Reference

Conforms to
Framework
/System/Library/Frameworks/MapKit.framework
Availability
Available in iOS 4.0 and later.
Companion guide
Declared in
MKOverlay.h
Related sample code

Overview

The MKOverlay protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can also describe polygons and other complex shapes.

You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. The Map Kit framework defines several concrete classes that conform to this protocol and define standard shapes.

Because overlays are also annotations, they have similar usage pattern to annotations. When added to a map view using the addOverlay: method, that view detects whenever the overlay’s defined region intersects the visible portion of the map. At that point, the map view asks its delegate to provide a special overlay view to draw the visual representation of the overlay. If you add an overlay to a map view as an annotation instead, it is treated as an annotation with a single point.

Tasks

Describing the Overlay Geometry

Determining Map Intersections

Optimizing Map Rendering

Properties

boundingMapRect

The projected rectangle that encompasses the overlay. (required) (read-only)

@property (nonatomic, readonly) MKMapRect boundingMapRect
Discussion

This property contains the smallest rectangle that completely encompasses the overlay. Implementers of this protocol must set this area when implementing their overlay class, and after setting it, you must not change it. The rectangle should be specified using projected coordinates—that is, coordinates obtained by projecting the globe onto a two-dimensional surface.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKOverlay.h

coordinate

The approximate center point of the overlay area. (required) (read-only)

@property (nonatomic, readonly) CLLocationCoordinate2D coordinate
Discussion

This point is typically set to the center point of the map’s bounding rectangle. It is used as the anchor point for any callouts displayed for the annotation.

Availability
  • Available in iOS 4.0 and later.
Related Sample Code
Declared In
MKOverlay.h

Instance Methods

canReplaceMapContent

Returns a Boolean indicating whether the overlay content replaces the underlying map content.

- (BOOL)canReplaceMapContent
Return Value

YES if the map view can skip the loading and drawing of the underlying map tiles or NO if the map tiles should still be drawn.

Discussion

The map view uses the return value of this method as a hint to determine whether it should load and render its tiles. If your overlay covers its designated region entirely with opaque content, and effectively replaces the content of underlying map tiles, implement this method and return YES. Doing so alleviates the need for the map to render its tiles.

If you do not implement this method, or if you return NO from it, the map view continues to load and render its tiles.

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

intersectsMapRect:

Returns a Boolean indicating whether the specified rectangle intersects the receiver’s shape.

- (BOOL)intersectsMapRect:(MKMapRect)mapRect
Parameters
mapRect

The rectangle to intersect with the receiver’s area.

Return Value

YES if any part of the map rectangle intersects the receiver’s shape or NO if it does not.

Discussion

You can implement this method to provide more specific bounds checking for an overlay. If you do not implement it, the bounding rectangle is used to detect intersections.

Availability
  • Available in iOS 4.0 and later.
Declared In
MKOverlay.h