MGLMapView
@interface MGLMapView : UIView <MGLStylable>
An interactive, customizable map view with an interface similar to the one provided by Apple’s MapKit.
Using MGLMapView
, you can embed the map inside a view, allow users to manipulate it with standard gestures, animate the map between different viewpoints, and present information in the form of annotations and overlays.
The map view loads scalable vector tiles that conform to the Vector Tile Specification. It styles them with a style that conforms to the GL Style Specification. Such styles can be designed in MapTiler Customize and hosted on maptiler.com.
A collection of MapTiler-hosted styles is available through the MGLStyle
class. These basic styles use MapTiler Streets or MapTiler Satellite data sources, but you can specify a custom style that makes use of your own data.
MapTiler-hosted vector tiles and styles require an API access token, which you can obtain from the MapTiler account page. Access tokens associate requests to MapTiler’s vector tile and style APIs with your MapTiler account. They also deter other developers from using your styles without your permission.
Because MGLMapView
loads asynchronously, several delegate methods are available for receiving map-related updates. These methods can be used to ensure that certain operations have completed before taking any additional actions. Information on these methods is located in the MGLMapViewDelegate
protocol documentation.
Adding your own gesture recognizer to MGLMapView
will block the corresponding gesture recognizer built into MGLMapView
. To avoid conflicts, define which gesture takes precedence. For example, you can create your own UITapGestureRecognizer
that will be invoked only if the default MGLMapView
tap gesture fails:
let mapTapGestureRecognizer = UITapGestureRecognizer(target: self, action: #selector(myCustomFunction))
for recognizer in mapView.gestureRecognizers! where recognizer is UITapGestureRecognizer {
mapTapGestureRecognizer.require(toFail: recognizer)
}
mapView.addGestureRecognizer(mapTapGestureRecognizer)
Note
You are responsible for getting permission to use the map data and for ensuring that your use adheres to the relevant terms of use.
Creating Instances
-initWithFrame:
Initializes and returns a newly allocated map view with the specified frame and the default style.
Declaration
Objective-C
- (nonnull instancetype)initWithFrame:(CGRect)frame;
Swift
init(frame: CGRect)
Parameters
frame
The frame for the view, measured in points.
Return Value
An initialized map view.
-initWithFrame:styleURL:
Initializes and returns a newly allocated map view with the specified frame and style URL.
Declaration
Objective-C
- (nonnull instancetype)initWithFrame:(CGRect)frame
styleURL:(nullable NSURL *)styleURL;
Swift
init(frame: CGRect, styleURL: URL?)
Parameters
frame
The frame for the view, measured in points.
styleURL
URL of the map style to display. The URL may be a full HTTP or HTTPS URL, a GL style URL (https://api.maptiler.com/maps/streets-v2/style.json
), or a path to a local file relative to the application’s resource path. Specify nil
for the default style.
Return Value
An initialized map view.
Accessing the Delegate
delegate
The receiver’s delegate.
A map view sends messages to its delegate to notify it of changes to its contents or the viewpoint. The delegate also provides information about annotations displayed on the map, such as the styles to apply to individual annotations.
Declaration
Objective-C
@property (nonatomic, weak, readwrite, nullable) id<MGLMapViewDelegate> delegate;
Configuring the Map’s Appearance
style
The style currently displayed in the receiver.
Unlike the styleURL
property, this property is set to an object that allows you to manipulate every aspect of the style locally.
If the style is loading, this property is set to nil
until the style finishes loading. If the style has failed to load, this property is set to nil
. Because the style loads asynchronously, you should manipulate it in the -[MGLMapViewDelegate mapView:didFinishLoadingStyle:]
or -[MGLMapViewDelegate mapViewDidFinishLoadingMap:]
method. It is not possible to manipulate the style before it has finished loading.
Note
The default styles provided by MapTiler contain sources and layers with identifiers that will change over time. Applications that use APIs that manipulate a style’s sources and layers must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:]
, MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL
.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) MGLStyle *style;
Swift
var style: MGLStyle? { get }
styleURL
URL of the style currently displayed in the receiver.
The URL may be a full HTTP or HTTPS URL, a GL style URL (https://api.maptiler.com/maps/streets-v2/style.json
), or a path to a local file relative to the application’s resource path.
If you set this property to nil
, the receiver will use the default style and this property will automatically be set to that style’s URL.
If you want to modify the current style without replacing it outright, or if you want to introspect individual style attributes, use the style
property.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite, null_resettable)
NSURL *styleURL;
Swift
var styleURL: URL! { get set }
-reloadStyle:
Reloads the style.
You do not normally need to call this method. The map view automatically responds to changes in network connectivity by reloading the style. You may need to call this method if you change the access token after a style has loaded but before loading a style associated with a different MapTiler account.
This method does not bust the cache. Even if the style has recently changed on the server, calling this method does not necessarily ensure that the map view reflects those changes.
Declaration
Objective-C
- (void)reloadStyle:(nullable id)sender;
Swift
@IBAction func reloadStyle(_ sender: Any?)
automaticallyAdjustsContentInset
A boolean value that indicates if whether the map view should automatically adjust its content insets.
When this property is set to YES
the map automatically updates its contentInset
property to account for any area not covered by navigation bars, tab bars, toolbars, and other ancestors that obscure the map view.
Declaration
Objective-C
@property (atomic, assign, unsafe_unretained, readwrite)
BOOL automaticallyAdjustsContentInset;
Swift
var automaticallyAdjustsContentInset: Bool { get set }
showsScale
A Boolean value indicating whether the map may display scale information.
The scale bar may not be shown at all zoom levels. The scale bar becomes visible when the maximum distance visible on the map view is less than 400 miles (800 kilometers). The zoom level where this occurs depends on the latitude at the map view’s center coordinate, as well as the device screen width. At latitudes farther from the equator, the scale bar becomes visible at lower zoom levels.
The unit of measurement is determined by the user’s device locale.
The view controlled by this property is available at scaleBar
. The default value of this property is NO
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) BOOL showsScale;
Swift
var showsScale: Bool { get set }
scaleBar
A control indicating the scale of the map. The scale bar is positioned in the upper-left corner. Enable the scale bar via showsScale
.
Declaration
Objective-C
@property (nonatomic, readonly) UIView *_Nonnull scaleBar;
Swift
var scaleBar: UIView { get }
scaleBarPosition
The position of the scale bar. The default value is MGLOrnamentPositionTopLeft
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLOrnamentPosition scaleBarPosition;
Swift
var scaleBarPosition: MGLOrnamentPosition { get set }
scaleBarMargins
A CGPoint
indicating the position offset of the scale bar.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CGPoint scaleBarMargins;
Swift
var scaleBarMargins: CGPoint { get set }
compassView
A control indicating the map’s direction and allowing the user to manipulate the direction, positioned in the upper-right corner.
Declaration
Objective-C
@property (nonatomic, readonly) MGLCompassButton *_Nonnull compassView;
Swift
var compassView: MGLCompassButton { get }
compassViewPosition
The position of the compass view. The default value is MGLOrnamentPositionTopRight
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLOrnamentPosition compassViewPosition;
Swift
var compassViewPosition: MGLOrnamentPosition { get set }
compassViewMargins
A CGPoint
indicating the position offset of the compass.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CGPoint compassViewMargins;
Swift
var compassViewMargins: CGPoint { get set }
logoView
The MapTiler wordmark, positioned in the lower-left corner.
Note
The MapTiler terms of service, which govern the use of MapTiler-hosted vector tiles and styles, require most MapTiler customers to display the MapTiler attribution. If this applies to you, do not hide this view or change its contents.
Declaration
Objective-C
@property (nonatomic, readonly) UIImageView *_Nonnull logoView;
Swift
var logoView: UIImageView { get }
logoViewPosition
The position of the logo view. The default value is MGLOrnamentPositionBottomLeft
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLOrnamentPosition logoViewPosition;
Swift
var logoViewPosition: MGLOrnamentPosition { get set }
logoViewMargins
A CGPoint
indicating the position offset of the logo.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CGPoint logoViewMargins;
Swift
var logoViewMargins: CGPoint { get set }
attributionButton
A view showing legally required copyright notices, positioned at the bottom-right of the map view.
If you choose to reimplement this view, assign the -showAttribution:
method as the action for your view to present the default notices and settings.
Note
The MapTiler terms of service, which govern the use of MapTiler-hosted vector tiles and styles, require these copyright notices to accompany any map that features MapTiler-designed styles, OpenStreetMap (OSM) data, or other MapTiler data such as satellite or terrain data. If that applies to this map view, do not hide this view or remove any notices from it.
Declaration
Objective-C
@property (nonatomic, readonly) UIButton *_Nonnull attributionButton;
Swift
var attributionButton: UIButton { get }
attributionButtonPosition
The position of the attribution button. The default value is MGLOrnamentPositionBottomRight
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLOrnamentPosition attributionButtonPosition;
Swift
var attributionButtonPosition: MGLOrnamentPosition { get set }
attributionButtonMargins
A CGPoint
indicating the position offset of the attribution.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CGPoint attributionButtonMargins;
Swift
var attributionButtonMargins: CGPoint { get set }
-showAttribution:
Show the attribution action sheet.
This action is performed when the user taps on the attribution button provided by default via the attributionButton
property. If you implement a custom attribution button, you should add this action to the button.
Declaration
Objective-C
- (void)showAttribution:(nonnull id)sender;
Swift
@IBAction func showAttribution(_ sender: Any)
preferredFramesPerSecond
The preferred frame rate at which the map view is rendered.
The default value for this property is MGLMapViewPreferredFramesPerSecondDefault
, which will adaptively set the preferred frame rate based on the capability of the user’s device to maintain a smooth experience.
In addition to the provided MGLMapViewPreferredFramesPerSecond
options, this property can be set to arbitrary integer values.
See
CADisplayLink.preferredFramesPerSecond
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLMapViewPreferredFramesPerSecond preferredFramesPerSecond;
Swift
var preferredFramesPerSecond: MGLMapViewPreferredFramesPerSecond { get set }
prefetchesTiles
A Boolean value indicating whether the map should prefetch tiles.
When this property is set to YES
, the map view prefetches tiles designed for a low zoom level and displays them until receiving more detailed tiles for the current zoom level. The prefetched tiles typically contain simplified versions of each shape, improving the map view’s perceived performance.
The default value of this property is YES
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) BOOL prefetchesTiles;
Swift
var prefetchesTiles: Bool { get set }
Displaying the User’s Location
locationManager
The object that this map view uses to start and stop the delivery of location-related updates.
To receive the current user location, implement the -[MGLMapViewDelegate mapView:didUpdateUserLocation:]
and -[MGLMapViewDelegate mapView:didFailToLocateUserWithError:]
methods.
If setting this property to nil
or if no custom manager is provided this property is set to the default location manager.
MGLMapView
uses a default location manager. If you want to substitute your own location manager, you should do so by setting this property before setting showsUserLocation
to YES
. To restore the default location manager, set this property to nil
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite, null_resettable)
id<MGLLocationManager>
locationManager;
showsUserLocation
A Boolean value indicating whether the map may display the user location.
Setting this property to YES
causes the map view to use the Core Location framework to find the current location. As long as this property is YES
, the map view continues to track the user’s location and update it periodically.
This property does not indicate whether the user’s position is actually visible on the map, only whether the map view is allowed to display it. To determine whether the user’s position is visible, use the userLocationVisible
property. The default value of this property is NO
.
Your app must specify a value for NSLocationWhenInUseUsageDescription
or NSLocationAlwaysUsageDescription
in its Info.plist
to satisfy the requirements of the underlying Core Location framework when enabling this property.
If you implement a custom location manager, set the locationManager
before calling showsUserLocation
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
BOOL showsUserLocation;
Swift
var showsUserLocation: Bool { get set }
userLocationVisible
A Boolean value indicating whether the device’s current location is visible in the map view.
Use showsUserLocation
to control the visibility of the on-screen user location annotation.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readonly,
getter=isUserLocationVisible) BOOL userLocationVisible;
Swift
var isUserLocationVisible: Bool { get }
userLocation
Returns the annotation object indicating the user’s current location.
Declaration
Objective-C
@property (nonatomic, readonly, nullable) MGLUserLocation *userLocation;
Swift
var userLocation: MGLUserLocation? { get }
userTrackingMode
The mode used to track the user location. The default value is MGLUserTrackingModeNone
.
Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setUserTrackingMode:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLUserTrackingMode userTrackingMode;
Swift
var userTrackingMode: MGLUserTrackingMode { get set }
-setUserTrackingMode:animated:
Deprecated
Use -setUserTrackingMode:animated:completionHandler:
instead.
Deprecated. Sets the mode used to track the user location, with an optional transition.
To specify a completion handler to execute after the animation finishes, use the -setUserTrackingMode:animated:completionHandler:
method.
Declaration
Objective-C
- (void)setUserTrackingMode:(MGLUserTrackingMode)mode animated:(BOOL)animated;
Swift
func setUserTrackingMode(_ mode: MGLUserTrackingMode, animated: Bool)
Parameters
mode
The mode used to track the user location.
animated
If YES
, there is an animated transition from the current viewport to a viewport that results from the change to mode
. If NO
, the map view instantaneously changes to the new viewport. This parameter only affects the initial transition; subsequent changes to the user location or heading are always animated.
-setUserTrackingMode:animated:completionHandler:
Sets the mode used to track the user location, with an optional transition and completion handler.
Declaration
Objective-C
- (void)setUserTrackingMode:(MGLUserTrackingMode)mode
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Swift
func setUserTrackingMode(_ mode: MGLUserTrackingMode, animated: Bool, completionHandler completion: (() -> Void)? = nil)
Parameters
mode
The mode used to track the user location.
animated
If YES
, there is an animated transition from the current viewport to a viewport that results from the change to mode
. If NO
, the map view instantaneously changes to the new viewport. This parameter only affects the initial transition; subsequent changes to the user location or heading are always animated.
completion
The block executed after the animation finishes.
userLocationVerticalAlignment
Deprecated
Use -[MGLMapViewDelegate mapViewUserLocationAnchorPoint:]
instead.
The vertical alignment of the user location annotation within the receiver. The default value is MGLAnnotationVerticalAlignmentCenter
.
Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setUserLocationVerticalAlignment:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLAnnotationVerticalAlignment userLocationVerticalAlignment;
Swift
var userLocationVerticalAlignment: MGLAnnotationVerticalAlignment { get set }
-setUserLocationVerticalAlignment:animated:
Deprecated
Use -[MGLMapViewDelegate mapViewUserLocationAnchorPoint:]
instead.
Sets the vertical alignment of the user location annotation within the receiver, with an optional transition.
Declaration
Objective-C
- (void)setUserLocationVerticalAlignment:
(MGLAnnotationVerticalAlignment)alignment
animated:(BOOL)animated;
Swift
func setUserLocationVerticalAlignment(_ alignment: MGLAnnotationVerticalAlignment, animated: Bool)
Parameters
alignment
The vertical alignment of the user location annotation.
animated
If YES
, the user location annotation animates to its new position within the map view. If NO
, the user location annotation instantaneously moves to its new position.
-updateUserLocationAnnotationView
Updates the position of the user location annotation view by retreiving the user’s last known location.
Declaration
Objective-C
- (void)updateUserLocationAnnotationView;
Swift
func updateUserLocationAnnotationView()
-updateUserLocationAnnotationViewAnimatedWithDuration:
Updates the position of the user location annotation view by retreiving the user’s last known location with a specified duration.
Declaration
Objective-C
- (void)updateUserLocationAnnotationViewAnimatedWithDuration:
(NSTimeInterval)duration;
Swift
func updateUserLocationAnnotationViewAnimated(withDuration duration: TimeInterval)
Parameters
duration
The duration to animate the change in seconds.
showsUserHeadingIndicator
A Boolean value indicating whether the user location annotation may display a permanent heading indicator.
Setting this property to YES
causes the default user location annotation to appear and always show an arrow-shaped heading indicator, if heading is available. This property does not rotate the map; for that, see MGLUserTrackingModeFollowWithHeading
.
This property has no effect when userTrackingMode
is MGLUserTrackingModeFollowWithHeading
or MGLUserTrackingModeFollowWithCourse
.
The default value of this property is NO
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
BOOL showsUserHeadingIndicator;
Swift
var showsUserHeadingIndicator: Bool { get set }
displayHeadingCalibration
Whether the map view should display a heading calibration alert when necessary. The default value is YES
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
BOOL displayHeadingCalibration;
Swift
var displayHeadingCalibration: Bool { get set }
targetCoordinate
The geographic coordinate that is the subject of observation as the user location is being tracked.
By default, this property is set to an invalid coordinate, indicating that there is no target. In course tracking mode, the target forms one of two foci in the viewport, the other being the user location annotation. Typically, this property is set to a destination or waypoint in a real-time navigation scene. As the user annotation moves toward the target, the map automatically zooms in to fit both foci optimally within the viewport.
This property has no effect if the userTrackingMode
property is set to a value other than MGLUserTrackingModeFollowWithCourse
.
Changing the value of this property updates the map view with an animated transition. If you don’t want to animate the change, use the -setTargetCoordinate:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CLLocationCoordinate2D targetCoordinate;
Swift
var targetCoordinate: CLLocationCoordinate2D { get set }
-setTargetCoordinate:animated:
Deprecated
Use -setTargetCoordinate:animated:completionHandler:
instead.
Deprecated. Sets the geographic coordinate that is the subject of observation as the user location is being tracked, with an optional transition animation.
By default, the target coordinate is set to an invalid coordinate, indicating that there is no target. In course tracking mode, the target forms one of two foci in the viewport, the other being the user location annotation. Typically, the target is set to a destination or waypoint in a real-time navigation scene. As the user annotation moves toward the target, the map automatically zooms in to fit both foci optimally within the viewport.
This method has no effect if the userTrackingMode
property is set to a value other than MGLUserTrackingModeFollowWithCourse
.
To specify a completion handler to execute after the animation finishes, use the -setTargetCoordinate:animated:completionHandler:
method.
Declaration
Objective-C
- (void)setTargetCoordinate:(CLLocationCoordinate2D)targetCoordinate
animated:(BOOL)animated;
Swift
func setTargetCoordinate(_ targetCoordinate: CLLocationCoordinate2D, animated: Bool)
Parameters
targetCoordinate
The target coordinate to fit within the viewport.
animated
If YES
, the map animates to fit the target within the map view. If NO
, the map fits the target instantaneously.
-setTargetCoordinate:animated:completionHandler:
Sets the geographic coordinate that is the subject of observation as the user location is being tracked, with an optional transition animation and completion handler.
By default, the target coordinate is set to an invalid coordinate, indicating that there is no target. In course tracking mode, the target forms one of two foci in the viewport, the other being the user location annotation. Typically, the target is set to a destination or waypoint in a real-time navigation scene. As the user annotation moves toward the target, the map automatically zooms in to fit both foci optimally within the viewport.
This method has no effect if the userTrackingMode
property is set to a value other than MGLUserTrackingModeFollowWithCourse
.
Declaration
Objective-C
- (void)setTargetCoordinate:(CLLocationCoordinate2D)targetCoordinate
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Swift
func setTargetCoordinate(_ targetCoordinate: CLLocationCoordinate2D, animated: Bool, completionHandler completion: (() -> Void)? = nil)
Parameters
targetCoordinate
The target coordinate to fit within the viewport.
animated
If YES
, the map animates to fit the target within the map view. If NO
, the map fits the target instantaneously.
completion
The block executed after the animation finishes.
Configuring How the User Interacts with the Map
zoomEnabled
A Boolean value that determines whether the user may zoom the map in and out, changing the zoom level.
When this property is set to YES
, the default, the user may zoom the map in and out by pinching two fingers or by double tapping, holding, and moving the finger up and down.
This property controls only user interactions with the map. If you set the value of this property to NO
, you may still change the map zoom programmatically.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite, getter=isZoomEnabled)
BOOL zoomEnabled;
Swift
var isZoomEnabled: Bool { get set }
scrollEnabled
A Boolean value that determines whether the user may scroll around the map, changing the center coordinate.
When this property is set to YES
, the default, the user may scroll the map by dragging or swiping with one finger.
This property controls only user interactions with the map. If you set the value of this property to NO
, you may still change the map location programmatically.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite,
getter=isScrollEnabled) BOOL scrollEnabled;
Swift
var isScrollEnabled: Bool { get set }
panScrollingMode
The scrolling mode the user is allowed to use to interact with the map.
MGLPanScrollingModeHorizontal
only allows the user to scroll horizontally on the map, restricting a user’s ability to scroll vertically. MGLPanScrollingModeVertical
only allows the user to scroll vertically on the map, restricting a user’s ability to scroll horizontally. MGLPanScrollingModeDefault
allows the user to scroll both horizontally and vertically on the map.
By default, this property is set to MGLPanScrollingModeDefault
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLPanScrollingMode panScrollingMode;
Swift
var panScrollingMode: MGLPanScrollingMode { get set }
rotateEnabled
A Boolean value that determines whether the user may rotate the map, changing the direction.
When this property is set to YES
, the default, the user may rotate the map by moving two fingers in a circular motion.
This property controls only user interactions with the map. If you set the value of this property to NO
, you may still rotate the map programmatically.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite,
getter=isRotateEnabled) BOOL rotateEnabled;
Swift
var isRotateEnabled: Bool { get set }
pitchEnabled
A Boolean value that determines whether the user may change the pitch (tilt) of the map.
When this property is set to YES
, the default, the user may tilt the map by vertically dragging two fingers.
This property controls only user interactions with the map. If you set the value of this property to NO
, you may still change the pitch of the map programmatically.
The default value of this property is YES
.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite,
getter=isPitchEnabled) BOOL pitchEnabled;
Swift
var isPitchEnabled: Bool { get set }
hapticFeedbackEnabled
A Boolean value that determines whether the user will receive haptic feedback for certain interactions with the map.
When this property is set to YES
, the default, a UIImpactFeedbackStyleLight
haptic feedback event be played when the user rotates the map to due north (0°).
This feature requires a device that supports haptic feedback, running iOS 10 or newer.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite,
getter=isHapticFeedbackEnabled) BOOL hapticFeedbackEnabled;
Swift
var isHapticFeedbackEnabled: Bool { get set }
decelerationRate
A floating-point value that determines the rate of deceleration after the user lifts their finger.
Your application can use the MGLMapViewDecelerationRateNormal
and MGLMapViewDecelerationRateFast
constants as reference points for reasonable deceleration rates. MGLMapViewDecelerationRateImmediate
can be used to disable deceleration entirely.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CGFloat decelerationRate;
Swift
var decelerationRate: CGFloat { get set }
Manipulating the Viewpoint
centerCoordinate
The geographic coordinate at the center of the map view.
Changing the value of this property centers the map on the new coordinate without changing the current zoom level.
Changing the value of this property updates the map view immediately. If you want to animate the change, use the -setCenterCoordinate:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CLLocationCoordinate2D centerCoordinate;
Swift
var centerCoordinate: CLLocationCoordinate2D { get set }
-setCenterCoordinate:animated:
Changes the center coordinate of the map and optionally animates the change.
Changing the center coordinate centers the map on the new coordinate without changing the current zoom level. For animated changes, wait until the map view has finished loading before calling this method.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
.
Declaration
Objective-C
- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate
animated:(BOOL)animated;
Swift
func setCenter(_ coordinate: CLLocationCoordinate2D, animated: Bool)
Parameters
coordinate
The new center coordinate for the map.
animated
Specify YES
if you want the map view to scroll to the new location or NO
if you want the map to display the new location immediately.
-setCenterCoordinate:zoomLevel:animated:
Changes the center coordinate and zoom level of the map and optionally animates the change. For animated changes, wait until the map view has finished loading before calling this method.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
.
Declaration
Objective-C
- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
zoomLevel:(double)zoomLevel
animated:(BOOL)animated;
Swift
func setCenter(_ centerCoordinate: CLLocationCoordinate2D, zoomLevel: Double, animated: Bool)
Parameters
centerCoordinate
The new center coordinate for the map.
zoomLevel
The new zoom level for the map.
animated
Specify YES
if you want the map view to animate scrolling and zooming to the new location or NO
if you want the map to display the new location immediately.
-setCenterCoordinate:zoomLevel:direction:animated:
Changes the center coordinate, zoom level, and direction of the map and optionally animates the change. For animated changes, wait until the map view has finished loading before calling this method.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
.
Declaration
Objective-C
- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
zoomLevel:(double)zoomLevel
direction:(CLLocationDirection)direction
animated:(BOOL)animated;
Swift
func setCenter(_ centerCoordinate: CLLocationCoordinate2D, zoomLevel: Double, direction: CLLocationDirection, animated: Bool)
Parameters
centerCoordinate
The new center coordinate for the map.
zoomLevel
The new zoom level for the map.
direction
The new direction for the map, measured in degrees relative to true north. A negative value leaves the map’s direction unchanged.
animated
Specify YES
if you want the map view to animate scrolling, zooming, and rotating to the new location or NO
if you want the map to display the new location immediately.
-setCenterCoordinate:zoomLevel:direction:animated:completionHandler:
Changes the center coordinate, zoom level, and direction of the map, calling a completion handler at the end of an optional animation. For animated changes, wait until the map view has finished loading before calling this method.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
.
Declaration
Objective-C
- (void)setCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate
zoomLevel:(double)zoomLevel
direction:(CLLocationDirection)direction
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Swift
func setCenter(_ centerCoordinate: CLLocationCoordinate2D, zoomLevel: Double, direction: CLLocationDirection, animated: Bool, completionHandler completion: (() -> Void)? = nil)
Parameters
centerCoordinate
The new center coordinate for the map.
zoomLevel
The new zoom level for the map.
direction
The new direction for the map, measured in degrees relative to true north. A negative value leaves the map’s direction unchanged.
animated
Specify YES
if you want the map view to animate scrolling, zooming, and rotating to the new location or NO
if you want the map to display the new location immediately.
completion
The block executed after the animation finishes.
zoomLevel
The zoom level of the receiver.
In addition to affecting the visual size and detail of features on the map, the zoom level affects the size of the vector tiles that are loaded. At zoom level 0, each tile covers the entire world map; at zoom level 1, it covers ¼ of the world; at zoom level 2, 1⁄16 of the world, and so on.
Changing the value of this property updates the map view immediately. If you want to animate the change, use the -setZoomLevel:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) double zoomLevel;
Swift
var zoomLevel: Double { get set }
-setZoomLevel:animated:
Changes the zoom level of the map and optionally animates the change.
Changing the zoom level scales the map without changing the current center coordinate.
Declaration
Objective-C
- (void)setZoomLevel:(double)zoomLevel animated:(BOOL)animated;
Swift
func setZoomLevel(_ zoomLevel: Double, animated: Bool)
Parameters
zoomLevel
The new zoom level for the map.
animated
Specify YES
if you want the map view to animate the change to the new zoom level or NO
if you want the map to display the new zoom level immediately.
minimumZoomLevel
The minimum zoom level at which the map can be shown.
Depending on the map view’s aspect ratio, the map view may be prevented from reaching the minimum zoom level, in order to keep the map from repeating within the current viewport.
If the value of this property is greater than that of the maximumZoomLevel property, the behavior is undefined.
The default minimumZoomLevel is 0.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
double minimumZoomLevel;
Swift
var minimumZoomLevel: Double { get set }
maximumZoomLevel
The maximum zoom level the map can be shown at.
If the value of this property is smaller than that of the minimumZoomLevel property, the behavior is undefined.
The default maximumZoomLevel is 22. The upper bound for this property is 25.5.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
double maximumZoomLevel;
Swift
var maximumZoomLevel: Double { get set }
direction
The heading of the map, measured in degrees clockwise from true north.
The value 0
means that the top edge of the map view corresponds to true north. The value 90
means the top of the map is pointing due east. The value 180
means the top of the map points due south, and so on.
Changing the value of this property updates the map view immediately. If you want to animate the change, use the -setDirection:animated:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
CLLocationDirection direction;
Swift
var direction: CLLocationDirection { get set }
-setDirection:animated:
Changes the heading of the map and optionally animates the change.
Changing the heading rotates the map without changing the current center coordinate or zoom level.
Declaration
Objective-C
- (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated;
Swift
func setDirection(_ direction: CLLocationDirection, animated: Bool)
Parameters
direction
The heading of the map, measured in degrees clockwise from true north.
animated
Specify YES
if you want the map view to animate the change to the new heading or NO
if you want the map to display the new heading immediately.
minimumPitch
The minimum pitch of the map’s camera toward the horizon measured in degrees.
If the value of this property is greater than that of the maximumPitch
property, the behavior is undefined. The pitch may not be less than 0 regardless of this property.
The default value of this property is 0 degrees, allowing the map to appear two-dimensional.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) CGFloat minimumPitch;
Swift
var minimumPitch: CGFloat { get set }
maximumPitch
The maximum pitch of the map’s camera toward the horizon measured in degrees.
If the value of this property is smaller than that of the minimumPitch
property, the behavior is undefined. The pitch may not exceed 60 degrees regardless of this property.
The default value of this property is 60 degrees.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite) CGFloat maximumPitch;
Swift
var maximumPitch: CGFloat { get set }
-resetNorth
Resets the map rotation to a northern heading — a direction
of 0
degrees.
Declaration
Objective-C
- (void)resetNorth;
Swift
@IBAction func resetNorth()
-resetPosition
Resets the map to the current style’s default viewport.
If the style doesn’t specify a default viewport, the map resets to a minimum zoom level, a center coordinate of (0, 0), and a northern heading.
Declaration
Objective-C
- (void)resetPosition;
Swift
@IBAction func resetPosition()
visibleCoordinateBounds
The coordinate bounds visible in the receiver’s viewport.
Changing the value of this property updates the receiver immediately. If you want to animate the change, call -setVisibleCoordinateBounds:animated:
instead.
If a longitude is less than −180 degrees or greater than 180 degrees, the visible bounds straddles the antimeridian or international date line. For example, if both Tokyo and San Francisco are visible, the visible bounds might extend from (35.68476, −220.24257) to (37.78428, −122.41310).
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLCoordinateBounds visibleCoordinateBounds;
Swift
var visibleCoordinateBounds: MGLCoordinateBounds { get set }
-setVisibleCoordinateBounds:animated:
Changes the receiver’s viewport to fit the given coordinate bounds, optionally animating the change.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible bounds to extend from (35.68476, −220.24257) to (37.78428, −122.41310).
Declaration
Objective-C
- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds
animated:(BOOL)animated;
Swift
func setVisibleCoordinateBounds(_ bounds: MGLCoordinateBounds, animated: Bool)
Parameters
bounds
The bounds that the viewport will show in its entirety.
animated
Specify YES
to animate the change by smoothly scrolling and zooming or NO
to immediately display the given bounds.
-setVisibleCoordinateBounds:edgePadding:animated:
Deprecated
Use -setVisibleCoordinateBounds:edgePadding:animated:completionHandler:
instead.
Deprecated. Changes the receiver’s viewport to fit the given coordinate bounds with some additional padding on each side.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible bounds to extend from (35.68476, −220.24257) to (37.78428, −122.41310).
To specify a completion handler to execute after the animation finishes, use the -setVisibleCoordinateBounds:edgePadding:animated:completionHandler:
method.
Declaration
Objective-C
- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds
edgePadding:(UIEdgeInsets)insets
animated:(BOOL)animated;
Swift
func setVisibleCoordinateBounds(_ bounds: MGLCoordinateBounds, edgePadding insets: UIEdgeInsets, animated: Bool)
Parameters
bounds
The bounds that the viewport will show in its entirety.
insets
The minimum padding (in screen points) that will be visible around the given coordinate bounds.
animated
Specify YES
to animate the change by smoothly scrolling and zooming or NO
to immediately display the given bounds.
-setVisibleCoordinateBounds:edgePadding:animated:completionHandler:
Changes the receiver’s viewport to fit the given coordinate bounds with some additional padding on each side, optionally calling a completion handler.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible bounds to extend from (35.68476, −220.24257) to (37.78428, −122.41310).
Declaration
Objective-C
- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds
edgePadding:(UIEdgeInsets)insets
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Swift
func setVisibleCoordinateBounds(_ bounds: MGLCoordinateBounds, edgePadding insets: UIEdgeInsets, animated: Bool, completionHandler completion: (() -> Void)? = nil)
Parameters
bounds
The bounds that the viewport will show in its entirety.
insets
The minimum padding (in screen points) that will be visible around the given coordinate bounds.
animated
Specify YES
to animate the change by smoothly scrolling and zooming or NO
to immediately display the given bounds.
completion
The block executed after the animation finishes.
-setVisibleCoordinates:count:edgePadding:animated:
Changes the receiver’s viewport to fit all of the given coordinates with some additional padding on each side.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible coordinates to (35.68476, −220.24257) and (37.78428, −122.41310).
Declaration
Objective-C
- (void)setVisibleCoordinates:
(nonnull const CLLocationCoordinate2D *)coordinates
count:(NSUInteger)count
edgePadding:(UIEdgeInsets)insets
animated:(BOOL)animated;
Swift
func setVisibleCoordinates(_ coordinates: UnsafePointer<CLLocationCoordinate2D>, count: UInt, edgePadding insets: UIEdgeInsets, animated: Bool)
Parameters
coordinates
The coordinates that the viewport will show.
count
The number of coordinates. This number must not be greater than the number of elements in coordinates
.
insets
The minimum padding (in screen points) that will be visible around the given coordinate bounds.
animated
Specify YES
to animate the change by smoothly scrolling and zooming or NO
to immediately display the given bounds.
-setVisibleCoordinates:count:edgePadding:direction:duration:animationTimingFunction:completionHandler:
Changes the receiver’s viewport to fit all of the given coordinates with some additional padding on each side, optionally calling a completion handler.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible coordinates to (35.68476, −220.24257) and (37.78428, −122.41310).
Declaration
Objective-C
- (void)setVisibleCoordinates:
(nonnull const CLLocationCoordinate2D *)coordinates
count:(NSUInteger)count
edgePadding:(UIEdgeInsets)insets
direction:(CLLocationDirection)direction
duration:(NSTimeInterval)duration
animationTimingFunction:(nullable CAMediaTimingFunction *)function
completionHandler:(nullable void (^)(void))completion;
Swift
func setVisibleCoordinates(_ coordinates: UnsafePointer<CLLocationCoordinate2D>, count: UInt, edgePadding insets: UIEdgeInsets, direction: CLLocationDirection, duration: TimeInterval, animationTimingFunction function: CAMediaTimingFunction?, completionHandler completion: (() -> Void)? = nil)
Parameters
coordinates
The coordinates that the viewport will show.
count
The number of coordinates. This number must not be greater than the number of elements in coordinates
.
insets
The minimum padding (in screen points) that will be visible around the given coordinate bounds.
direction
The direction to rotate the map to, measured in degrees relative to true north. A negative value leaves the map’s direction unchanged.
duration
The duration to animate the change in seconds.
function
The timing function to animate the change.
completion
The block executed after the animation finishes.
-showAnnotations:animated:
Sets the visible region so that the map displays the specified annotations.
Calling this method updates the value in the visibleCoordinateBounds
property and potentially other properties to reflect the new map region. A small amount of padding is reserved around the edges of the map view. To specify a different amount of padding, use the -showAnnotations:edgePadding:animated:
method.
Declaration
Objective-C
- (void)showAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations
animated:(BOOL)animated;
Parameters
annotations
The annotations that you want to be visible in the map.
animated
YES
if you want the map region change to be animated, or NO
if you want the map to display the new region immediately without animations.
-showAnnotations:edgePadding:animated:
Deprecated
Use -showAnnotations:edgePadding:animated:completionHandler:
instead.
Deprecated. Sets the visible region so that the map displays the specified annotations with the specified amount of padding on each side.
Calling this method updates the value in the visibleCoordinateBounds
property and potentially other properties to reflect the new map region.
To specify a completion handler to execute after the animation finishes, use the -showAnnotations:edgePadding:animated:completionHandler:
method.
Declaration
Objective-C
- (void)showAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations
edgePadding:(UIEdgeInsets)insets
animated:(BOOL)animated;
Parameters
annotations
The annotations that you want to be visible in the map.
insets
The minimum padding (in screen points) around the edges of the map view to keep clear of annotations.
animated
YES
if you want the map region change to be animated, or NO
if you want the map to display the new region immediately without animations.
-showAnnotations:edgePadding:animated:completionHandler:
Sets the visible region so that the map displays the specified annotations with the specified amount of padding on each side and an optional completion handler.
Calling this method updates the value in the visibleCoordinateBounds
property and potentially other properties to reflect the new map region.
Declaration
Objective-C
- (void)showAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations
edgePadding:(UIEdgeInsets)insets
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Parameters
annotations
The annotations that you want to be visible in the map.
insets
The minimum padding (in screen points) around the edges of the map view to keep clear of annotations.
animated
YES
if you want the map region change to be animated, or NO
if you want the map to display the new region immediately without animations.
completion
The block executed after the animation finishes.
camera
A camera representing the current viewpoint of the map.
Declaration
Objective-C
@property (nonatomic, copy, readwrite) MGLMapCamera *_Nonnull camera;
Swift
@NSCopying var camera: MGLMapCamera { get set }
-setCamera:animated:
Moves the viewpoint to a different location with respect to the map with an optional transition animation. For animated changes, wait until the map view has finished loading before calling this method.
Declaration
Objective-C
- (void)setCamera:(nonnull MGLMapCamera *)camera animated:(BOOL)animated;
Swift
func setCamera(_ camera: MGLMapCamera, animated: Bool)
Parameters
camera
The new viewpoint.
animated
Specify YES
if you want the map view to animate the change to the new viewpoint or NO
if you want the map to display the new viewpoint immediately.
-setCamera:withDuration:animationTimingFunction:
Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function. For animated changes, wait until the map view has finished loading before calling this method.
Declaration
Objective-C
- (void)setCamera:(nonnull MGLMapCamera *)camera
withDuration:(NSTimeInterval)duration
animationTimingFunction:(nullable CAMediaTimingFunction *)function;
Swift
func setCamera(_ camera: MGLMapCamera, withDuration duration: TimeInterval, animationTimingFunction function: CAMediaTimingFunction?)
Parameters
camera
The new viewpoint.
duration
The amount of time, measured in seconds, that the transition animation should take. Specify 0
to jump to the new viewpoint instantaneously.
function
A timing function used for the animation. Set this parameter to nil
for a transition that matches most system animations. If the duration is 0
, this parameter is ignored.
-setCamera:withDuration:animationTimingFunction:completionHandler:
Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function. For animated changes, wait until the map view has finished loading before calling this method.
Declaration
Objective-C
- (void)setCamera:(nonnull MGLMapCamera *)camera
withDuration:(NSTimeInterval)duration
animationTimingFunction:(nullable CAMediaTimingFunction *)function
completionHandler:(nullable void (^)(void))completion;
Swift
func setCamera(_ camera: MGLMapCamera, withDuration duration: TimeInterval, animationTimingFunction function: CAMediaTimingFunction?, completionHandler completion: (() -> Void)? = nil)
Parameters
camera
The new viewpoint.
duration
The amount of time, measured in seconds, that the transition animation should take. Specify 0
to jump to the new viewpoint instantaneously.
function
A timing function used for the animation. Set this parameter to nil
for a transition that matches most system animations. If the duration is 0
, this parameter is ignored.
completion
The block to execute after the animation finishes.
-setCamera:withDuration:animationTimingFunction:edgePadding:completionHandler:
Moves the viewpoint to a different location with respect to the map with an optional transition duration and timing function, and optionally some additional padding on each side. For animated changes, wait until the map view has finished loading before calling this method.
Declaration
Objective-C
- (void)setCamera:(nonnull MGLMapCamera *)camera
withDuration:(NSTimeInterval)duration
animationTimingFunction:(nullable CAMediaTimingFunction *)function
edgePadding:(UIEdgeInsets)edgePadding
completionHandler:(nullable void (^)(void))completion;
Swift
func setCamera(_ camera: MGLMapCamera, withDuration duration: TimeInterval, animationTimingFunction function: CAMediaTimingFunction?, edgePadding: UIEdgeInsets, completionHandler completion: (() -> Void)? = nil)
Parameters
camera
The new viewpoint.
duration
The amount of time, measured in seconds, that the transition animation should take. Specify 0
to jump to the new viewpoint instantaneously.
function
A timing function used for the animation. Set this parameter to nil
for a transition that matches most system animations. If the duration is 0
, this parameter is ignored.
edgePadding
The minimum padding (in screen points) that would be visible around the returned camera object if it were set as the receiver’s camera.
completion
The block to execute after the animation finishes.
-flyToCamera:completionHandler:
Moves the viewpoint to a different location using a transition animation that evokes powered flight and a default duration based on the length of the flight path.
The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
Declaration
Objective-C
- (void)flyToCamera:(nonnull MGLMapCamera *)camera
completionHandler:(nullable void (^)(void))completion;
Swift
func fly(to camera: MGLMapCamera, completionHandler completion: (() -> Void)? = nil)
Parameters
camera
The new viewpoint.
completion
The block to execute after the animation finishes.
-flyToCamera:withDuration:completionHandler:
Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration.
The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
Declaration
Objective-C
- (void)flyToCamera:(nonnull MGLMapCamera *)camera
withDuration:(NSTimeInterval)duration
completionHandler:(nullable void (^)(void))completion;
Swift
func fly(to camera: MGLMapCamera, withDuration duration: TimeInterval, completionHandler completion: (() -> Void)? = nil)
Parameters
camera
The new viewpoint.
duration
The amount of time, measured in seconds, that the transition animation should take. Specify 0
to jump to the new viewpoint instantaneously. Specify a negative value to use the default duration, which is based on the length of the flight path.
completion
The block to execute after the animation finishes.
-flyToCamera:withDuration:peakAltitude:completionHandler:
Moves the viewpoint to a different location using a transition animation that evokes powered flight and an optional transition duration and peak altitude.
The transition animation seamlessly incorporates zooming and panning to help the user find his or her bearings even after traversing a great distance.
Declaration
Objective-C
- (void)flyToCamera:(nonnull MGLMapCamera *)camera
withDuration:(NSTimeInterval)duration
peakAltitude:(CLLocationDistance)peakAltitude
completionHandler:(nullable void (^)(void))completion;
Swift
func fly(to camera: MGLMapCamera, withDuration duration: TimeInterval, peakAltitude: CLLocationDistance, completionHandler completion: (() -> Void)? = nil)
Parameters
camera
The new viewpoint.
duration
The amount of time, measured in seconds, that the transition animation should take. Specify 0
to jump to the new viewpoint instantaneously. Specify a negative value to use the default duration, which is based on the length of the flight path.
peakAltitude
The altitude, measured in meters, at the midpoint of the animation. The value of this parameter is ignored if it is negative or if the animation transition resulting from a similar call to -setCamera:animated:
would have a midpoint at a higher altitude.
completion
The block to execute after the animation finishes.
-cameraThatFitsCoordinateBounds:
Returns the camera that best fits the given coordinate bounds.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
; you may receive a nil
return value depending on the order of notification delivery.
Declaration
Objective-C
- (nonnull MGLMapCamera *)cameraThatFitsCoordinateBounds:
(MGLCoordinateBounds)bounds;
Swift
func cameraThatFitsCoordinateBounds(_ bounds: MGLCoordinateBounds) -> MGLMapCamera
Parameters
bounds
The coordinate bounds to fit to the receiver’s viewport.
Return Value
A camera object centered on the same location as the coordinate bounds with zoom level as high (close to the ground) as possible while still including the entire coordinate bounds. The camera object uses the current direction and pitch.
-cameraThatFitsCoordinateBounds:edgePadding:
Returns the camera that best fits the given coordinate bounds with some additional padding on each side.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
; you may receive a nil
return value depending on the order of notification delivery.
Declaration
Objective-C
- (nonnull MGLMapCamera *)cameraThatFitsCoordinateBounds:
(MGLCoordinateBounds)bounds
edgePadding:(UIEdgeInsets)insets;
Swift
func cameraThatFitsCoordinateBounds(_ bounds: MGLCoordinateBounds, edgePadding insets: UIEdgeInsets) -> MGLMapCamera
Parameters
bounds
The coordinate bounds to fit to the receiver’s viewport.
insets
The minimum padding (in screen points) that would be visible around the returned camera object if it were set as the receiver’s camera.
Return Value
A camera object centered on the same location as the coordinate bounds with zoom level as high (close to the ground) as possible while still including the entire coordinate bounds. The camera object uses the current direction and pitch.
-camera:fittingCoordinateBounds:edgePadding:
Returns the camera that best fits the given coordinate bounds with some additional padding on each side, matching an existing camera as much as possible.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
; you may receive a nil
return value depending on the order of notification delivery.
Declaration
Objective-C
- (nonnull MGLMapCamera *)camera:(nonnull MGLMapCamera *)camera
fittingCoordinateBounds:(MGLCoordinateBounds)bounds
edgePadding:(UIEdgeInsets)insets;
Swift
func camera(_ camera: MGLMapCamera, fitting bounds: MGLCoordinateBounds, edgePadding insets: UIEdgeInsets) -> MGLMapCamera
Parameters
camera
The camera that the return camera should adhere to. All values on this camera will be manipulated except for pitch and direction.
bounds
The coordinate bounds to fit to the receiver’s viewport.
insets
The minimum padding (in screen points) that would be visible around the returned camera object if it were set as the receiver’s camera.
Return Value
A camera object centered on the same location as the coordinate bounds with zoom level as high (close to the ground) as possible while still including the entire coordinate bounds. The initial camera’s pitch and direction will be honored.
-camera:fittingShape:edgePadding:
Returns the camera that best fits the given shape with some additional padding on each side, matching an existing camera as much as possible.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
; you may receive a nil
return value depending on the order of notification delivery.
Declaration
Objective-C
- (nonnull MGLMapCamera *)camera:(nonnull MGLMapCamera *)camera
fittingShape:(nonnull MGLShape *)shape
edgePadding:(UIEdgeInsets)insets;
Swift
func camera(_ camera: MGLMapCamera, fitting shape: MGLShape, edgePadding insets: UIEdgeInsets) -> MGLMapCamera
Parameters
camera
The camera that the return camera should adhere to. All values on this camera will be manipulated except for pitch and direction.
shape
The shape to fit to the receiver’s viewport.
insets
The minimum padding (in screen points) that would be visible around the returned camera object if it were set as the receiver’s camera.
Return Value
A camera object centered on the shape’s center with zoom level as high (close to the ground) as possible while still including the entire shape. The initial camera’s pitch and direction will be honored.
-cameraThatFitsShape:direction:edgePadding:
Returns the camera that best fits the given shape with some additional padding on each side while looking in the specified direction.
Note
The behavior of this method is undefined if called in response to UIApplicationWillTerminateNotification
; you may receive a nil
return value depending on the order of notification delivery.
Declaration
Objective-C
- (nonnull MGLMapCamera *)cameraThatFitsShape:(nonnull MGLShape *)shape
direction:(CLLocationDirection)direction
edgePadding:(UIEdgeInsets)insets;
Swift
func cameraThatFitsShape(_ shape: MGLShape, direction: CLLocationDirection, edgePadding insets: UIEdgeInsets) -> MGLMapCamera
Parameters
shape
The shape to fit to the receiver’s viewport.
direction
The direction of the viewport, measured in degrees clockwise from true north.
insets
The minimum padding (in screen points) that would be visible around the returned camera object if it were set as the receiver’s camera.
Return Value
A camera object centered on the shape’s center with zoom level as high (close to the ground) as possible while still including the entire shape. The camera object uses the current pitch.
-anchorPointForGesture:
Returns the point in this view’s coordinate system on which to “anchor” in response to a user-initiated gesture.
For example, a pinch-to-zoom gesture would anchor the map at the midpoint of the pinch.
If the userTrackingMode
property is not MGLUserTrackingModeNone
, the user annotation is used as the anchor point.
Subclasses may override this method to provide specialized behavior - for example, anchoring on the map’s center point to provide a locked zooming mode.
Declaration
Objective-C
- (CGPoint)anchorPointForGesture:(nonnull UIGestureRecognizer *)gesture;
Swift
func anchorPoint(forGesture gesture: UIGestureRecognizer) -> CGPoint
Parameters
gesture
An anchorable user gesture.
Return Value
The point on which to anchor in response to the gesture.
contentInset
The distance from the edges of the map view’s frame to the edges of the map view’s logical viewport.
When the value of this property is equal to UIEdgeInsetsZero
, viewport properties such as centerCoordinate
assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.
When the map view’s superview is an instance of UIViewController
whose automaticallyAdjustsScrollViewInsets
property is YES
, the value of this property may be overridden at any time.
The usage of automaticallyAdjustsScrollViewInsets
has been deprecated use the map view’s property MGLMapView.automaticallyAdjustsContentInset
instead.
Changing the value of this property updates the map view immediately. If you want to animate the change, use the -setContentInset:animated:completionHandler:
method instead.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
UIEdgeInsets contentInset;
Swift
var contentInset: UIEdgeInsets { get set }
-setContentInset:animated:
Deprecated
Use -setContentInset:animated:completionHandler:
instead.
Deprecated. Sets the distance from the edges of the map view’s frame to the edges of the map view’s logical viewport with an optional transition animation.
When the value of this property is equal to UIEdgeInsetsZero
, viewport properties such as centerCoordinate
assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.
When the map view’s superview is an instance of UIViewController
whose automaticallyAdjustsScrollViewInsets
property is YES
, the value of this property may be overridden at any time.
The usage of automaticallyAdjustsScrollViewInsets
has been deprecated use the map view’s property MGLMapView.automaticallyAdjustsContentInset
instead.
To specify a completion handler to execute after the animation finishes, use the -setContentInset:animated:completionHandler:
method.
Declaration
Objective-C
- (void)setContentInset:(UIEdgeInsets)contentInset animated:(BOOL)animated;
Swift
func setContentInset(_ contentInset: UIEdgeInsets, animated: Bool)
Parameters
contentInset
The new values to inset the content by.
animated
Specify YES
if you want the map view to animate the change to the content inset or NO
if you want the map to inset the content immediately.
-setContentInset:animated:completionHandler:
Sets the distance from the edges of the map view’s frame to the edges of the map view’s logical viewport with an optional transition animation and completion handler.
When the value of this property is equal to UIEdgeInsetsZero
, viewport properties such as centerCoordinate
assume a viewport that matches the map view’s frame. Otherwise, those properties are inset, excluding part of the frame from the viewport. For instance, if the only the top edge is inset, the map center is effectively shifted downward.
When the map view’s superview is an instance of UIViewController
whose automaticallyAdjustsScrollViewInsets
property is YES
, the value of this property may be overridden at any time.
The usage of automaticallyAdjustsScrollViewInsets
has been deprecated use the map view’s property MGLMapView.automaticallyAdjustsContentInset
instead.
Declaration
Objective-C
- (void)setContentInset:(UIEdgeInsets)contentInset
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Swift
func setContentInset(_ contentInset: UIEdgeInsets, animated: Bool, completionHandler completion: (() -> Void)? = nil)
Parameters
contentInset
The new values to inset the content by.
animated
Specify YES
if you want the map view to animate the change to the content inset or NO
if you want the map to inset the content immediately.
completion
The block executed after the animation finishes.
Converting Geographic Coordinates
-convertPoint:toCoordinateFromView:
Converts a point in the given view’s coordinate system to a geographic coordinate.
Declaration
Objective-C
- (CLLocationCoordinate2D)convertPoint:(CGPoint)point
toCoordinateFromView:(nullable UIView *)view;
Swift
func convert(_ point: CGPoint, toCoordinateFrom view: UIView?) -> CLLocationCoordinate2D
Parameters
point
The point to convert.
view
The view in whose coordinate system the point is expressed.
Return Value
The geographic coordinate at the given point.
-convertCoordinate:toPointToView:
Converts a geographic coordinate to a point in the given view’s coordinate system.
Declaration
Objective-C
- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate
toPointToView:(nullable UIView *)view;
Swift
func convert(_ coordinate: CLLocationCoordinate2D, toPointTo view: UIView?) -> CGPoint
Parameters
coordinate
The geographic coordinate to convert.
view
The view in whose coordinate system the returned point should be expressed. If this parameter is nil
, the returned point is expressed in the window’s coordinate system. If view
is not nil
, it must belong to the same window as the map view.
Return Value
The point (in the appropriate view or window coordinate system) corresponding to the given geographic coordinate.
-convertRect:toCoordinateBoundsFromView:
Converts a rectangle in the given view’s coordinate system to a geographic bounding box.
If the returned coordinate bounds contains a longitude is less than −180 degrees or greater than 180 degrees, the bounding box straddles the antimeridian or international date line.
Declaration
Objective-C
- (MGLCoordinateBounds)convertRect:(CGRect)rect
toCoordinateBoundsFromView:(nullable UIView *)view;
Swift
func convert(_ rect: CGRect, toCoordinateBoundsFrom view: UIView?) -> MGLCoordinateBounds
Parameters
rect
The rectangle to convert.
view
The view in whose coordinate system the rectangle is expressed.
Return Value
The geographic bounding box coextensive with the given rectangle.
-convertCoordinateBounds:toRectToView:
Converts a geographic bounding box to a rectangle in the given view’s coordinate system.
To bring both sides of the antimeridian or international date line into view, specify some longitudes less than −180 degrees or greater than 180 degrees. For example, to show both Tokyo and San Francisco simultaneously, you could set the visible bounds to extend from (35.68476, −220.24257) to (37.78428, −122.41310).
Declaration
Objective-C
- (CGRect)convertCoordinateBounds:(MGLCoordinateBounds)bounds
toRectToView:(nullable UIView *)view;
Swift
func convert(_ bounds: MGLCoordinateBounds, toRectTo view: UIView?) -> CGRect
Parameters
bounds
The geographic bounding box to convert.
view
The view in whose coordinate system the returned rectangle should be expressed. If this parameter is nil
, the returned rectangle is expressed in the window’s coordinate system. If view
is not nil
, it must belong to the same window as the map view.
-metersPerPointAtLatitude:
Returns the distance spanned by one point in the map view’s coordinate system at the given latitude and current zoom level.
The distance between points decreases as the latitude approaches the poles. This relationship parallels the relationship between longitudinal coordinates at different latitudes.
Declaration
Objective-C
- (CLLocationDistance)metersPerPointAtLatitude:(CLLocationDegrees)latitude;
Swift
func metersPerPoint(atLatitude latitude: CLLocationDegrees) -> CLLocationDistance
Parameters
latitude
The latitude of the geographic coordinate represented by the point.
Return Value
The distance in meters spanned by a single point.
Annotating the Map
annotations
The complete list of annotations associated with the receiver. (read-only)
The objects in this array must adopt the MGLAnnotation
protocol. If no annotations are associated with the map view, the value of this property is nil
.
Declaration
Objective-C
@property (nonatomic, readonly, nullable)
NSArray<id<MGLAnnotation>> *annotations;
-addAnnotation:
Adds an annotation to the map view.
Note
MGLMultiPolyline
, MGLMultiPolygon
, MGLShapeCollection
, and MGLPointCollection
objects cannot be added to the map view at this time. Any multipoint, multipolyline, multipolygon, shape or point collection object that is specified is silently ignored.
Declaration
Objective-C
- (void)addAnnotation:(nonnull id<MGLAnnotation>)annotation;
Parameters
annotation
The annotation object to add to the receiver. This object must conform to the MGLAnnotation
protocol. The map view retains the annotation object.
-addAnnotations:
Adds an array of annotations to the map view.
Note
MGLMultiPolyline
, MGLMultiPolygon
, and MGLShapeCollection
objects cannot be added to the map view at this time. Nor can MGLMultiPoint
objects that are not instances of MGLPolyline
or MGLPolygon
. Any multipoint, multipolyline, multipolygon, or shape collection objects that are specified are silently ignored.
Declaration
Objective-C
- (void)addAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations;
Parameters
annotations
An array of annotation objects. Each object in the array must conform to the MGLAnnotation
protocol. The map view retains each individual annotation object.
-removeAnnotation:
Removes an annotation from the map view, deselecting it if it is selected.
Removing an annotation object dissociates it from the map view entirely, preventing it from being displayed on the map. Thus you would typically call this method only when you want to hide or delete a given annotation.
Declaration
Objective-C
- (void)removeAnnotation:(nonnull id<MGLAnnotation>)annotation;
Parameters
annotation
The annotation object to remove. This object must conform to the MGLAnnotation
protocol
-removeAnnotations:
Removes an array of annotations from the map view, deselecting any selected annotations in the array.
Removing annotation objects dissociates them from the map view entirely, preventing them from being displayed on the map. Thus you would typically call this method only when you want to hide or delete the given annotations.
Declaration
Objective-C
- (void)removeAnnotations:(nonnull NSArray<id<MGLAnnotation>> *)annotations;
Parameters
annotations
The array of annotation objects to remove. Objects in the array must conform to the MGLAnnotation
protocol.
-viewForAnnotation:
Returns an MGLAnnotationView
if the given annotation is currently associated with a view, otherwise nil.
Declaration
Objective-C
- (nullable MGLAnnotationView *)viewForAnnotation:
(nonnull id<MGLAnnotation>)annotation;
Parameters
annotation
The annotation associated with the view. Annotation must conform to the MGLAnnotation
protocol.
-dequeueReusableAnnotationImageWithIdentifier:
Returns a reusable annotation image object associated with its identifier.
For performance reasons, you should generally reuse MGLAnnotationImage
objects for identical-looking annotations in your map views. Dequeueing saves time and memory during performance-critical operations such as scrolling.
Declaration
Objective-C
- (nullable __kindof MGLAnnotationImage *)
dequeueReusableAnnotationImageWithIdentifier:(nonnull NSString *)identifier;
Swift
func dequeueReusableAnnotationImage(withIdentifier identifier: String) -> MGLAnnotationImage?
Parameters
identifier
A string identifying the annotation image to be reused. This string is the same one you specify when initially returning the annotation image object using the -mapView:imageForAnnotation:
method.
Return Value
An annotation image object with the given identifier, or nil
if no such object exists in the reuse queue.
-dequeueReusableAnnotationViewWithIdentifier:
Returns a reusable annotation view object associated with its identifier.
For performance reasons, you should generally reuse MGLAnnotationView
objects for identical-looking annotations in your map views. Dequeueing saves time and memory during performance-critical operations such as scrolling.
Declaration
Objective-C
- (nullable __kindof MGLAnnotationView *)
dequeueReusableAnnotationViewWithIdentifier:(nonnull NSString *)identifier;
Swift
func dequeueReusableAnnotationView(withIdentifier identifier: String) -> MGLAnnotationView?
Parameters
identifier
A string identifying the annotation view to be reused. This string is the same one you specify when initially returning the annotation view object using the -mapView:viewForAnnotation:
method.
Return Value
An annotation view object with the given identifier, or nil
if no such object exists in the reuse queue.
visibleAnnotations
The complete list of annotations associated with the receiver that are currently visible.
The objects in this array must adopt the MGLAnnotation
protocol. If no annotations are associated with the map view or if no annotations associated with the map view are currently visible, the value of this property is nil
.
Declaration
Objective-C
@property (nonatomic, readonly, nullable)
NSArray<id<MGLAnnotation>> *visibleAnnotations;
-visibleAnnotationsInRect:
Returns the list of annotations associated with the receiver that intersect with the given rectangle.
Declaration
Objective-C
- (nullable NSArray<id<MGLAnnotation>> *)visibleAnnotationsInRect:(CGRect)rect;
Parameters
rect
A rectangle expressed in the map view’s coordinate system.
Return Value
An array of objects that adopt the MGLAnnotation
protocol or nil
if no annotations associated with the map view are currently visible in the rectangle.
Managing Annotation Selections
selectedAnnotations
The currently selected annotations.
Assigning a new array to this property selects only the first annotation in the array.
If the annotation is of type MGLPointAnnotation
and is offscreen, the camera will animate to bring the annotation and its callout just on screen. If you need finer control, consider using -selectAnnotation:animated:
.
Note
In versions prior to 4.0.0
if the annotation was offscreen it was not selected.
Declaration
Objective-C
@property (nonatomic, copy, readwrite)
NSArray<id<MGLAnnotation>> *_Nonnull selectedAnnotations;
-selectAnnotation:animated:
Deprecated
Use -selectAnnotation:animated:completionHandler:
instead.
Deprecated. Selects an annotation and displays its callout view.
The animated
parameter determines whether the selection is animated including whether the map is panned to bring the annotation into view, specifically:
animated
parameter
Effect
NO
The annotation is selected, and the callout is presented. However the map is not panned to bring the annotation or callout into view. The presentation of the callout is NOT animated.
YES
The annotation is selected, and the callout is presented. If the annotation is not visible (or is partially visible) and is of type MGLPointAnnotation
, the map is panned so that the annotation and its callout are brought into view. The annotation is not centered within the viewport.
Note that a selection initiated by a single tap gesture is always animated.
To specify a completion handler to execute after the animation finishes, use the -selectAnnotation:animated:completionHandler:
method.
Note
In versions prior to 4.0.0
selecting an offscreen annotation did not change the camera.
Declaration
Objective-C
- (void)selectAnnotation:(nonnull id<MGLAnnotation>)annotation
animated:(BOOL)animated;
Parameters
annotation
The annotation object to select.
animated
If YES
, the annotation and callout view are animated on-screen.
-selectAnnotation:animated:completionHandler:
Selects an annotation and displays its callout view with an optional completion handler.
The animated
parameter determines whether the selection is animated including whether the map is panned to bring the annotation into view, specifically:
animated
parameter
Effect
NO
The annotation is selected, and the callout is presented. However the map is not panned to bring the annotation or callout into view. The presentation of the callout is NOT animated.
YES
The annotation is selected, and the callout is presented. If the annotation is not visible (or is partially visible) and is of type MGLPointAnnotation
, the map is panned so that the annotation and its callout are brought into view. The annotation is not centered within the viewport.
Note that a selection initiated by a single tap gesture is always animated.
Note
In versions prior to 4.0.0
selecting an offscreen annotation did not change the camera.
Declaration
Objective-C
- (void)selectAnnotation:(nonnull id<MGLAnnotation>)annotation
animated:(BOOL)animated
completionHandler:(nullable void (^)(void))completion;
Parameters
annotation
The annotation object to select.
animated
If YES
, the annotation and callout view are animated on-screen.
completion
The block executed after the animation finishes.
-deselectAnnotation:animated:
Deselects an annotation and hides its callout view.
Declaration
Objective-C
- (void)deselectAnnotation:(nullable id<MGLAnnotation>)annotation
animated:(BOOL)animated;
Parameters
annotation
The annotation object to deselect.
animated
If YES
, the callout view is animated offscreen.
Overlaying the Map
overlays
The complete list of overlays associated with the receiver. (read-only)
The objects in this array must adopt the MGLOverlay
protocol. If no overlays are associated with the map view, the value of this property is empty array.
Declaration
Objective-C
@property (nonatomic, readonly, nonnull) NSArray<id<MGLOverlay>> *overlays;
-addOverlay:
Adds a single overlay object to the map.
To remove an overlay from a map, use the -removeOverlay:
method.
Declaration
Objective-C
- (void)addOverlay:(nonnull id<MGLOverlay>)overlay;
Parameters
overlay
The overlay object to add. This object must conform to the MGLOverlay
protocol.
-addOverlays:
Adds an array of overlay objects to the map.
To remove multiple overlays from a map, use the -removeOverlays:
method.
Declaration
Objective-C
- (void)addOverlays:(nonnull NSArray<id<MGLOverlay>> *)overlays;
Parameters
overlays
An array of objects, each of which must conform to the MGLOverlay
protocol.
-removeOverlay:
Removes a single overlay object from the map.
If the specified overlay is not currently associated with the map view, this method does nothing.
Declaration
Objective-C
- (void)removeOverlay:(nonnull id<MGLOverlay>)overlay;
Parameters
overlay
The overlay object to remove.
-removeOverlays:
Removes one or more overlay objects from the map.
If a given overlay object is not associated with the map view, it is ignored.
Declaration
Objective-C
- (void)removeOverlays:(nonnull NSArray<id<MGLOverlay>> *)overlays;
Parameters
overlays
An array of objects, each of which conforms to the MGLOverlay
protocol.
Accessing the Underlying Map Data
-visibleFeaturesAtPoint:
Returns an array of rendered map features that intersect with a given point.
This method may return features from any of the map’s style layers. To restrict the search to a particular layer or layers, use the -visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:
method. For more information about searching for map features, see that method’s documentation.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)visibleFeaturesAtPoint:(CGPoint)point;
Parameters
point
A point expressed in the map view’s coordinate system.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
-visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:
Returns an array of rendered map features that intersect with a given point, restricted to the given style layers.
This method returns all the intersecting features from the specified layers. To filter the returned features, use the -visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:
method. For more information about searching for map features, see that method’s documentation.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)visibleFeaturesAtPoint:(CGPoint)point
inStyleLayersWithIdentifiers:
(nullable NSSet<NSString *> *)
styleLayerIdentifiers;
Parameters
point
A point expressed in the map view’s coordinate system.
styleLayerIdentifiers
A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
-visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:
Returns an array of rendered map features that intersect with a given point, restricted to the given style layers and filtered by the given predicate.
Each object in the returned array represents a feature rendered by the current style and provides access to attributes specified by the relevant map content sources. The returned array includes features loaded by MGLShapeSource
and MGLVectorTileSource
objects but does not include anything from MGLRasterTileSource
objects, or from video or canvas sources, which are unsupported by this SDK.
The returned features are drawn by a style layer in the current style. For example, suppose the current style uses the MapTiler Streets source, but none of the specified style layers includes features that have the maki
property set to bus
. If you pass a point corresponding to the location of a bus stop into this method, the bus stop feature does not appear in the resulting array. On the other hand, if the style does include bus stops, an MGLFeature
object representing that bus stop is returned and its featureAttributes
dictionary has the maki
key set to bus
(along with other attributes). The dictionary contains only the attributes provided by the tile source; it does not include computed attribute values or rules about how the feature is rendered by the current style.
The returned array is sorted by z-order, starting with the topmost rendered feature and ending with the bottommost rendered feature. A feature that is rendered multiple times due to wrapping across the antimeridian at low zoom levels is included only once, subject to the caveat that follows.
Features come from tiled vector data or GeoJSON data that is converted to tiles internally, so feature geometries are clipped at tile boundaries and features may appear duplicated across tiles. For example, suppose the specified point lies along a road that spans the screen. The resulting array includes those parts of the road that lie within the map tile that contain the specified point, even if the road extends into other tiles.
To find out the layer names in a particular style, view the style in MapTiler Customize.
Only visible features are returned. To obtain features regardless of visibility, use the -[MGLVectorTileSource featuresInSourceLayersWithIdentifiers:predicate:]
and -[MGLShapeSource featuresMatchingPredicate:]
methods on the relevant sources.
The returned features may also include features corresponding to annotations. These features are not object-equal to the MGLAnnotation
objects that were originally added to the map. To query the map for annotations, use visibleAnnotations
or -[MGLMapView visibleAnnotationsInRect:]
.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:]
, MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)
visibleFeaturesAtPoint:(CGPoint)point
inStyleLayersWithIdentifiers:
(nullable NSSet<NSString *> *)styleLayerIdentifiers
predicate:(nullable NSPredicate *)predicate;
Parameters
point
A point expressed in the map view’s coordinate system.
styleLayerIdentifiers
A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
predicate
A predicate to filter the returned features.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
-visibleFeaturesInRect:
Returns an array of rendered map features that intersect with the given rectangle.
This method may return features from any of the map’s style layers. To restrict the search to a particular layer or layers, use the -visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:
method. For more information about searching for map features, see that method’s documentation.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)visibleFeaturesInRect:(CGRect)rect;
Parameters
rect
A rectangle expressed in the map view’s coordinate system.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
-visibleFeaturesInRect:inStyleLayersWithIdentifiers:
Returns an array of rendered map features that intersect with the given rectangle, restricted to the given style layers.
This method returns all the intersecting features from the specified layers. To filter the returned features, use the -visibleFeaturesAtPoint:inStyleLayersWithIdentifiers:predicate:
method. For more information about searching for map features, see that method’s documentation.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)visibleFeaturesInRect:(CGRect)rect
inStyleLayersWithIdentifiers:
(nullable NSSet<NSString *> *)
styleLayerIdentifiers;
Parameters
rect
A rectangle expressed in the map view’s coordinate system.
styleLayerIdentifiers
A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
-visibleFeaturesInRect:inStyleLayersWithIdentifiers:predicate:
Returns an array of rendered map features that intersect with the given rectangle, restricted to the given style layers and filtered by the given predicate.
Each object in the returned array represents a feature rendered by the current style and provides access to attributes specified by the relevant map content sources. The returned array includes features loaded by MGLShapeSource
and MGLVectorTileSource
objects but does not include anything from MGLRasterTileSource
objects, or from video or canvas sources, which are unsupported by this SDK.
The returned features are drawn by a style layer in the current style. For example, suppose the current style uses the MapTiler Streets source, but none of the specified style layers includes features that have the maki
property set to bus
. If you pass a rectangle containing the location of a bus stop into this method, the bus stop feature does not appear in the resulting array. On the other hand, if the style does include bus stops, an MGLFeature
object representing that bus stop is returned and its featureAttributes
dictionary has the maki
key set to bus
(along with other attributes). The dictionary contains only the attributes provided by the tile source; it does not include computed attribute values or rules about how the feature is rendered by the current style.
The returned array is sorted by z-order, starting with the topmost rendered feature and ending with the bottommost rendered feature. A feature that is rendered multiple times due to wrapping across the antimeridian at low zoom levels is included only once, subject to the caveat that follows.
Features come from tiled vector data or GeoJSON data that is converted to tiles internally, so feature geometries are clipped at tile boundaries and features may appear duplicated across tiles. For example, suppose the specified rectangle intersects with a road that spans the screen. The resulting array includes those parts of the road that lie within the map tiles covering the specified rectangle, even if the road extends into other tiles. The portion of the road within each map tile is included individually.
To find out the layer names in a particular style, view the style in MapTiler Customize.
Only visible features are returned. To obtain features regardless of visibility, use the -[MGLVectorTileSource featuresInSourceLayersWithIdentifiers:predicate:]
and -[MGLShapeSource featuresMatchingPredicate:]
methods on the relevant sources.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:]
, MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.
Note
Layer identifiers are not guaranteed to exist across styles or different versions of the same style. Applications that use this API must first set the style URL to an explicitly versioned style using a convenience method like +[MGLStyle outdoorsStyleURLWithVersion:]
, MGLMapView
’s “Style URL” inspectable in Interface Builder, or a manually constructed NSURL
. This approach also avoids layer identifer name changes that will occur in the default style’s layers over time.
Declaration
Objective-C
- (nonnull NSArray<id<MGLFeature>> *)
visibleFeaturesInRect:(CGRect)rect
inStyleLayersWithIdentifiers:
(nullable NSSet<NSString *> *)styleLayerIdentifiers
predicate:(nullable NSPredicate *)predicate;
Parameters
rect
A rectangle expressed in the map view’s coordinate system.
styleLayerIdentifiers
A set of strings that correspond to the names of layers defined in the current style. Only the features contained in these layers are included in the returned array.
predicate
A predicate to filter the returned features.
Return Value
An array of objects conforming to the MGLFeature
protocol that represent features in the sources used by the current style.
Debugging the Map
debugMask
The options that determine which debugging aids are shown on the map.
These options are all disabled by default and should remain disabled in released software for performance and aesthetic reasons.
Declaration
Objective-C
@property (nonatomic, assign, unsafe_unretained, readwrite)
MGLMapDebugMaskOptions debugMask;
Swift
var debugMask: MGLMapDebugMaskOptions { get set }
iOS SDK
Examples
SDK JS Reference
- Annotations
- Appendices
- NSExpression(MGLAdditions)
- NSValue(MGLAdditions)
- NSValue(MGLCircleStyleLayerAdditions)
- NSValue(MGLFillExtrusionStyleLayerAdditions)
- NSValue(MGLFillStyleLayerAdditions)
- NSValue(MGLHillshadeStyleLayerAdditions)
- NSValue(MGLLineStyleLayerAdditions)
- NSValue(MGLRasterStyleLayerAdditions)
- NSValue(MGLSymbolStyleLayerAdditions)
- MGLAccountManager
- MGLAnnotationImage
- MGLAnnotationView
- MGLAttributedExpression
- MGLAttributionInfo
- MGLBackgroundStyleLayer
- MGLCircleStyleLayer
- MGLClockDirectionFormatter
- MGLCompassButton
- MGLCompassDirectionFormatter
- MGLComputedShapeSource
- MGLCoordinateFormatter
- MGLDistanceFormatter
- MGLFillExtrusionStyleLayer
- MGLFillStyleLayer
- MGLForegroundStyleLayer
- MGLHeatmapStyleLayer
- MGLHillshadeStyleLayer
- MGLImageSource
- MGLLight
- MGLLineStyleLayer
- MGLLoggingConfiguration
- MGLMapCamera
- MGLMapSnapshot
- MGLMapSnapshotOptions
- MGLMapSnapshotOverlay
- MGLMapSnapshotter
- MGLMapView
- MGLMultiPoint
- MGLMultiPolygon
- MGLMultiPolyline
- MGLNetworkConfiguration
- MGLOfflinePack
- MGLOfflineStorage
- MGLPointAnnotation
- MGLPointCollection
- MGLPolygon
- MGLPolyline
- MGLRasterStyleLayer
- MGLRasterTileSource
- MGLShape
- MGLShapeCollection
- MGLShapeOfflineRegion
- MGLShapeSource
- MGLSource
- MGLStyle
- MGLStyleLayer
- MGLSymbolStyleLayer
- MGLTilePyramidOfflineRegion
- MGLTileSource
- MGLUserLocation
- MGLUserLocationAnnotationView
- MGLUserLocationAnnotationViewStyle
- MGLVectorStyleLayer
- MGLVectorTileSource
- MGLAnnotationVerticalAlignment
- MGLAnnotationViewDragState
- MGLAttributionInfoStyle
- MGLCirclePitchAlignment
- MGLCircleScaleAlignment
- MGLCircleTranslationAnchor
- MGLDEMEncoding
- MGLErrorCode
- MGLFillExtrusionTranslationAnchor
- MGLFillTranslationAnchor
- MGLHillshadeIlluminationAnchor
- MGLIconAnchor
- MGLIconPitchAlignment
- MGLIconRotationAlignment
- MGLIconTextFit
- MGLIconTranslationAnchor
- MGLLightAnchor
- MGLLineCap
- MGLLineJoin
- MGLLineTranslationAnchor
- MGLLoggingLevel
- MGLMapDebugMaskOptions
- MGLOfflinePackState
- MGLOrnamentPosition
- MGLOrnamentVisibility
- MGLRasterResamplingMode
- MGLResourceKind
- MGLSymbolPlacement
- MGLSymbolZOrder
- MGLTextAnchor
- MGLTextJustification
- MGLTextPitchAlignment
- MGLTextRotationAlignment
- MGLTextTransform
- MGLTextTranslationAnchor
- MGLTextWritingMode
- MGLTileCoordinateSystem
- MGLUserTrackingMode
- Formatters
- Geometry
- Location Updates
- Maps
- Offline Maps
- Other Categories
- Other Classes
- Other Constants
- Other Enumerations
- Other Functions
- Other Protocols
- Other Structures
- Other Type Definitions
- Primitive Shapes
- MGLAnnotation
- MGLCalloutView
- MGLCalloutViewDelegate
- MGLCluster
- MGLComputedShapeSourceDataSource
- MGLFeature
- MGLLocationManager
- MGLLocationManagerDelegate
- MGLMapSnapshotterDelegate
- MGLMapViewDelegate
- MGLOfflineRegion
- MGLOfflineStorageDelegate
- MGLOverlay
- MGLStylable
- MGLCoordinateBounds
- MGLCoordinateQuad
- MGLCoordinateSpan
- MGLOfflinePackProgress
- MGLSphericalPosition
- MGLTransition
- Style Content
- Style Layers
- Style Primitives
- Styling the Map
- MGLCoordinateBounds
- MGLCoordinateQuad
- MGLCoordinateSpan
- MGLOfflinePackProgress
- MGLSphericalPosition
- MGLTransition
- User Interaction
- Customizing Fonts
- Information for Style Authors
- Gesture Recognizers
- Info.plist Keys
- Migrating to Expressions
- Predicates and expressions
- Tile URL Templates
- Working with GeoJSON Data