diff options
Diffstat (limited to 'platform/ios/src')
| -rw-r--r-- | platform/ios/src/MGLAnnotationImage.h | 5 | ||||
| -rw-r--r-- | platform/ios/src/MGLAnnotationView.h | 10 | ||||
| -rw-r--r-- | platform/ios/src/MGLCalloutView.h | 5 | ||||
| -rw-r--r-- | platform/ios/src/MGLMapView.h | 67 | ||||
| -rw-r--r-- | platform/ios/src/MGLMapViewDelegate.h | 102 | ||||
| -rw-r--r-- | platform/ios/src/MGLUserLocation.h | 3 | ||||
| -rw-r--r-- | platform/ios/src/MGLUserLocationAnnotationView.h | 5 |
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; |