summaryrefslogtreecommitdiff
path: root/platform/ios
diff options
context:
space:
mode:
Diffstat (limited to 'platform/ios')
-rw-r--r--platform/ios/src/MGLAnnotationImage.h5
-rw-r--r--platform/ios/src/MGLAnnotationView.h10
-rw-r--r--platform/ios/src/MGLCalloutView.h5
-rw-r--r--platform/ios/src/MGLMapView.h67
-rw-r--r--platform/ios/src/MGLMapViewDelegate.h102
-rw-r--r--platform/ios/src/MGLUserLocation.h3
-rw-r--r--platform/ios/src/MGLUserLocationAnnotationView.h5
7 files changed, 185 insertions, 12 deletions
diff --git a/platform/ios/src/MGLAnnotationImage.h b/platform/ios/src/MGLAnnotationImage.h
index 0b5a111841..fd76a9b43a 100644
--- a/platform/ios/src/MGLAnnotationImage.h
+++ b/platform/ios/src/MGLAnnotationImage.h
@@ -9,6 +9,11 @@ NS_ASSUME_NONNULL_BEGIN
annotations visually on a map view. Annotation image objects wrap `UIImage`
objects and may be recycled later and put into a reuse queue that is maintained
by the map view.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/marker-image/">
+ Mark a place on the map with an image</a> example to learn how use an image
+ as a marker using `MGLAnnotationImage`.
*/
MGL_EXPORT
@interface MGLAnnotationImage : NSObject <NSSecureCoding>
diff --git a/platform/ios/src/MGLAnnotationView.h b/platform/ios/src/MGLAnnotationView.h
index 57d97e56c1..61fd22f1c2 100644
--- a/platform/ios/src/MGLAnnotationView.h
+++ b/platform/ios/src/MGLAnnotationView.h
@@ -222,6 +222,11 @@ MGL_EXPORT
if it should display itself as unselected.
@param animated `YES` if the change in selection state is animated; `NO` if the
change is immediate.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-vie
+ ws/">Annotation views</a> example to learn how to modify an
+ `MGLAnnotationView`'s behavior when it is selected.
*/
- (void)setSelected:(BOOL)selected animated:(BOOL)animated;
@@ -250,6 +255,11 @@ MGL_EXPORT
attempting to stop an operation that has already been initiated; doing so can
lead to undefined behavior. Once begun, the drag operation should always
continue to completion.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/draggable-views
+ /">Draggable annotation views</a> to learn how to enable users to drag
+ `MGLAnnotationView` objects on your map.
*/
@property (nonatomic, assign, getter=isDraggable) BOOL draggable;
diff --git a/platform/ios/src/MGLCalloutView.h b/platform/ios/src/MGLCalloutView.h
index 4f88429fbb..7b2177fdd5 100644
--- a/platform/ios/src/MGLCalloutView.h
+++ b/platform/ios/src/MGLCalloutView.h
@@ -11,6 +11,11 @@ NS_ASSUME_NONNULL_BEGIN
To receive updates from an object that conforms to the `MGLCalloutView` protocol,
use the optional methods available in the `MGLCalloutViewDelegate` protocol.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/custom-callout/">
+ Display custom views as callouts</a> example to learn how to customize an
+ `MGLCalloutView`.
*/
@protocol MGLCalloutView <NSObject>
diff --git a/platform/ios/src/MGLMapView.h b/platform/ios/src/MGLMapView.h
index 27394b61ff..0f8de86555 100644
--- a/platform/ios/src/MGLMapView.h
+++ b/platform/ios/src/MGLMapView.h
@@ -51,6 +51,9 @@ typedef NS_ENUM(NSUInteger, MGLAnnotationVerticalAlignment) {
/**
The mode used to track the user location on the map. Used with
`MGLMapView.userTrackingMode`.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/user-tracking-mode/">Switch between user tracking modes</a> example to learn how to toggle modes and how each mode behaves.
*/
typedef NS_ENUM(NSUInteger, MGLUserTrackingMode) {
/** The map does not follow the user location. */
@@ -151,7 +154,10 @@ FOUNDATION_EXTERN MGL_EXPORT MGLExceptionName const MGLResourceNotFoundException
@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.
-
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/simple-map-view/">
+ Simple map view</a> example to learn how to initialize a basic `MGLMapView`.
*/
MGL_EXPORT IB_DESIGNABLE
@interface MGLMapView : UIView
@@ -177,6 +183,16 @@ MGL_EXPORT IB_DESIGNABLE
(`mapbox://styles/{user}/{style}`), or a path to a local file relative
to the application’s resource path. Specify `nil` for the default style.
@return An initialized map view.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/custom-style/">
+ Apply a style designed in Mapbox Studio</a> example to learn how to
+ initialize an `MGLMapView` with a custom style. See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/raster-styles/">
+ Appy a style designed in Mapbox Studio Classic</a> example to learn how to
+ intialize an `MGLMapView` with a Studio Classic style _or_ a custom style
+ JSON. See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/source-custom-vector/">
+ Use third-party vector tiles</a> example to learn how to initialize an
+ `MGLMapView` with a third-party tile source.
*/
- (instancetype)initWithFrame:(CGRect)frame styleURL:(nullable NSURL *)styleURL;
@@ -230,6 +246,11 @@ MGL_EXPORT IB_DESIGNABLE
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.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/switch-styles/">
+ Switch between map styles</a> example to learn how to change the style of
+ a map at runtime.
*/
@property (nonatomic, null_resettable) NSURL *styleURL;
@@ -398,6 +419,11 @@ MGL_EXPORT IB_DESIGNABLE
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.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/user-location-annotation/">
+ Customize the user location annotation</a> to learn how to customize the
+ default user location annotation shown by `MGLUserTrackingMode`.
*/
@property (nonatomic, assign) MGLUserTrackingMode userTrackingMode;
@@ -878,6 +904,11 @@ MGL_EXPORT IB_DESIGNABLE
@param 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.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/camera-animation/">
+ Camera animation</a> example to learn how to trigger an animation that
+ rotates around a central point.
*/
- (void)setCamera:(MGLMapCamera *)camera animated:(BOOL)animated;
@@ -892,6 +923,11 @@ MGL_EXPORT IB_DESIGNABLE
@param 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.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/camera-animation/">
+ Camera animation</a> example to learn how to create a timed animation that
+ rotates around a central point for a specific duration.
*/
- (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function;
@@ -1115,6 +1151,11 @@ MGL_EXPORT IB_DESIGNABLE
@param point The point to convert.
@param view The view in whose coordinate system the point is expressed.
@return The geographic coordinate at the given point.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/point-conversion/">
+ Point conversion</a> example to learn how to convert a `CGPoint` to a map
+ coordinate.
*/
- (CLLocationCoordinate2D)convertPoint:(CGPoint)point toCoordinateFromView:(nullable UIView *)view;
@@ -1129,6 +1170,11 @@ MGL_EXPORT IB_DESIGNABLE
belong to the same window as the map view.
@return The point (in the appropriate view or window coordinate system)
corresponding to the given geographic coordinate.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/point-conversion/">
+ Point conversion</a> example to learn how to convert a map coordinate to a
+ `CGPoint` object.
*/
- (CGPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable UIView *)view;
@@ -1200,7 +1246,14 @@ MGL_EXPORT IB_DESIGNABLE
@param annotation The annotation object to add to the receiver. This object
must conform to the `MGLAnnotation` protocol. The map view retains the
- annotation object. */
+ annotation object.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-models/">
+ Annotation models</a> and <a href="https://www.mapbox.com/ios-sdk/maps/examples/line-geojson/">
+ Add a line annotation from GeoJSON</a> examples to learn how to add an
+ annotation to an `MGLMapView` object.
+ */
- (void)addAnnotation:(id <MGLAnnotation>)annotation;
/**
@@ -1265,6 +1318,11 @@ MGL_EXPORT IB_DESIGNABLE
annotation image object using the `-mapView:imageForAnnotation:` method.
@return An annotation image object with the given identifier, or `nil` if no
such object exists in the reuse queue.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-view-image/">
+ Add annotation views and images</a> example learn how to most efficiently
+ reuse an `MGLAnnotationImage`.
*/
- (nullable __kindof MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier;
@@ -1412,6 +1470,11 @@ MGL_EXPORT IB_DESIGNABLE
@param point A point expressed in the map view’s coordinate system.
@return An array of objects conforming to the `MGLFeature` protocol that
represent features in the sources used by the current style.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/select-layer/">
+ Select a feature within a layer</a> example to learn how to query an
+ `MGLMapView` object for visible `MGLFeature` objects.
*/
- (NSArray<id <MGLFeature>> *)visibleFeaturesAtPoint:(CGPoint)point NS_SWIFT_NAME(visibleFeatures(at:));
diff --git a/platform/ios/src/MGLMapViewDelegate.h b/platform/ios/src/MGLMapViewDelegate.h
index 77dd2e4ef4..9175669dc9 100644
--- a/platform/ios/src/MGLMapViewDelegate.h
+++ b/platform/ios/src/MGLMapViewDelegate.h
@@ -41,6 +41,11 @@ NS_ASSUME_NONNULL_BEGIN
method returns `YES`, this camera becomes the map view’s camera.
@return A Boolean value indicating whether the map view should stay at
`oldCamera` or change to `newCamera`.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/constraining-gestures/">
+ Restrict map panning to an area</a> example to learn how to use this method
+ and `MGLMapCamera` objects to restrict a users ability to pan your map.
*/
- (BOOL)mapView:(MGLMapView *)mapView shouldChangeFromCamera:(MGLMapCamera *)oldCamera toCamera:(MGLMapCamera *)newCamera;
@@ -72,7 +77,7 @@ NS_ASSUME_NONNULL_BEGIN
/**
Tells the delegate that the viewpoint depicted by the map view is about to change.
-
+
This method is called whenever the currently displayed map camera will start
changing for any reason.
@@ -103,12 +108,17 @@ NS_ASSUME_NONNULL_BEGIN
an animation, whether due to a user gesture or due to a call to a method such
as `-[MGLMapView setCamera:animated:]`. This method can be called before
`-mapViewDidFinishLoadingMap:` is called.
-
- During the animation, this method may be called many times to report updates to
- the viewpoint. Therefore, your implementation of this method should be as lightweight
+
+ During the animation, this method may be called many times to report updates to
+ the viewpoint. Therefore, your implementation of this method should be as lightweight
as possible to avoid affecting performance.
@param mapView The map view whose viewpoint is changing.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/clustering/">
+ Cluster point data</a> example to learn how to trigger an action whenever
+ the map region changes.
*/
- (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
@@ -137,7 +147,7 @@ NS_ASSUME_NONNULL_BEGIN
changing.
This method is called whenever the currently displayed map camera has finished
- changing, after any calls to `-mapViewRegionIsChanging:` due to animation. Therefore,
+ changing, after any calls to `-mapViewRegionIsChanging:` due to animation. Therefore,
this method can be called before `-mapViewDidFinishLoadingMap:` is called.
@param mapView The map view whose viewpoint has changed.
@@ -243,6 +253,12 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view that has just loaded a style.
@param style The style that was loaded.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/runtime-multiple-annotations/">
+ Dynamically style interactive points</a> and <a href="https://www.mapbox.com/ios-sdk/maps/examples/shape-collection/">
+ Add multiple shapes from a single shape source</a> examples to learn how to
+ ensure a map's style has loaded before modifying it at runtime.
*/
- (void)mapView:(MGLMapView *)mapView didFinishLoadingStyle:(MGLStyle *)style;
@@ -312,13 +328,13 @@ NS_ASSUME_NONNULL_BEGIN
Returns a screen coordinate at which to position the user location annotation.
This coordinate is relative to the map view’s origin after applying the map view’s
content insets.
-
+
When unimplemented, the user location annotation is aligned within the center of
the map view with respect to the content insets.
-
+
This method will override any values set by `MGLMapView.userLocationVerticalAlignment`
or `-[MGLMapView setUserLocationVerticalAlignment:]`.
-
+
@param mapView The map view that is tracking the user's location.
*/
- (CGPoint)mapViewUserLocationAnchorPoint:(MGLMapView *)mapView;
@@ -343,6 +359,14 @@ NS_ASSUME_NONNULL_BEGIN
displayed.
@return The annotation image object to display for the given annotation or
`nil` if you want to display the default marker image or an annotation view.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-models/">
+ Annotation models</a>, <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-view-image/">
+ Add annotation views and images</a>, and <a href="https://www.mapbox.com/ios-sdk/maps/examples/marker-image/">
+ Mark a place on the map with an image</a> examples to learn to specify which
+ image should be used for `MGLAnnotation` objects that have been added to
+ your map.
*/
- (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id <MGLAnnotation>)annotation;
@@ -375,6 +399,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view rendering the shape annotation.
@param annotation The annotation being rendered.
@return A color to use for the shape outline.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-models/">
+ Annotation models</a> example to learn how to modify the outline color of an
+ `MGLShape` object that has been added to your map as an annotation.
*/
- (UIColor *)mapView:(MGLMapView *)mapView strokeColorForShapeAnnotation:(MGLShape *)annotation;
@@ -390,6 +419,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view rendering the polygon annotation.
@param annotation The annotation being rendered.
@return The polygon’s interior fill color.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/polygon/">Add
+ a polygon annotation</a> example to learn how to modify the color of a an
+ `MGLPolygon` at runtime.
*/
- (UIColor *)mapView:(MGLMapView *)mapView fillColorForPolygonAnnotation:(MGLPolygon *)annotation;
@@ -402,6 +436,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view rendering the polygon annotation.
@param annotation The annotation being rendered.
@return A line width for the polyline, measured in points.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/line-geojson/">
+ Add a line annotation from GeoJSON</a> example to learn how to modify the
+ line width of an `MGLPolylineFeature` on your map.
*/
- (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotation;
@@ -429,6 +468,12 @@ NS_ASSUME_NONNULL_BEGIN
displayed.
@return The view object to display for the given annotation or `nil` if you
want to display an annotation image instead.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-view-image/">
+ Add annotation views and images</a> example to learn how to specify what
+ `MGLViewAnnotation` to use for a given `MGLPointAnnotation` object on your
+ map.
*/
- (nullable MGLAnnotationView *)mapView:(MGLMapView *)mapView viewForAnnotation:(id <MGLAnnotation>)annotation;
@@ -449,10 +494,10 @@ NS_ASSUME_NONNULL_BEGIN
/**
Returns a Boolean value indicating whether the shape annotation can be selected.
-
+
If the return value is `YES`, the user can select the annotation by tapping
on it. If the delegate does not implement this method, the default value is `YES`.
-
+
@param mapView The map view that has selected the annotation.
@param annotation The object representing the shape annotation.
@return A Boolean value indicating whether the annotation can be selected.
@@ -470,6 +515,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view containing the annotation.
@param annotation The annotation that was selected.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/runtime-multiple-annotations/">
+ Dynamically style interactive points</a> example to learn how to remove an
+ annotation view if it has already been selected.
*/
- (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id <MGLAnnotation>)annotation;
@@ -544,6 +594,13 @@ NS_ASSUME_NONNULL_BEGIN
@param annotation The object representing the annotation.
@return A Boolean value indicating whether the annotation should show a
callout.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/annotation-view-image/">
+ Add annotation views and images</a>, <a href="https://www.mapbox.com/ios-sdk/maps/examples/custom-callout/">
+ Display custom views as callouts</a>, and <a href="https://www.mapbox.com/ios-sdk/maps/examples/default-callout/">
+ Default callout usage</a> examples to learn how to show callouts for
+ `MGLAnnotation` objects.
*/
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation;
@@ -561,6 +618,11 @@ NS_ASSUME_NONNULL_BEGIN
@param annotation The object representing the annotation.
@return A view conforming to the `MGLCalloutView` protocol, or `nil` to use the
default callout view.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/custom-callout/">
+ Display custom views as callouts</a> example to learn how to customize an
+ `MGLAnnotation` object's `MGLCalloutView`.
*/
- (nullable id <MGLCalloutView>)mapView:(MGLMapView *)mapView calloutViewForAnnotation:(id <MGLAnnotation>)annotation;
@@ -587,6 +649,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view presenting the annotation callout.
@param annotation The object representing the annotation with the callout.
@return The accessory view to display.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/default-callout/">
+ Default callout usage</a> example to learn how to modify the view that is
+ displayed on the left side of the standard callout bubble.
*/
- (nullable UIView *)mapView:(MGLMapView *)mapView leftCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
@@ -613,6 +680,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view presenting the annotation callout.
@param annotation The object representing the annotation with the callout.
@return The accessory view to display.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/default-callout/">
+ Default callout usage</a> example to learn how to modify the view that is
+ displayed on the right side of the standard callout bubble.
*/
- (nullable UIView *)mapView:(MGLMapView *)mapView rightCalloutAccessoryViewForAnnotation:(id <MGLAnnotation>)annotation;
@@ -638,6 +710,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view containing the specified annotation.
@param annotation The annotation whose accessory view was tapped.
@param control The control that was tapped.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/default-callout/">
+ Default callout usage</a> example to learn how to trigger an action when the
+ standard callout bubble's accessory control is tapped.
*/
- (void)mapView:(MGLMapView *)mapView annotation:(id <MGLAnnotation>)annotation calloutAccessoryControlTapped:(UIControl *)control;
@@ -656,6 +733,11 @@ NS_ASSUME_NONNULL_BEGIN
@param mapView The map view containing the specified annotation.
@param annotation The annotation whose callout was tapped.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/custom-callout/">
+ Display custom views as callouts</a> example to learn how to trigger an
+ action when an `MGLAnnotation`s `MGLCalloutView` is tapped.
*/
- (void)mapView:(MGLMapView *)mapView tapOnCalloutForAnnotation:(id <MGLAnnotation>)annotation;
diff --git a/platform/ios/src/MGLUserLocation.h b/platform/ios/src/MGLUserLocation.h
index 4e01cf00c9..de720d9050 100644
--- a/platform/ios/src/MGLUserLocation.h
+++ b/platform/ios/src/MGLUserLocation.h
@@ -11,6 +11,9 @@ NS_ASSUME_NONNULL_BEGIN
the user’s current location. You do not create instances of this class
directly. Instead, you retrieve an existing `MGLUserLocation` object from the
`userLocation` property of the map view displayed in your application.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/user-location-annotation/">Customize the user location annotation</a> example to learn how to overide the default user location annotation.
*/
MGL_EXPORT
@interface MGLUserLocation : NSObject <MGLAnnotation, NSSecureCoding>
diff --git a/platform/ios/src/MGLUserLocationAnnotationView.h b/platform/ios/src/MGLUserLocationAnnotationView.h
index 4d95f39cf3..573fb9f95f 100644
--- a/platform/ios/src/MGLUserLocationAnnotationView.h
+++ b/platform/ios/src/MGLUserLocationAnnotationView.h
@@ -25,6 +25,11 @@ MGL_EXPORT
The value of this property is nil during initialization and while user tracking
is inactive.
+
+ #### Related examples
+ See the <a href="https://www.mapbox.com/ios-sdk/maps/examples/user-location-annotation/">
+ Customize the user location annotation</a> example to learn how to customize
+ the default user location annotation object.
*/
@property (nonatomic, readonly, weak, nullable) MGLUserLocation *userLocation;