diff options
Diffstat (limited to 'platform')
| -rw-r--r-- | platform/darwin/src/MGLAnnotation.h | 21 | ||||
| -rw-r--r-- | platform/darwin/src/MGLGeometry.h | 28 | ||||
| -rw-r--r-- | platform/darwin/src/MGLMapCamera.h | 38 | ||||
| -rw-r--r-- | platform/darwin/src/MGLMultiPoint.h | 19 | ||||
| -rw-r--r-- | platform/darwin/src/MGLOverlay.h | 37 | ||||
| -rw-r--r-- | platform/darwin/src/MGLPointAnnotation.h | 11 | ||||
| -rw-r--r-- | platform/darwin/src/MGLPolygon.h | 13 | ||||
| -rw-r--r-- | platform/darwin/src/MGLPolyline.h | 13 | ||||
| -rw-r--r-- | platform/darwin/src/MGLShape.h | 22 | ||||
| -rw-r--r-- | platform/darwin/src/MGLStyle.h | 96 | ||||
| -rw-r--r-- | platform/darwin/test/MGLStyleTests.mm | 2 | ||||
| -rw-r--r-- | platform/osx/src/MGLAnnotationImage.h | 70 | ||||
| -rw-r--r-- | platform/osx/src/MGLMapView.h | 1088 | ||||
| -rw-r--r-- | platform/osx/src/MGLMapViewDelegate.h | 307 | ||||
| -rw-r--r-- | platform/osx/src/Mapbox.h | 48 |
15 files changed, 1039 insertions, 774 deletions
diff --git a/platform/darwin/src/MGLAnnotation.h b/platform/darwin/src/MGLAnnotation.h index e4726f9503..7293aeec4f 100644 --- a/platform/darwin/src/MGLAnnotation.h +++ b/platform/darwin/src/MGLAnnotation.h @@ -7,15 +7,26 @@ NS_ASSUME_NONNULL_BEGIN /** - The `MGLAnnotation` protocol is used to provide annotation-related information to a map view. To use this protocol, you adopt it in any custom objects that store or represent annotation data. Each object then serves as the source of information about a single map annotation and provides critical information, such as the annotation’s location on the map. Annotation objects do not provide the visual representation of the annotation but typically coordinate (in conjunction with the map view’s delegate) the creation of an appropriate objects to handle the display. + The `MGLAnnotation` protocol is used to provide annotation-related information + to a map view. To use this protocol, you adopt it in any custom objects that + store or represent annotation data. Each object then serves as the source of + information about a single map annotation and provides critical information, + such as the annotation’s location on the map. Annotation objects do not provide + the visual representation of the annotation but typically coordinate (in + conjunction with the map view’s delegate) the creation of an appropriate + objects to handle the display. - An object that adopts this protocol must implement the `coordinate` property. The other methods of this protocol are optional. + An object that adopts this protocol must implement the `coordinate` property. + The other methods of this protocol are optional. */ @protocol MGLAnnotation <NSObject> #pragma mark Position Attributes -/** The center point (specified as a map coordinate) of the annotation. (required) (read-only) */ +/** + The center point (specified as a map coordinate) of the annotation. (required) + (read-only) + */ @property (nonatomic, readonly) CLLocationCoordinate2D coordinate; @optional @@ -25,7 +36,9 @@ NS_ASSUME_NONNULL_BEGIN /** The string containing the annotation’s title. - Although this property is optional, if you support the selection of annotations in your map view, you are expected to provide this property. This string is displayed in the callout for the associated annotation. + Although this property is optional, if you support the selection of annotations + in your map view, you are expected to provide this property. This string is + displayed in the callout for the associated annotation. */ @property (nonatomic, readonly, copy, nullable) NSString *title; diff --git a/platform/darwin/src/MGLGeometry.h b/platform/darwin/src/MGLGeometry.h index 7ad5140400..af54d7b391 100644 --- a/platform/darwin/src/MGLGeometry.h +++ b/platform/darwin/src/MGLGeometry.h @@ -14,7 +14,10 @@ typedef struct MGLCoordinateSpan { CLLocationDegrees longitudeDelta; } MGLCoordinateSpan; -/** Creates a new `MGLCoordinateSpan` from the given latitudinal and longitudinal deltas. */ +/** + Creates a new `MGLCoordinateSpan` from the given latitudinal and longitudinal + deltas. + */ NS_INLINE MGLCoordinateSpan MGLCoordinateSpanMake(CLLocationDegrees latitudeDelta, CLLocationDegrees longitudeDelta) { MGLCoordinateSpan span; span.latitudeDelta = latitudeDelta; @@ -22,7 +25,10 @@ NS_INLINE MGLCoordinateSpan MGLCoordinateSpanMake(CLLocationDegrees latitudeDelt return span; } -/** Returns `YES` if the two coordinate spans represent the same latitudinal change and the same longitudinal change. */ +/** + Returns `YES` if the two coordinate spans represent the same latitudinal change + and the same longitudinal change. + */ NS_INLINE BOOL MGLCoordinateSpanEqualToCoordinateSpan(MGLCoordinateSpan span1, MGLCoordinateSpan span2) { return (span1.latitudeDelta == span2.latitudeDelta && span1.longitudeDelta == span2.longitudeDelta); @@ -39,7 +45,10 @@ typedef struct MGLCoordinateBounds { CLLocationCoordinate2D ne; } MGLCoordinateBounds; -/** Creates a new `MGLCoordinateBounds` structure from the given southwest and northeast coordinates. */ +/** + Creates a new `MGLCoordinateBounds` structure from the given southwest and + northeast coordinates. + */ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsMake(CLLocationCoordinate2D sw, CLLocationCoordinate2D ne) { MGLCoordinateBounds bounds; bounds.sw = sw; @@ -61,7 +70,10 @@ NS_INLINE MGLCoordinateSpan MGLCoordinateBoundsGetCoordinateSpan(MGLCoordinateBo bounds.ne.longitude - bounds.sw.longitude); } -/** Returns a coordinate bounds with southwest and northeast coordinates that are offset from those of the source bounds. */ +/** + Returns a coordinate bounds with southwest and northeast coordinates that are + offset from those of the source bounds. + */ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsOffset(MGLCoordinateBounds bounds, MGLCoordinateSpan offset) { MGLCoordinateBounds offsetBounds = bounds; offsetBounds.sw.latitude += offset.latitudeDelta; @@ -71,8 +83,12 @@ NS_INLINE MGLCoordinateBounds MGLCoordinateBoundsOffset(MGLCoordinateBounds boun return offsetBounds; } -/** Returns `YES` if the coordinate bounds covers no area. - Note that a bounds may be empty but have a non-zero coordinate span (e.g., when its northeast point lies due north of its southwest point). */ +/** + Returns `YES` if the coordinate bounds covers no area. + + @note A bounds may be empty but have a non-zero coordinate span (e.g., when its + northeast point lies due north of its southwest point). + */ NS_INLINE BOOL MGLCoordinateBoundsIsEmpty(MGLCoordinateBounds bounds) { MGLCoordinateSpan span = MGLCoordinateBoundsGetCoordinateSpan(bounds); return span.latitudeDelta == 0 || span.longitudeDelta == 0; diff --git a/platform/darwin/src/MGLMapCamera.h b/platform/darwin/src/MGLMapCamera.h index 3cb902ba52..4b50c32b2f 100644 --- a/platform/darwin/src/MGLMapCamera.h +++ b/platform/darwin/src/MGLMapCamera.h @@ -6,7 +6,10 @@ NS_ASSUME_NONNULL_BEGIN -/** An `MGLMapCamera` object represents a viewpoint from which the user observes some point on an `MGLMapView`. */ +/** + An `MGLMapCamera` object represents a viewpoint from which the user observes + some point on an `MGLMapView`. + */ @interface MGLMapCamera : NSObject <NSSecureCoding, NSCopying> /** Coordinate at the center of the map view. */ @@ -15,7 +18,10 @@ NS_ASSUME_NONNULL_BEGIN /** Heading measured in degrees clockwise from true north. */ @property (nonatomic) CLLocationDirection heading; -/** Pitch toward the horizon measured in degrees, with 0 degrees resulting in a two-dimensional map. */ +/** + Pitch toward the horizon measured in degrees, with 0 degrees resulting in a + two-dimensional map. + */ @property (nonatomic) CGFloat pitch; /** Meters above ground level. */ @@ -25,11 +31,16 @@ NS_ASSUME_NONNULL_BEGIN + (instancetype)camera; /** - Returns a new camera using based on information about the camera’s viewpoint and focus point. + Returns a new camera using based on information about the camera’s viewpoint + and focus point. - @param centerCoordinate The geographic coordinate on which the map should be centered. - @param eyeCoordinate The geometric coordinate at which the camera should be situated. - @param eyeAltitude The altitude (measured in meters) above the map at which the camera should be situated. The altitude may be less than the distance from the camera’s viewpoint to the camera’s focus point. + @param centerCoordinate The geographic coordinate on which the map should be + centered. + @param eyeCoordinate The geometric coordinate at which the camera should be + situated. + @param eyeAltitude The altitude (measured in meters) above the map at which the + camera should be situated. The altitude may be less than the distance from + the camera’s viewpoint to the camera’s focus point. */ + (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate fromEyeCoordinate:(CLLocationCoordinate2D)eyeCoordinate @@ -38,10 +49,17 @@ NS_ASSUME_NONNULL_BEGIN /** Returns a new camera with the given distance, pitch, and heading. - @param centerCoordinate The geographic coordinate on which the map should be centered. - @param distance The straight-line distance from the viewpoint to the `centerCoordinate`. - @param pitch The viewing angle of the camera, measured in degrees. A value of `0` results in a camera pointed straight down at the map. Angles greater than `0` result in a camera angled toward the horizon. - @param heading The camera’s heading, measured in degrees clockwise from true north. A value of `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. + @param centerCoordinate The geographic coordinate on which the map should be + centered. + @param distance The straight-line distance from the viewpoint to the + `centerCoordinate`. + @param pitch The viewing angle of the camera, measured in degrees. A value of + `0` results in a camera pointed straight down at the map. Angles greater + than `0` result in a camera angled toward the horizon. + @param heading The camera’s heading, measured in degrees clockwise from true + north. A value of `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. */ + (instancetype)cameraLookingAtCenterCoordinate:(CLLocationCoordinate2D)centerCoordinate fromDistance:(CLLocationDistance)distance diff --git a/platform/darwin/src/MGLMultiPoint.h b/platform/darwin/src/MGLMultiPoint.h index ad9db1e681..041c52e8f2 100644 --- a/platform/darwin/src/MGLMultiPoint.h +++ b/platform/darwin/src/MGLMultiPoint.h @@ -7,7 +7,14 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLMultiPoint` class is an abstract superclass used to define shapes composed of multiple points. You should not create instances of this class directly. Instead, you should create instances of the `MGLPolyline` or `MGLPolygon` classes. However, you can use the method and properties of this class to access information about the specific points associated with the line or polygon. */ +/** + The `MGLMultiPoint` class is an abstract superclass used to define shapes + composed of multiple points. You should not create instances of this class + directly. Instead, you should create instances of the `MGLPolyline` or + `MGLPolygon` classes. However, you can use the method and properties of this + class to access information about the specific points associated with the line + or polygon. + */ @interface MGLMultiPoint : MGLShape /** The number of points associated with the shape. (read-only) */ @@ -16,8 +23,14 @@ NS_ASSUME_NONNULL_BEGIN /** Retrieves one or more coordinates associated with the shape. - @param coords On input, you must provide a C array of structures large enough to hold the desired number of coordinates. On output, this structure contains the requested coordinate data. - @param range The range of points you want. The `location` field indicates the first point you are requesting, with `0` being the first point, `1` being the second point, and so on. The `length` field indicates the number of points you want. The array in _`coords`_ must be large enough to accommodate the number of requested coordinates. + @param coords On input, you must provide a C array of structures large enough + to hold the desired number of coordinates. On output, this structure + contains the requested coordinate data. + @param range The range of points you want. The `location` field indicates the + first point you are requesting, with `0` being the first point, `1` being + the second point, and so on. The `length` field indicates the number of + points you want. The array in _`coords`_ must be large enough to accommodate + the number of requested coordinates. */ - (void)getCoordinates:(CLLocationCoordinate2D *)coords range:(NSRange)range; diff --git a/platform/darwin/src/MGLOverlay.h b/platform/darwin/src/MGLOverlay.h index aa80fe3900..ba03b19737 100644 --- a/platform/darwin/src/MGLOverlay.h +++ b/platform/darwin/src/MGLOverlay.h @@ -9,35 +9,56 @@ NS_ASSUME_NONNULL_BEGIN /** - The `MGLOverlay` protocol defines a specific type of annotation that represents both a point and an area on a map. Overlay objects are essentially data objects that contain the geographic data needed to represent the map area. For example, overlays can take the form of common shapes such as rectangles and circles. They can also describe polygons and other complex shapes. + The `MGLOverlay` protocol defines a specific type of annotation that represents + both a point and an area on a map. Overlay objects are essentially data objects + that contain the geographic data needed to represent the map area. For example, + overlays can take the form of common shapes such as rectangles and circles. + They can also describe polygons and other complex shapes. - You use overlays to layer more sophisticated content on top of a map view. For example, you could use an overlay to show the boundaries of a national park or trace a bus route along city streets. The Mapbox iOS SDK defines several concrete classes that conform to this protocol and define standard shapes. + You use overlays to layer more sophisticated content on top of a map view. For + example, you could use an overlay to show the boundaries of a national park or + trace a bus route along city streets. This SDK defines several concrete classes + that conform to this protocol and define standard shapes. - Because overlays are also annotations, they have similar usage pattern to annotations. When added to a map view using the `-addOverlay:` method, that view detects whenever the overlay’s defined region intersects the visible portion of the map. At that point, the map view asks its delegate to provide a special overlay view to draw the visual representation of the overlay. If you add an overlay to a map view as an annotation instead, it is treated as an annotation with a single point. + Because overlays are also annotations, they have similar usage pattern to + annotations. When added to a map view using the `-addOverlay:` method, that + view detects whenever the overlay’s defined region intersects the visible + portion of the map. At that point, the map view asks its delegate to provide a + special overlay view to draw the visual representation of the overlay. If you + add an overlay to a map view as an annotation instead, it is treated as an + annotation with a single point. */ @protocol MGLOverlay <MGLAnnotation> /** The approximate center point of the overlay area. (required) (read-only) - This point is typically set to the center point of the map’s bounding rectangle. It is used as the anchor point for any callouts displayed for the annotation. + This point is typically set to the center point of the map’s bounding + rectangle. It is used as the anchor point for any callouts displayed for the + annotation. */ @property (nonatomic, readonly) CLLocationCoordinate2D coordinate; /** The cooordinate rectangle that encompasses the overlay. (required) (read-only) - This property contains the smallest rectangle that completely encompasses the overlay. Implementers of this protocol must set this area when implementing their overlay class, and after setting it, you must not change it. + This property contains the smallest rectangle that completely encompasses the + overlay. Implementers of this protocol must set this area when implementing + their overlay class, and after setting it, you must not change it. */ @property (nonatomic, readonly) MGLCoordinateBounds overlayBounds; /** - Returns a Boolean indicating whether the specified rectangle intersects the receiver’s shape. + Returns a Boolean indicating whether the specified rectangle intersects the + receiver’s shape. - You can implement this method to provide more specific bounds checking for an overlay. If you do not implement it, the bounding rectangle is used to detect intersections. + You can implement this method to provide more specific bounds checking for an + overlay. If you do not implement it, the bounding rectangle is used to detect + intersections. @param overlayBounds The rectangle to intersect with the receiver’s area. - @return `YES` if any part of the map rectangle intersects the receiver’s shape or `NO` if it does not. + @return `YES` if any part of the map rectangle intersects the receiver’s shape + or `NO` if it does not. */ - (BOOL)intersectsOverlayBounds:(MGLCoordinateBounds)overlayBounds; diff --git a/platform/darwin/src/MGLPointAnnotation.h b/platform/darwin/src/MGLPointAnnotation.h index d186cbff18..13afcab717 100644 --- a/platform/darwin/src/MGLPointAnnotation.h +++ b/platform/darwin/src/MGLPointAnnotation.h @@ -7,10 +7,17 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLPointAnnotation` class defines a concrete annotation object located at a specified point. You can use this class, rather than define your own, in situations where all you want to do is associate a point on the map with a title. */ +/** + The `MGLPointAnnotation` class defines a concrete annotation object located at + a specified point. You can use this class, rather than define your own, in + situations where all you want to do is associate a point on the map with a + title. + */ @interface MGLPointAnnotation : MGLShape -/** The coordinate point of the annotation, specified as a latitude and longitude. */ +/** + The coordinate point of the annotation, specified as a latitude and longitude. + */ @property (nonatomic, assign) CLLocationCoordinate2D coordinate; @end diff --git a/platform/darwin/src/MGLPolygon.h b/platform/darwin/src/MGLPolygon.h index c5480264fb..1a158874bb 100644 --- a/platform/darwin/src/MGLPolygon.h +++ b/platform/darwin/src/MGLPolygon.h @@ -8,13 +8,20 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLPolygon` class represents a shape consisting of one or more points that define a closed polygon. The points are connected end-to-end in the order they are provided. The first and last points are connected to each other to create the closed shape. */ +/** + The `MGLPolygon` class represents a shape consisting of one or more points that + define a closed polygon. The points are connected end-to-end in the order they + are provided. The first and last points are connected to each other to create + the closed shape. + */ @interface MGLPolygon : MGLMultiPoint <MGLOverlay> /** - Creates and returns an `MGLPolygon` object from the specified set of coordinates. + Creates and returns an `MGLPolygon` object from the specified set of + coordinates. - @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. + @param coords The array of coordinates defining the shape. The data in this + array is copied to the new object. @param count The number of items in the `coords` array. @return A new polygon object. */ diff --git a/platform/darwin/src/MGLPolyline.h b/platform/darwin/src/MGLPolyline.h index c28299c7e0..5e45513735 100644 --- a/platform/darwin/src/MGLPolyline.h +++ b/platform/darwin/src/MGLPolyline.h @@ -8,13 +8,20 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLPolyline` class represents a shape consisting of one or more points that define connecting line segments. The points are connected end-to-end in the order they are provided. The first and last points are not connected to each other. */ +/** + The `MGLPolyline` class represents a shape consisting of one or more points + that define connecting line segments. The points are connected end-to-end in + the order they are provided. The first and last points are not connected to + each other. + */ @interface MGLPolyline : MGLMultiPoint <MGLOverlay> /** - Creates and returns an `MGLPolyline` object from the specified set of coordinates. + Creates and returns an `MGLPolyline` object from the specified set of + coordinates. - @param coords The array of coordinates defining the shape. The data in this array is copied to the new object. + @param coords The array of coordinates defining the shape. The data in this + array is copied to the new object. @param count The number of items in the `coords` array. @return A new polyline object. */ diff --git a/platform/darwin/src/MGLShape.h b/platform/darwin/src/MGLShape.h index c1b84816f2..40c92fc32d 100644 --- a/platform/darwin/src/MGLShape.h +++ b/platform/darwin/src/MGLShape.h @@ -6,18 +6,32 @@ NS_ASSUME_NONNULL_BEGIN -/** The `MGLShape` class is an abstract class that defines the basic properties for all shape-based annotation objects. This class must be subclassed and cannot be used as is. Subclasses are responsible for defining the geometry of the shape and providing an appropriate value for the coordinate property inherited from the `MGLAnnotation` protocol. */ +/** + The `MGLShape` class is an abstract class that defines the basic properties for + all shape-based annotation objects. This class must be subclassed and cannot be + used as is. Subclasses are responsible for defining the geometry of the shape + and providing an appropriate value for the coordinate property inherited from + the `MGLAnnotation` protocol. + */ @interface MGLShape : NSObject <MGLAnnotation> -/** The title of the shape annotation. The default value of this property is `nil`. */ +/** + The title of the shape annotation. The default value of this property is `nil`. + */ @property (nonatomic, copy, nullable) NSString *title; -/** The subtitle of the shape annotation. The default value of this property is `nil`. */ +/** + The subtitle of the shape annotation. The default value of this property is + `nil`. + */ @property (nonatomic, copy, nullable) NSString *subtitle; #if !TARGET_OS_IPHONE -/** The tooltip of the shape annotation. The default value of this property is `nil`. */ +/** + The tooltip of the shape annotation. The default value of this property is + `nil`. + */ @property (nonatomic, copy, nullable) NSString *toolTip; #endif diff --git a/platform/darwin/src/MGLStyle.h b/platform/darwin/src/MGLStyle.h index 65d45dc98e..8577522b96 100644 --- a/platform/darwin/src/MGLStyle.h +++ b/platform/darwin/src/MGLStyle.h @@ -5,116 +5,156 @@ NS_ASSUME_NONNULL_BEGIN /** - A version number identifying the default version of the suite of default styles provided by Mapbox. This version number may be passed into one of the “StyleURLWithVersion” class methods of MGLStyle. - - The value of this constant generally corresponds to the latest released version as of the date on which this SDK was published. You can use this constant to ascertain the style used by `MGLMapView` and `MGLTilePyramidOfflineRegion` when no style URL is specified. Consult the <a href="https://www.mapbox.com/api-documentation/#styles">Mapbox Styles API documentation</a> for the most up-to-date style versioning information. - - @warning The value of this constant may change in a future release of the SDK. If you use any feature that depends on a specific aspect of a default style – for instance, the minimum zoom level that includes roads – you may use the current value of this constant or the underlying style URL, but do not use the constant itself. Such details may change significantly from version to version. + A version number identifying the default version of the suite of default styles + provided by Mapbox. This version number may be passed into one of the + “StyleURLWithVersion” class methods of MGLStyle. + + The value of this constant generally corresponds to the latest released version + as of the date on which this SDK was published. You can use this constant to + ascertain the style used by `MGLMapView` and `MGLTilePyramidOfflineRegion` when + no style URL is specified. Consult the + <a href="https://www.mapbox.com/api-documentation/#styles">Mapbox Styles API documentation</a> + for the most up-to-date style versioning information. + + @warning The value of this constant may change in a future release of the SDK. + If you use any feature that depends on a specific aspect of a default style + – for instance, the minimum zoom level that includes roads – you may use the + current value of this constant or the underlying style URL, but do not use + the constant itself. Such details may change significantly from version to + version. */ static const NSInteger MGLStyleDefaultVersion = 9; /** - A collection of convenience methods for creating style URLs of default styles provided by Mapbox. <a href="https://www.mapbox.com/maps/">Learn more about Mapbox default styles</a>. + A collection of convenience methods for creating style URLs of default styles + provided by Mapbox. + <a href="https://www.mapbox.com/maps/">Learn more about Mapbox default styles</a>. */ @interface MGLStyle : NSObject /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style. Streets is a general-purpose style with detailed road and transit networks. - `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style is specified explicitly. + `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style + is specified explicitly. */ + (NSURL *)streetsStyleURL __attribute__((deprecated("Use -streetsStyleURLWithVersion:."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/streets/">Mapbox Streets</a> style. Streets is a general-purpose style with detailed road and transit networks. - `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style is specified explicitly. + `MGLMapView` and `MGLTilePyramidOfflineRegion` use Mapbox Streets when no style + is specified explicitly. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)streetsStyleURLWithVersion:(NSInteger)version; /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/blog/emerald-gl/">Mapbox Emerald</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/blog/emerald-gl/">Mapbox Emerald</a> style. Emerald is a tactile style with subtle textures and dramatic hillshading. */ + (NSURL *)emeraldStyleURL __attribute__((deprecated("Create an NSURL object with the string “mapbox://styles/mapbox/emerald-v8”."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/outdoors/">Mapbox Outdoors</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/outdoors/">Mapbox Outdoors</a> style. Outdoors is a general-purpose style tailored to outdoor activities. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)outdoorsStyleURLWithVersion:(NSInteger)version; /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style. Light is a subtle, light-colored backdrop for data visualizations. */ + (NSURL *)lightStyleURL __attribute__((deprecated("Use -lightStyleURLWithVersion:."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Light</a> style. Light is a subtle, light-colored backdrop for data visualizations. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)lightStyleURLWithVersion:(NSInteger)version; /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style. Dark is a subtle, dark-colored backdrop for data visualizations. */ + (NSURL *)darkStyleURL __attribute__((deprecated("Use -darkStyleURLWithVersion:."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/light-dark/">Mapbox Dark</a> style. Dark is a subtle, dark-colored backdrop for data visualizations. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)darkStyleURLWithVersion:(NSInteger)version; /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style. Satellite is high-resolution satellite and aerial imagery. */ + (NSURL *)satelliteStyleURL __attribute__((deprecated("Use -satelliteStyleURLWithVersion:."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite</a> style. Satellite is high-resolution satellite and aerial imagery. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)satelliteStyleURLWithVersion:(NSInteger)version; /** - Returns the URL to version 8 of the <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite Streets</a> style. + Returns the URL to version 8 of the + <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite Streets</a> + style. - Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets. + Satellite Streets combines the high-resolution satellite and aerial imagery of + Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox + Streets. */ + (NSURL *)hybridStyleURL __attribute__((deprecated("Use -satelliteStreetsStyleURLWithVersion:."))); /** - Returns the URL to the given version of the <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite Streets</a> style. + Returns the URL to the given version of the + <a href="https://www.mapbox.com/maps/satellite/">Mapbox Satellite Streets</a> + style. - Satellite Streets combines the high-resolution satellite and aerial imagery of Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox Streets. + Satellite Streets combines the high-resolution satellite and aerial imagery of + Mapbox Satellite with unobtrusive labels and translucent roads from Mapbox + Streets. - @param version The style’s latest released version. As of publication, the current version is `9`. + @param version The style’s latest released version. As of publication, the + current version is `9`. */ + (NSURL *)satelliteStreetsStyleURLWithVersion:(NSInteger)version; diff --git a/platform/darwin/test/MGLStyleTests.mm b/platform/darwin/test/MGLStyleTests.mm index 8c42417aba..363017dffe 100644 --- a/platform/darwin/test/MGLStyleTests.mm +++ b/platform/darwin/test/MGLStyleTests.mm @@ -74,7 +74,7 @@ // Test that “current version is” statements are present and current for all versioned style methods. NSError *versionError; - NSString *versionExpressionString = @(R"RE(the current version is `(\d+)`)RE"); + NSString *versionExpressionString = @(R"RE(current version is `(\d+)`)RE"); NSRegularExpression *versionExpression = [NSRegularExpression regularExpressionWithPattern:versionExpressionString options:0 error:&versionError]; XCTAssertNil(versionError, @"Error compiling regular expression to search for current version statements."); NSUInteger numVersionDeclarations = [versionExpression numberOfMatchesInString:styleHeader options:0 range:NSMakeRange(0, styleHeader.length)]; diff --git a/platform/osx/src/MGLAnnotationImage.h b/platform/osx/src/MGLAnnotationImage.h index a33ea75a5e..ad44993ee1 100644 --- a/platform/osx/src/MGLAnnotationImage.h +++ b/platform/osx/src/MGLAnnotationImage.h @@ -4,53 +4,59 @@ NS_ASSUME_NONNULL_BEGIN -/** The MGLAnnotationImage class is responsible for presenting point-based - annotations visually on an MGLMapView instance. Annotation image objects - pair NSImage objects with annotation-related metadata. They may be recycled - later and put into a reuse queue that is maintained by the map view. */ +/** + The `MGLAnnotationImage` class is responsible for presenting point-based + annotations visually on an `MGLMapView` instance. Annotation image objects pair + `NSImage` objects with annotation-related metadata. They may be recycled later + and put into a reuse queue that is maintained by the map view. + */ @interface MGLAnnotationImage : NSObject -#pragma mark Initializing and preparing the image object -/** @name Initializing and Preparing the Image Object */ +#pragma mark Initializing and Preparing the Image Object -/** Initializes and returns a new annotation image object. - - @param image The image to display for the annotation. - @param reuseIdentifier The string that identifies this annotation image in - the reuse queue. - @return The initialized annotation image object or `nil` if there was a - problem initializing the object. */ +/** + Initializes and returns a new annotation image object. + + @param image The image to display for the annotation. + @param reuseIdentifier The string that identifies this annotation image in the + reuse queue. + @return The initialized annotation image object or `nil` if there was a problem + initializing the object. + */ + (instancetype)annotationImageWithImage:(NSImage *)image reuseIdentifier:(NSString *)reuseIdentifier; -#pragma mark Getting and setting attributes -/** @name Getting and Setting Attributes */ +#pragma mark Getting and Setting Attributes /** The image to display for the annotation. */ @property (nonatomic, readonly) NSImage *image; -/** The string that identifies this annotation image in the reuse queue. - (read-only) - - You specify the reuse identifier when you create the image object. You use - this type later to retrieve an annotation image object that was created - previously but which is currently unused because its annotation is not - on-screen. - - If you define distinctly different types of annotations (with distinctly - different annotation images to go with them), you can differentiate between - the annotation types by specifying different reuse identifiers for each one. +/** + The string that identifies this annotation image in the reuse queue. + (read-only) + + You specify the reuse identifier when you create the image object. You use this + type later to retrieve an annotation image object that was created previously + but which is currently unused because its annotation is not on-screen. + + If you define distinctly different types of annotations (with distinctly + different annotation images to go with them), you can differentiate between the + annotation types by specifying different reuse identifiers for each one. */ @property (nonatomic, readonly) NSString *reuseIdentifier; -/** A Boolean value indicating whether the annotation is selectable. - - The default value of this property is `YES`. If the value of this property - is `NO`, the annotation image ignores click events and cannot be selected. +/** + A Boolean value indicating whether the annotation is selectable. + + The default value of this property is `YES`. If the value of this property is + `NO`, the annotation image ignores click events and cannot be selected. */ @property (nonatomic, getter=isSelectable) BOOL selectable; -/** The cursor that appears above any annotation using this annotation image. By - default, this property is set to `nil`, representing the current cursor. */ +/** + The cursor that appears above any annotation using this annotation image. + + By default, this property is set to `nil`, representing the current cursor. + */ @property (nonatomic, nullable) NSCursor *cursor; @end diff --git a/platform/osx/src/MGLMapView.h b/platform/osx/src/MGLMapView.h index a8fd24ab5b..3a64dde7d5 100644 --- a/platform/osx/src/MGLMapView.h +++ b/platform/osx/src/MGLMapView.h @@ -29,645 +29,727 @@ typedef NS_OPTIONS(NSUInteger, MGLMapDebugMaskOptions) { @protocol MGLMapViewDelegate; @protocol MGLOverlay; -/** 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 - <a href="https://github.com/mapbox/vector-tile-spec">Mapbox Vector Tile Specification</a>. - It styles them with a style that conforms to the - <a href="https://www.mapbox.com/mapbox-gl-style-spec/">Mapbox GL style specification</a>. - Such styles can be designed in - <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on - mapbox.com. - - A collection of Mapbox-hosted styles is available through the MGLStyle - class. These basic styles use - <a href="https://www.mapbox.com/developers/vector-tiles/mapbox-streets">Mapbox Streets</a> - or <a href="https://www.mapbox.com/satellite/">Mapbox Satellite</a> data - sources, but you can specify a custom style that makes use of your own data. - - Mapbox-hosted vector tiles and styles require an API access token, which you - can obtain from the - <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>. - Access tokens associate requests to Mapbox’s vector tile and style APIs with - your Mapbox account. They also deter other developers from using your styles - without your permission. - - @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. */ +/** + 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 + <a href="https://github.com/mapbox/vector-tile-spec">Mapbox Vector Tile Specification</a>. + It styles them with a style that conforms to the + <a href="https://www.mapbox.com/mapbox-gl-style-spec/">Mapbox GL style specification</a>. + Such styles can be designed in + <a href="https://www.mapbox.com/studio/">Mapbox Studio</a> and hosted on + mapbox.com. + + A collection of Mapbox-hosted styles is available through the `MGLStyle` class. + These basic styles use + <a href="https://www.mapbox.com/developers/vector-tiles/mapbox-streets">Mapbox Streets</a> + or <a href="https://www.mapbox.com/satellite/">Mapbox Satellite</a> data + sources, but you can specify a custom style that makes use of your own data. + + Mapbox-hosted vector tiles and styles require an API access token, which you + can obtain from the + <a href="https://www.mapbox.com/studio/account/tokens/">Mapbox account page</a>. + Access tokens associate requests to Mapbox’s vector tile and style APIs with + your Mapbox account. They also deter other developers from using your styles + without your permission. + + @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. + */ IB_DESIGNABLE @interface MGLMapView : NSView -#pragma mark Creating instances -/** @name Creating Instances */ +#pragma mark Creating Instances -/** Initializes and returns a newly allocated map view with the specified frame - and the default style. - - @param frame The frame for the view, measured in points. - @return An initialized map view. */ +/** + Initializes and returns a newly allocated map view with the specified frame and + the default style. + + @param frame The frame for the view, measured in points. + @return An initialized map view. + */ - (instancetype)initWithFrame:(NSRect)frame; -/** Initializes and returns a newly allocated map view with the specified frame - and style URL. - - @param frame The frame for the view, measured in points. - @param styleURL URL of the map style to display. The URL may be a full HTTP - or HTTPS URL, a Mapbox URL indicating the style’s map ID - (`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. */ +/** + Initializes and returns a newly allocated map view with the specified frame and + style URL. + + @param frame The frame for the view, measured in points. + @param styleURL URL of the map style to display. The URL may be a full HTTP or + HTTPS URL, a Mapbox URL indicating the style’s map ID + (`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. + */ - (instancetype)initWithFrame:(NSRect)frame styleURL:(nullable NSURL *)styleURL; -#pragma mark Accessing the delegate -/** @name Accessing the Delegate */ +#pragma mark Accessing the 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. */ +/** + 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. + */ @property (nonatomic, weak, nullable) IBOutlet id <MGLMapViewDelegate> delegate; -#pragma mark Configuring the map’s appearance -/** @name Configuring the Map’s Appearance */ - +#pragma mark Configuring the Map’s Appearance -/** URL of the style currently displayed in the receiver. - - The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s - map ID (`mapbox://styles/<user>/<style>`), 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. */ +/** + URL of the style currently displayed in the receiver. + + The URL may be a full HTTP or HTTPS URL, a Mapbox URL indicating the style’s + map ID (`mapbox://styles/<user>/<style>`), 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. + */ @property (nonatomic, null_resettable) NSURL *styleURL; -/** Reloads the style. +/** + 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 Mapbox - account. */ + 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 Mapbox account. + */ - (IBAction)reloadStyle:(id)sender; -/** A control for zooming in and out, positioned in the lower-right corner. */ +/** + A control for zooming in and out, positioned in the lower-right corner. + */ @property (nonatomic, readonly) NSSegmentedControl *zoomControls; -/** A control indicating the map’s direction and allowing the user to manipulate - the direction, positioned above the zoom controls in the lower-right corner. +/** + A control indicating the map’s direction and allowing the user to manipulate + the direction, positioned above the zoom controls in the lower-right corner. */ @property (nonatomic, readonly) NSSlider *compass; -/** The Mapbox logo, positioned in the lower-left corner. - - @note The Mapbox terms of service, which governs the use of Mapbox-hosted - vector tiles and styles, - <a href="https://www.mapbox.com/help/mapbox-logo/">requires</a> most - Mapbox customers to display the Mapbox logo. If this applies to you, do - not hide this view or change its contents. */ +/** + The Mapbox logo, positioned in the lower-left corner. + + @note The Mapbox terms of service, which governs the use of Mapbox-hosted + vector tiles and styles, + <a href="https://www.mapbox.com/help/mapbox-logo/">requires</a> most Mapbox + customers to display the Mapbox logo. If this applies to you, do not hide + this view or change its contents. + */ @property (nonatomic, readonly) NSImageView *logoView; -/** A view showing legally required copyright notices, positioned along the - bottom of the map view, to the left of the Mapbox logo. - - @note The Mapbox terms of service, which governs the use of Mapbox-hosted - vector tiles and styles, - <a href="https://www.mapbox.com/help/attribution/">requires</a> these - copyright notices to accompany any map that features Mapbox-designed - styles, OpenStreetMap data, or other Mapbox 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. */ +/** + A view showing legally required copyright notices, positioned along the bottom + of the map view, to the left of the Mapbox logo. + + @note The Mapbox terms of service, which governs the use of Mapbox-hosted + vector tiles and styles, + <a href="https://www.mapbox.com/help/attribution/">requires</a> these + copyright notices to accompany any map that features Mapbox-designed styles, + OpenStreetMap data, or other Mapbox 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. + */ @property (nonatomic, readonly) NSView *attributionView; -#pragma mark Manipulating the viewpoint -/** @name Manipulating the Viewpoint */ +#pragma mark Manipulating the Viewpoint -/** 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. */ +/** + 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. + */ @property (nonatomic) CLLocationCoordinate2D centerCoordinate; -/** 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. - - @param coordinate The new center coordinate for the map. - @param 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. */ +/** + 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. + + @param coordinate The new center coordinate for the map. + @param 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. + */ - (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated; -/** 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, <sup>1</sup>⁄<sub>16</sub> 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. +/** + 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, <sup>1</sup>⁄<sub>16</sub> 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. */ @property (nonatomic) double zoomLevel; /** - * 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. + 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 value of this property is 0. */ @property (nonatomic) double minimumZoomLevel; /** - * 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 20. + 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 value of this property is 20. */ @property (nonatomic) double maximumZoomLevel; -/** 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. - - @param zoomLevel The new zoom level for the map. - @param 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. */ +/** + 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. + + @param zoomLevel The new zoom level for the map. + @param 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. + */ - (void)setZoomLevel:(double)zoomLevel animated:(BOOL)animated; -/** 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. +/** + 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. */ @property (nonatomic) CLLocationDirection direction; -/** Changes the heading of the map and optionally animates the change. - - @param direction The heading of the map, measured in degrees clockwise from - true north. - @param 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. - - Changing the heading rotates the map without changing the current center - coordinate or zoom level. */ +/** + 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. + + @param direction The heading of the map, measured in degrees clockwise from + true north. + @param 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. + */ - (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated; -/** A camera representing the current viewpoint of the map. */ +/** + A camera representing the current viewpoint of the map. + */ @property (nonatomic, copy) MGLMapCamera *camera; -/** Moves the viewpoint to a different location with respect to the map with an - optional transition animation. - - @param camera The new viewpoint. - @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. */ +/** + Moves the viewpoint to a different location with respect to the map with an + optional transition animation. + + @param camera The new viewpoint. + @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. + */ - (void)setCamera:(MGLMapCamera *)camera animated:(BOOL)animated; -/** Moves the viewpoint to a different location with respect to the map with an - optional transition duration and timing function. - - @param camera The new viewpoint. - @param duration The amount of time, measured in seconds, that the transition - animation should take. Specify `0` to jump to the new viewpoint - instantaneously. - @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. - @param completion The block to execute after the animation finishes. */ +/** + Moves the viewpoint to a different location with respect to the map with an + optional transition duration and timing function. + + @param camera The new viewpoint. + @param duration The amount of time, measured in seconds, that the transition + animation should take. Specify `0` to jump to the new viewpoint + instantaneously. + @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. + @param completion The block to execute after the animation finishes. + */ - (void)setCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration animationTimingFunction:(nullable CAMediaTimingFunction *)function completionHandler:(nullable void (^)(void))completion; -/** 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. - - @param camera The new viewpoint. - @param completion The block to execute after the animation finishes. */ +/** + 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. + + @param camera The new viewpoint. + @param completion The block to execute after the animation finishes. + */ - (void)flyToCamera:(MGLMapCamera *)camera completionHandler:(nullable void (^)(void))completion; -/** 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. - - @param camera The new viewpoint. - @param 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. - @param completion The block to execute after the animation finishes. */ +/** + 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. + + @param camera The new viewpoint. + @param 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. + @param completion The block to execute after the animation finishes. + */ - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration completionHandler:(nullable void (^)(void))completion; -/** 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. - - @param camera The new viewpoint. - @param 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. - @param 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. - @param completion The block to execute after the animation finishes. */ +/** + 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. + + @param camera The new viewpoint. + @param 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. + @param 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. + @param completion The block to execute after the animation finishes. + */ - (void)flyToCamera:(MGLMapCamera *)camera withDuration:(NSTimeInterval)duration peakAltitude:(CLLocationDistance)peakAltitude completionHandler:(nullable void (^)(void))completion; -/** The geographic 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, use the -setVisibleCoordinateBounds:animated: - method instead. */ +/** + The geographic 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, use the `-setVisibleCoordinateBounds:animated:` + method instead. + */ @property (nonatomic) MGLCoordinateBounds visibleCoordinateBounds; -/** Changes the receiver’s viewport to fit the given coordinate bounds, - optionally animating the change. - - @param bounds The bounds that the viewport will show in its entirety. - @param animated Specify `YES` to animate the change by smoothly scrolling - and zooming or `NO` to immediately display the given bounds. */ +/** + Changes the receiver’s viewport to fit the given coordinate bounds, optionally + animating the change. + + @param bounds The bounds that the viewport will show in its entirety. + @param animated Specify `YES` to animate the change by smoothly scrolling and + zooming or `NO` to immediately display the given bounds. + */ - (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds animated:(BOOL)animated; -/** Changes the receiver’s viewport to fit the given coordinate bounds and - optionally some additional padding on each side. - - @param bounds The bounds that the viewport will show in its entirety. - @param insets The minimum padding (in screen points) that will be visible - around the given coordinate bounds. - @param animated Specify `YES` to animate the change by smoothly scrolling and - zooming or `NO` to immediately display the given bounds. +/** + Changes the receiver’s viewport to fit the given coordinate bounds and + optionally some additional padding on each side. + + @param bounds The bounds that the viewport will show in its entirety. + @param insets The minimum padding (in screen points) that will be visible + around the given coordinate bounds. + @param animated Specify `YES` to animate the change by smoothly scrolling and + zooming or `NO` to immediately display the given bounds. */ - (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds edgePadding:(NSEdgeInsets)insets animated:(BOOL)animated; -/** Returns the camera that best fits the given coordinate bounds. - - @param bounds The coordinate bounds to fit to the receiver’s viewport. - @return 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. +/** + Returns the camera that best fits the given coordinate bounds. + + @param bounds The coordinate bounds to fit to the receiver’s viewport. + @return 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. */ - (MGLMapCamera *)cameraThatFitsCoordinateBounds:(MGLCoordinateBounds)bounds; -/** Returns the camera that best fits the given coordinate bounds, optionally - with some additional padding on each side. - - @param bounds The coordinate bounds to fit to the receiver’s viewport. - @param 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 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. +/** + Returns the camera that best fits the given coordinate bounds, optionally with + some additional padding on each side. + + @param bounds The coordinate bounds to fit to the receiver’s viewport. + @param 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 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. */ - (MGLMapCamera *)cameraThatFitsCoordinateBounds:(MGLCoordinateBounds)bounds edgePadding:(NSEdgeInsets)insets; -/** A Boolean value indicating whether the receiver automatically adjusts its - content insets. - - When the value of this property is `YES`, the map view automatically updates - its `contentInsets` property to account for any overlapping title bar or - toolbar. To overlap with the title bar or toolbar, the containing window’s - style mask must have `NSFullSizeContentViewWindowMask` set, and the title - bar must not be transparent. - - The default value of this property is `YES`. */ +/** + A Boolean value indicating whether the receiver automatically adjusts its + content insets. + + When the value of this property is `YES`, the map view automatically updates + its `contentInsets` property to account for any overlapping title bar or + toolbar. To overlap with the title bar or toolbar, the containing window’s + style mask must have `NSFullSizeContentViewWindowMask` set, and the title bar + must not be transparent. + + The default value of this property is `YES`. + */ @property (nonatomic, assign) BOOL automaticallyAdjustsContentInsets; -/** 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 `NSEdgeInsetsZero`, 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 value of the `automaticallyAdjustsContentInsets` property is `YES`, - the value of this property may be overridden at any time. - - Changing the value of this property updates the map view immediately. If you - want to animate the change, use the `-setContentInsets:animated:` method - instead. */ +/** + 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 `NSEdgeInsetsZero`, 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 value of the `automaticallyAdjustsContentInsets` property is `YES`, + the value of this property may be overridden at any time. + + Changing the value of this property updates the map view immediately. If you + want to animate the change, use the `-setContentInsets:animated:` method + instead. + */ @property (nonatomic, assign) NSEdgeInsets contentInsets; -/** 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 `NSEdgeInsetsZero`, 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 value of the `automaticallyAdjustsContentInsets` property is `YES`, - the value of this property may be overridden at any time. - - @param contentInsets The new values to inset the content by. - @param animated Specify `YES` if you want the map view to animate the change - to the content insets or `NO` if you want the map to inset the content - immediately. */ +/** + 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 `NSEdgeInsetsZero`, 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 value of the `automaticallyAdjustsContentInsets` property is `YES`, + the value of this property may be overridden at any time. + + @param contentInsets The new values to inset the content by. + @param animated Specify `YES` if you want the map view to animate the change to + the content insets or `NO` if you want the map to inset the content + immediately. + */ - (void)setContentInsets:(NSEdgeInsets)contentInsets animated:(BOOL)animated; -#pragma mark Configuring gesture recognition -/** @name Configuring How the User Interacts with the Map */ +#pragma mark Configuring How the User Interacts with the Map -/** 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, by using a scroll wheel on a - traditional mouse, or by dragging the mouse cursor up and down while holding - down the Shift key. When the receiver has focus, the user may also zoom by - pressing the up and down arrow keys while holding down the Option key. - - 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. */ +/** + 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, by using a scroll wheel on a traditional + mouse, or by dragging the mouse cursor up and down while holding down the Shift + key. When the receiver has focus, the user may also zoom by pressing the up and + down arrow keys while holding down the Option key. + + 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. + */ @property (nonatomic, getter=isZoomEnabled) BOOL zoomEnabled; -/** 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 swiping with two fingers or dragging the mouse cursor. When the receiver - has focus, the user may also scroll around the map by pressing the arrow - keys. - - 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. */ +/** + 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 + swiping with two fingers or dragging the mouse cursor. When the receiver has + focus, the user may also scroll around the map by pressing the arrow keys. + + 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. + */ @property (nonatomic, getter=isScrollEnabled) BOOL scrollEnabled; -/** 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 or by dragging the mouse cursor - left and right while holding down the Option key. When the receiver has - focus, the user may also zoom by pressing the left and right arrow keys - while holding down the Option key. - - 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. */ +/** + 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 or by dragging the mouse cursor left + and right while holding down the Option key. When the receiver has focus, the + user may also zoom by pressing the left and right arrow keys while holding down + the Option key. + + 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. + */ @property (nonatomic, getter=isRotateEnabled) BOOL rotateEnabled; -/** A Boolean value that determines whether the user may tilt of the map, - changing the pitch. - - When this property is set to `YES`, the default, the user may rotate the map - by dragging the mouse cursor up and down while holding down the Option key. - - 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. */ +/** + A Boolean value that determines whether the user may tilt of the map, changing + the pitch. + + When this property is set to `YES`, the default, the user may rotate the map by + dragging the mouse cursor up and down while holding down the Option key. + + 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. + */ @property (nonatomic, getter=isPitchEnabled) BOOL pitchEnabled; -#pragma mark Annotating the map -/** @name Annotating the Map */ +#pragma mark Annotating the Map -/** 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`. */ +/** + 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`. + */ @property (nonatomic, readonly, nullable) NS_ARRAY_OF(id <MGLAnnotation>) *annotations; -/** Adds an annotation to the map view. - - @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. */ +/** + Adds an annotation to the map view. + + @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. + */ - (void)addAnnotation:(id <MGLAnnotation>)annotation; -/** Adds an array of annotations to the map view. - - @param 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. */ +/** + Adds an array of annotations to the map view. + + @param 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. + */ - (void)addAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations; -/** 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. - - @param annotation The annotation object to remove. This object must conform - to the MGLAnnotation protocol. */ +/** + 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. + + @param annotation The annotation object to remove. This object must conform to + the `MGLAnnotation` protocol. + */ - (void)removeAnnotation:(id <MGLAnnotation>)annotation; -/** 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. - - @param annotations The array of annotation objects to remove. Objects in the - array must conform to the MGLAnnotation protocol. */ +/** + 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. + + @param annotations The array of annotation objects to remove. Objects in the + array must conform to the `MGLAnnotation` protocol. + */ - (void)removeAnnotations:(NS_ARRAY_OF(id <MGLAnnotation>) *)annotations; -/** 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. - - @param 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 An annotation image object with the given identifier, or `nil` if no - such object exists in the reuse queue. */ +/** + 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. + + @param 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 An annotation image object with the given identifier, or `nil` if no + such object exists in the reuse queue. + */ - (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier; -#pragma mark Managing annotation selections -/** @name Managing Annotation Selections */ +#pragma mark Managing Annotation Selections -/** The currently selected annotations. - - Assigning a new array to this property selects only the first annotation in - the array. */ +/** + The currently selected annotations. + + Assigning a new array to this property selects only the first annotation in the + array. + */ @property (nonatomic, copy) NS_ARRAY_OF(id <MGLAnnotation>) *selectedAnnotations; -/** Selects an annotation and displays a callout popover for it. - - If the given annotation is not visible within the current viewport, this - method has no effect. - - @param annotation The annotation object to select. */ +/** + Selects an annotation and displays a callout popover for it. + + If the given annotation is not visible within the current viewport, this method + has no effect. + + @param annotation The annotation object to select. + */ - (void)selectAnnotation:(id <MGLAnnotation>)annotation; -/** Deselects an annotation and hides its callout popover. - - @param annotation The annotation object to deselect. */ +/** + Deselects an annotation and hides its callout popover. + + @param annotation The annotation object to deselect. + */ - (void)deselectAnnotation:(nullable id <MGLAnnotation>)annotation; -/** A common view controller for managing a callout popover’s content view. - - Like any instance of NSPopover, an annotation callout manages its contents - with a view controller. The annotation object is the view controller’s - represented object. This means that you can bind controls in the view - controller’s content view to KVO-compliant properties of the annotation - object, such as -title and -subtitle. - - This property defines a common view controller that is used for every - annotation’s callout view. If you set this property to `nil`, a default - view controller will be used that manages a simple title label and subtitle - label. If you need distinct view controllers for different annotations, the - map view’s delegate should implement - -mapView:calloutViewControllerForAnnotation: instead. */ +/** + A common view controller for managing a callout popover’s content view. + + Like any instance of `NSPopover`, an annotation callout manages its contents + with a view controller. The annotation object is the view controller’s + represented object. This means that you can bind controls in the view + controller’s content view to KVO-compliant properties of the annotation object, + such as `title` and `subtitle`. + + This property defines a common view controller that is used for every + annotation’s callout view. If you set this property to `nil`, a default view + controller will be used that manages a simple title label and subtitle label. + If you need distinct view controllers for different annotations, the map view’s + delegate should implement `-mapView:calloutViewControllerForAnnotation:` + instead. + */ @property (nonatomic, strong, null_resettable) IBOutlet NSViewController *calloutViewController; -#pragma mark Finding annotations -/** @name Finding Annotations */ +#pragma mark Finding Annotations -/** Returns a point annotation located at the given point. - - @param point A point in the view’s coordinate system. - @return A point annotation whose annotation image coincides with the point. - If multiple point annotations coincide with the point, the return value - is the annotation that would be selected if the user clicks at this - point. +/** + Returns a point annotation located at the given point. + + @param point A point in the view’s coordinate system. + @return A point annotation whose annotation image coincides with the point. If + multiple point annotations coincide with the point, the return value is the + annotation that would be selected if the user clicks at this point. */ - (id <MGLAnnotation>)annotationAtPoint:(NSPoint)point; -#pragma mark Overlaying the map -/** @name Overlaying the Map */ +#pragma mark Overlaying the Map -/** Adds a single overlay to the map. - - To remove an overlay from a map, use the -removeOverlay: method. - - @param overlay The overlay object to add. This object must conform to the - MGLOverlay protocol. */ +/** + Adds a single overlay to the map. + + To remove an overlay from a map, use the `-removeOverlay:` method. + + @param overlay The overlay object to add. This object must conform to the + `MGLOverlay` protocol. + */ - (void)addOverlay:(id <MGLOverlay>)overlay; -/** Adds an array of overlays to the map. - - To remove multiple overlays from a map, use the -removeOverlays: method. - - @param overlays An array of objects, each of which must conform to the - MGLOverlay protocol. */ +/** + Adds an array of overlays to the map. + + To remove multiple overlays from a map, use the `-removeOverlays:` method. + + @param overlays An array of objects, each of which must conform to the + `MGLOverlay` protocol. + */ - (void)addOverlays:(NS_ARRAY_OF(id <MGLOverlay>) *)overlays; -/** Removes a single overlay from the map. - - If the specified overlay is not currently associated with the map view, this - method does nothing. - - @param overlay The overlay object to remove. */ +/** + Removes a single overlay from the map. + + If the specified overlay is not currently associated with the map view, this + method does nothing. + + @param overlay The overlay object to remove. + */ - (void)removeOverlay:(id <MGLOverlay>)overlay; -/** Removes an array of overlays from the map. - - If a given overlay object is not associated with the map view, it is - ignored. - - @param overlays An array of objects, each of which conforms to the - MGLOverlay protocol. */ +/** + Removes an array of overlays from the map. + + If a given overlay object is not associated with the map view, it is ignored. + + @param overlays An array of objects, each of which conforms to the `MGLOverlay` + protocol. + */ - (void)removeOverlays:(NS_ARRAY_OF(id <MGLOverlay>) *)overlays; -#pragma mark Converting geographic coordinates -/** @name Converting Geographic Coordinates */ +#pragma mark Converting Geographic Coordinates -/** Converts a geographic coordinate to a point in the given view’s coordinate - system. - - @param coordinate The geographic coordinate to convert. - @param 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 The point (in the appropriate view or window coordinate system) - corresponding to the given geographic coordinate. */ +/** + Converts a geographic coordinate to a point in the given view’s coordinate + system. + + @param coordinate The geographic coordinate to convert. + @param 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 The point (in the appropriate view or window coordinate system) + corresponding to the given geographic coordinate. + */ - (NSPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable NSView *)view; -/** Converts a point in the given view’s coordinate system to a geographic - coordinate. - - @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. */ +/** + Converts a point in the given view’s coordinate system to a geographic + coordinate. + + @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. + */ - (CLLocationCoordinate2D)convertPoint:(NSPoint)point toCoordinateFromView:(nullable NSView *)view; -/** Converts a geographic bounding box to a rectangle in the given view’s - coordinate system. - - @param bounds The geographic bounding box to convert. - @param 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. */ +/** + Converts a geographic bounding box to a rectangle in the given view’s + coordinate system. + + @param bounds The geographic bounding box to convert. + @param 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. + */ - (NSRect)convertCoordinateBounds:(MGLCoordinateBounds)bounds toRectToView:(nullable NSView *)view; -/** Converts a rectangle in the given view’s coordinate system to a geographic - bounding box. - - @param rect The rectangle to convert. - @param view The view in whose coordinate system the rectangle is expressed. - @return The geographic bounding box coextensive with the given rectangle. */ +/** + Converts a rectangle in the given view’s coordinate system to a geographic + bounding box. + + @param rect The rectangle to convert. + @param view The view in whose coordinate system the rectangle is expressed. + @return The geographic bounding box coextensive with the given rectangle. + */ - (MGLCoordinateBounds)convertRect:(NSRect)rect toCoordinateBoundsFromView:(nullable NSView *)view; -/** 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. - - @param latitude The latitude of the geographic coordinate represented by the - point. - @return The distance in meters spanned by a single point. */ +/** + 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. + + @param latitude The latitude of the geographic coordinate represented by the + point. + @return The distance in meters spanned by a single point. + */ - (CLLocationDistance)metersPerPointAtLatitude:(CLLocationDegrees)latitude; -#pragma mark Debugging the map -/** @name Debugging the Map */ +#pragma mark Debugging the Map -/** 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. */ +/** + 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. + */ @property (nonatomic) MGLMapDebugMaskOptions debugMask; @end diff --git a/platform/osx/src/MGLMapViewDelegate.h b/platform/osx/src/MGLMapViewDelegate.h index fcd013284d..0b7eec84ac 100644 --- a/platform/osx/src/MGLMapViewDelegate.h +++ b/platform/osx/src/MGLMapViewDelegate.h @@ -10,68 +10,77 @@ NS_ASSUME_NONNULL_BEGIN @class MGLPolyline; @class MGLShape; -/** The MGLMapViewDelegate protocol defines a set of optional methods that you - can use to receive messages from an MGLMapView instance. Because many map - operations require the MGLMapView class to load data asynchronously, the map - view calls these methods to notify your application when specific operations - complete. The map view also uses these methods to request information about - annotations displayed on the map, such as the styles and interaction modes - to apply to individual annotations. */ +/** + The `MGLMapViewDelegate` protocol defines a set of optional methods that you + can use to receive messages from an `MGLMapView` instance. Because many map + operations require the `MGLMapView` class to load data asynchronously, the map + view calls these methods to notify your application when specific operations + complete. The map view also uses these methods to request information about + annotations displayed on the map, such as the styles and interaction modes to + apply to individual annotations. + */ @protocol MGLMapViewDelegate <NSObject> @optional -#pragma mark Responding to map viewpoint changes -/** @name Responding to Map Viewpoint Changes */ - -/** 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. - - @param mapView The map view whose viewpoint will change. - @param animated Whether the change will cause an animated effect on the map. +#pragma mark Responding to Map Viewpoint Changes + +/** + 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. + + @param mapView The map view whose viewpoint will change. + @param animated Whether the change will cause an animated effect on the map. */ - (void)mapView:(MGLMapView *)mapView cameraWillChangeAnimated:(BOOL)animated; -/** Tells the delegate that the viewpoint depicted by the map view is changing. - - This method is called as the currently displayed map camera changes due to - animation. During movement, 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. */ +/** + Tells the delegate that the viewpoint depicted by the map view is changing. + + This method is called as the currently displayed map camera changes due to + animation. During movement, 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. + */ - (void)mapViewCameraIsChanging:(MGLMapView *)mapView; -/** Tells the delegate that the viewpoint depicted by the map view has finished - changing. - - This method is called whenever the currently displayed map camera has - finished changing. - - @param mapView The map view whose viewpoint has changed. - @param animated Whether the change caused an animated effect on the map. */ +/** + Tells the delegate that the viewpoint depicted by the map view has finished + changing. + + This method is called whenever the currently displayed map camera has finished + changing. + + @param mapView The map view whose viewpoint has changed. + @param animated Whether the change caused an animated effect on the map. + */ - (void)mapView:(MGLMapView *)mapView cameraDidChangeAnimated:(BOOL)animated; -#pragma mark Loading the map -/** @name Loading the Map */ +#pragma mark Loading the Map -/** Tells the delegate that the map view will begin to load. - - This method is called whenever the map view starts loading, including when a - new style has been set and the map must reload. - - @param mapView The map view that is starting to load. */ +/** + Tells the delegate that the map view will begin to load. + + This method is called whenever the map view starts loading, including when a + new style has been set and the map must reload. + + @param mapView The map view that is starting to load. + */ - (void)mapViewWillStartLoadingMap:(MGLMapView *)mapView; -/** Tells the delegate that the map view has finished loading. - - This method is called whenever the map view finishes loading, either after - the initial load or after a style change has forced a reload. - - @param mapView The map view that has finished loading. */ +/** + Tells the delegate that the map view has finished loading. + + This method is called whenever the map view finishes loading, either after the + initial load or after a style change has forced a reload. + + @param mapView The map view that has finished loading. + */ - (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapView; - (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView; @@ -79,119 +88,131 @@ NS_ASSUME_NONNULL_BEGIN - (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView; - (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered; -#pragma mark Managing the display of annotations -/** @name Managing the Display of Annotations */ - -/** Returns an annotation image object to mark the given point annotation object - on the map. - - @param mapView The map view that requested the annotation image. - @param annotation The object representing the annotation that is about to be - displayed. - @return The image object to display for the given annotation or `nil` if you - want to display the default marker image. */ +#pragma mark Managing the Display of Annotations + +/** + Returns an annotation image object to mark the given point annotation object on + the map. + + @param mapView The map view that requested the annotation image. + @param annotation The object representing the annotation that is about to be + displayed. + @return The image object to display for the given annotation or `nil` if you + want to display the default marker image. + */ - (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id <MGLAnnotation>)annotation; -/** Returns the alpha value to use when rendering a shape annotation. - - A value of 0.0 results in a completely transparent shape. A value of 1.0, - the default, results in a completely opaque shape. - - @param mapView The map view rendering the shape annotation. - @param annotation The annotation being rendered. - @return An alpha value between 0 and 1.0. */ +/** + Returns the alpha value to use when rendering a shape annotation. + + A value of 0.0 results in a completely transparent shape. A value of 1.0, the + default, results in a completely opaque shape. + + @param mapView The map view rendering the shape annotation. + @param annotation The annotation being rendered. + @return An alpha value between 0 and 1.0. + */ - (CGFloat)mapView:(MGLMapView *)mapView alphaForShapeAnnotation:(MGLShape *)annotation; -/** Returns the color to use when rendering the outline of a shape annotation. - - The default stroke color is the selected menu item color. If a pattern - color is specified, the result is undefined. - - @param mapView The map view rendering the shape annotation. - @param annotation The annotation being rendered. - @return A color to use for the shape outline. */ +/** + Returns the color to use when rendering the outline of a shape annotation. + + The default stroke color is the selected menu item color. If a pattern color is + specified, the result is undefined. + + @param mapView The map view rendering the shape annotation. + @param annotation The annotation being rendered. + @return A color to use for the shape outline. + */ - (NSColor *)mapView:(MGLMapView *)mapView strokeColorForShapeAnnotation:(MGLShape *)annotation; -/** Returns the color to use when rendering the fill of a polygon annotation. - - The default fill color is selected menu item color. If a pattern color - is specified, the result is undefined. - - @param mapView The map view rendering the polygon annotation. - @param annotation The annotation being rendered. - @return The polygon’s interior fill color. */ +/** + Returns the color to use when rendering the fill of a polygon annotation. + + The default fill color is selected menu item color. If a pattern color is + specified, the result is undefined. + + @param mapView The map view rendering the polygon annotation. + @param annotation The annotation being rendered. + @return The polygon’s interior fill color. + */ - (NSColor *)mapView:(MGLMapView *)mapView fillColorForPolygonAnnotation:(MGLPolygon *)annotation; -/** Returns the line width in points to use when rendering the outline of a - polyline annotation. - - By default, the polyline is outlined with a line 3.0 points wide. - - @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. */ +/** + Returns the line width in points to use when rendering the outline of a + polyline annotation. + + By default, the polyline is outlined with a line 3.0 points wide. + + @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. + */ - (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotation; -#pragma mark Selecting annotations -/** @name Selecting annotations */ +#pragma mark Selecting Annotations -/** Tells the delegate that one of its annotations has been selected. - - You can use this method to track changes to the selection state of - annotations. - - @param mapView The map view containing the annotation. - @param annotation The annotation that was selected. */ +/** + Tells the delegate that one of its annotations has been selected. + + You can use this method to track changes to the selection state of annotations. + + @param mapView The map view containing the annotation. + @param annotation The annotation that was selected. + */ - (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id <MGLAnnotation>)annotation; -/** Tells the delegate that one of its annotations has been deselected. - - You can use this method to track changes in the selection state of - annotations. - - @param mapView The map view containing the annotation. - @param annotation The annotation that was deselected. */ +/** + Tells the delegate that one of its annotations has been deselected. + + You can use this method to track changes in the selection state of annotations. + + @param mapView The map view containing the annotation. + @param annotation The annotation that was deselected. + */ - (void)mapView:(MGLMapView *)mapView didDeselectAnnotation:(id <MGLAnnotation>)annotation; -#pragma mark Displaying information about annotations -/** @name Displaying Information About Annotations */ - -/** Returns a Boolean value indicating whether the annotation is able to display - extra information in a callout popover. - - This method is called after an annotation is selected, before any callout is - displayed for the annotation. - - If the return value is `YES`, a callout popover is shown when the user - clicks on a selected annotation. The default callout displays the - annotation’s title and subtitle. You can customize the popover’s contents by - implementing the -mapView:calloutViewControllerForAnnotation: method. - - If the return value is `NO`, or if this method is unimplemented, or if the - annotation lacks a title, the annotation will not show a callout even when - selected. - - @param mapView The map view that has selected the annotation. - @param annotation The object representing the annotation. - @return A Boolean value indicating whether the annotation should show a - callout. +#pragma mark Displaying Information About Annotations + +/** + Returns a Boolean value indicating whether the annotation is able to display + extra information in a callout popover. + + This method is called after an annotation is selected, before any callout is + displayed for the annotation. + + If the return value is `YES`, a callout popover is shown when the user clicks + on a selected annotation. The default callout displays the annotation’s title + and subtitle. You can customize the popover’s contents by implementing the + `-mapView:calloutViewControllerForAnnotation:` method. + + If the return value is `NO`, or if this method is unimplemented, or if the + annotation lacks a title, the annotation will not show a callout even when + selected. + + @param mapView The map view that has selected the annotation. + @param annotation The object representing the annotation. + @return A Boolean value indicating whether the annotation should show a + callout. */ - (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation; -/** Returns a view controller to manage the callout popover’s content view. - - Like any instance of NSPopover, an annotation callout manages its contents - with a view controller. The annotation object is the view controller’s - represented object. This means that you can bind controls in the view - controller’s content view to KVO-compliant properties of the annotation - object, such as -title and -subtitle. - - If each annotation should have an identical callout, you can set the - MGLMapView instance’s -setCalloutViewController: method instead. - - @param mapView The map view that is requesting a callout view controller. - @param annotation The object representing the annotation. - @return A view controller for the given annotation. */ +/** + Returns a view controller to manage the callout popover’s content view. + + Like any instance of `NSPopover`, an annotation callout manages its contents + with a view controller. The annotation object is the view controller’s + represented object. This means that you can bind controls in the view + controller’s content view to KVO-compliant properties of the annotation object, + such as `title` and `subtitle`. + + If each annotation should have an identical callout, you can set the + `MGLMapView` instance’s `-setCalloutViewController:` method instead. + + @param mapView The map view that is requesting a callout view controller. + @param annotation The object representing the annotation. + @return A view controller for the given annotation. + */ - (nullable NSViewController *)mapView:(MGLMapView *)mapView calloutViewControllerForAnnotation:(id <MGLAnnotation>)annotation; @end diff --git a/platform/osx/src/Mapbox.h b/platform/osx/src/Mapbox.h index 14d84e2e32..a98aea9bcf 100644 --- a/platform/osx/src/Mapbox.h +++ b/platform/osx/src/Mapbox.h @@ -6,27 +6,27 @@ FOUNDATION_EXPORT double MapboxVersionNumber; /// Project version string for Mapbox. FOUNDATION_EXPORT const unsigned char MapboxVersionString[]; -#import <Mapbox/MGLAccountManager.h> -#import <Mapbox/MGLAnnotation.h> -#import <Mapbox/MGLAnnotationImage.h> -#import <Mapbox/MGLClockDirectionFormatter.h> -#import <Mapbox/MGLCompassDirectionFormatter.h> -#import <Mapbox/MGLCoordinateFormatter.h> -#import <Mapbox/MGLGeometry.h> -#import <Mapbox/MGLMapCamera.h> -#import <Mapbox/MGLMapView.h> -#import <Mapbox/MGLMapView+IBAdditions.h> -#import <Mapbox/MGLMapViewDelegate.h> -#import <Mapbox/MGLMultiPoint.h> -#import <Mapbox/MGLOfflinePack.h> -#import <Mapbox/MGLOfflineRegion.h> -#import <Mapbox/MGLOfflineStorage.h> -#import <Mapbox/MGLOverlay.h> -#import <Mapbox/MGLPointAnnotation.h> -#import <Mapbox/MGLPolygon.h> -#import <Mapbox/MGLPolyline.h> -#import <Mapbox/MGLShape.h> -#import <Mapbox/MGLStyle.h> -#import <Mapbox/MGLTilePyramidOfflineRegion.h> -#import <Mapbox/MGLTypes.h> -#import <Mapbox/NSValue+MGLAdditions.h> +#import "MGLAccountManager.h" +#import "MGLAnnotation.h" +#import "MGLAnnotationImage.h" +#import "MGLClockDirectionFormatter.h" +#import "MGLCompassDirectionFormatter.h" +#import "MGLCoordinateFormatter.h" +#import "MGLGeometry.h" +#import "MGLMapCamera.h" +#import "MGLMapView.h" +#import "MGLMapView+IBAdditions.h" +#import "MGLMapViewDelegate.h" +#import "MGLMultiPoint.h" +#import "MGLOfflinePack.h" +#import "MGLOfflineRegion.h" +#import "MGLOfflineStorage.h" +#import "MGLOverlay.h" +#import "MGLPointAnnotation.h" +#import "MGLPolygon.h" +#import "MGLPolyline.h" +#import "MGLShape.h" +#import "MGLStyle.h" +#import "MGLTilePyramidOfflineRegion.h" +#import "MGLTypes.h" +#import "NSValue+MGLAdditions.h" |