iOS Developer Library

Developer

MapKit Framework Reference MKOverlayView Class Reference

Options
Deployment Target:

On This Page
Language:

MKOverlayView

The MKOverlayView class defines the basic behavior associated with all overlay views. An overlay view provides the visual representation of an overlay object—that is, an object that conforms to the MKOverlay protocol. This class defines the drawing infrastructure used by the map view but does not do any actual drawing. Subclasses are expected to override the drawMapRect:zoomScale:inContext: method in order to draw the contents of the overlay view.

The Map Kit framework provides several concrete instances of overlay views. Specifically, it provides overlay views for each of the concrete overlay objects. You can use one of these existing overlay views or define your own subclass if you want to draw the overlay contents differently.

In iOS 7 and later, use the MKOverlayRenderer class to display overlays instead.

Subclassing Notes

You can subclass MKOverlayView to create overlays based on custom shapes and content. The only method subclasses are expected to override is the drawMapRect:zoomScale:inContext: method. However, if your class contains content that may not be ready for drawing right away, you should also override the canDrawMapRect:zoomScale: method and use it to report when your class is ready and able to draw.

The implementation of your drawMapRect:zoomScale:inContext: method must be safe to run from multiple threads simultaneously. To improve performance, the map view may tile overlays that are large enough and distribute the rendering of each tile to separate threads.

Import Statement


Swift

import MapKit

Objective-C

@import MapKit;

Availability


Available in iOS 4.0 and later.
  • initWithOverlay: - initWithOverlay: (iOS 7.0) Designated Initializer

    Initializes and returns the overlay view and associates it with the specified overlay object.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (instancetype)initWithOverlay:(id<MKOverlay>)overlay

    Parameters

    overlay

    The overlay object to use when drawing the overlay on the map. This object provides the data needed to draw the overlay’s shape. This object is retained by the overlay view.

    Return Value

    An initialized overlay object.

    Discussion

    Upon initialization, the frame of the overlay view is set to CGRectZero. The map view sets the size and position of the view at display time, and you should not change those values yourself.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • overlay overlay (iOS 7.0) Property

    The overlay object containing the data for drawing. (read-only)

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    @property(nonatomic, readonly) id< MKOverlay > overlay

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns the point in the overlay view that corresponds to specified point on the map.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (CGPoint)pointForMapPoint:(MKMapPoint)mapPoint

    Parameters

    mapPoint

    A point on the two-dimensional map projection. If you have a coordinate value (latitude and longitude), you can use the MKMapPointForCoordinate function to convert that coordinate to a map point.

    Return Value

    The point in the receiver’s coordinate system that corresponds to the map point.

    Special Considerations

    Because the bounds and frame rectangles of an overlay view do not change after the view has been created, you may call this method from multiple threads simultaneously. Therefore, you may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns the map point that corresponds to the specified point in the overlay view.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (MKMapPoint)mapPointForPoint:(CGPoint)point

    Parameters

    point

    The point in the view’s coordinate system that you want to convert.

    Return Value

    The point on the two-dimensional map projection corresponding to the specified point.

    Special Considerations

    Because the bounds and frame rectangles of an overlay view do not change after the view has been created, you may call this method from multiple threads simultaneously. Therefore, you may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns the rectangle in the overlay view that corresponds to the specified rectangle on the map.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (CGRect)rectForMapRect:(MKMapRect)mapRect

    Parameters

    mapRect

    A rectangle on the two-dimensional map projection.

    Return Value

    The rectangle specified in the receiver’s coordinate system.

    Special Considerations

    Because the bounds and frame rectangles of an overlay view do not change after the view has been created, you may call this method from multiple threads simultaneously. Therefore, you may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns the map rectangle that corresponds to the rectangle in the overlay view’s coordinate system.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (MKMapRect)mapRectForRect:(CGRect)rect

    Parameters

    rect

    The rectangle specified in the receiver’s coordinate system.

    Return Value

    The rectangle on the two-dimensional map project that corresponds to the specified view rectangle.

    Special Considerations

    Because the bounds and frame rectangles of an overlay view do not change after the view has been created, you may call this method from multiple threads simultaneously. Therefore, you may call this method safely from your view’s drawMapRect:zoomScale:inContext: method.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Returns a Boolean value indicating whether the overlay view is ready to draw its content.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (BOOL)canDrawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale

    Parameters

    mapRect

    The map rectangle that needs to be updated.

    zoomScale

    The current scale factor applied to the map.

    Return Value

    YEStrue if this view is ready to draw its contents or NOfalse if it is not.

    Discussion

    Overlay views can override this method in situations where they may depend on the availability of other information to draw their contents. For example, an overlay view showing traffic information might want to delay drawing until it has all of the traffic data it needs. In such a case, it can return NOfalse from this method to indicate that it is not ready.

    If you return NOfalse from this method, your application is responsible for calling the setNeedsDisplayInMapRect:zoomScale: method when the overlay view subsequently becomes ready to draw its contents.

    The default implementation of this method returns YEStrue.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Draws the contents of the overlay view.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (void)drawMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale inContext:(CGContextRef)context

    Parameters

    mapRect

    The map rectangle that needs to be updated. You can use this rectangle to limit drawing to only the portion of the view that changed.

    zoomScale

    The current scale factor applied to the map content. You can use this value for configuring the stroke width of lines or other attributes that might be affected by the scale of the view’s content.

    context

    The graphics context to use for drawing the view’s content.

    Discussion

    The default implementation of this method does nothing. Subclasses are expected to override this method (instead of the drawRect: method) and use it to draw the contents of the view.

    In your drawing code, you should specify the position of any rendered content relative to the map itself and not relative to the view’s bounds or frame. In other words, compute the position and size of any overlay content using map points and map rectangles, convert those values to CGPoint and CGRect types (using the methods of this class), and then use the converted points to build paths or specify the rendering location for items.

    You should also not make assumptions that the view’s frame matches the bounding rectangle of the overlay. The view’s frame is actually bigger than the bounding rectangle to allow you to draw lines for things like roads that might be located directly on the border of that rectangle. For some types of content, such as gradients, this also means that you might need to apply a clipping rectangle to context to ensure drawing is contained to the correct area.

    It is recommended that you use Core Graphics to draw any content for your overlays. If you choose to use UIKit classes and methods for drawing instead, you must push the specified graphics context onto the context stack (using the UIGraphicsPushContext function) before making any drawing calls. When you are done drawing, you must similarly pop the graphics context off the stack using the UIGraphicsPopContext. During drawing, you may draw content normally but should avoid manipulating views and other classes that are safe to use only from the application’s main thread.

    To improve drawing performance, the map view may tile overlays that become large enough and render the tiles from separate threads. Your implementation of this method must therefore be capable of safely running from multiple threads simultaneously. In addition, you should avoid drawing the entire contents of the overlay each time this method is called. Instead, your implementation should always take the mapRect parameter into consideration and avoid drawing content outside that rectangle. Failure to do so could lead to performance problems.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Invalidates the view in the given map rectangle at all zoom scales.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect

    Parameters

    mapRect

    The portion of the overlay that needs to be updated. This value is specified using a map rectangle and not view coordinates. You can convert from a view rectangle to a map rectangle using the mapRectForRect: method.

    Discussion

    Marking a rectangle as invalid causes that portion of the view to be redrawn during the next update cycle. This method invalidates the overlay regardless of the current zoom scale associated with the map.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.

  • Invalidates the view in the given map rectangle but only at the specified zoom scale.

    Deprecation Statement

    Use an MKOverlayRenderer object instead.

    Declaration

    Objective-C

    - (void)setNeedsDisplayInMapRect:(MKMapRect)mapRect zoomScale:(MKZoomScale)zoomScale

    Parameters

    mapRect

    The portion of the overlay that needs to be updated. This value is specified using a map rectangle and not view coordinates. You can convert from a view rectangle to a map rectangle using the mapRectForRect: method.

    zoomScale

    The zoom scale for which you want to invalidate the overlay.

    Discussion

    Marking a rectangle as invalid causes that portion of the view to be redrawn during the next update cycle. This method invalidates the overlay only when it is drawn at the specified zoom scale.

    Import Statement

    Objective-C

    @import MapKit;

    Availability

    Available in iOS 4.0 and later.

    Deprecated in iOS 7.0.