tei/MapLibreParticleLab
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[ios, osx] Reformatted documentation comments

Browse Source 
Reformatted documentation comments in public headers in the OS X SDK and public headers shared between the iOS and OS X SDKs to wrap at column 80 and avoid excessive indentation that causes SourceKitten to detect code blocks.
This commit is contained in:
Minh Nguyễn
2016-05-09 16:05:14 -07:00
committed by Minh Nguyễn
parent a025d8327a
commit 1634058b51
15 changed files with 1034 additions and 769 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
platform/darwin/src/MGLAnnotation.h
View File

@@ -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;

28
platform/darwin/src/MGLGeometry.h
View File

@@ -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;

38
platform/darwin/src/MGLMapCamera.h
View File

@@ -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

19
platform/darwin/src/MGLMultiPoint.h
View File

@@ -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;

37
platform/darwin/src/MGLOverlay.h
View File

@@ -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;

11
platform/darwin/src/MGLPointAnnotation.h
View File

@@ -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

13
platform/darwin/src/MGLPolygon.h
View File

@@ -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.
*/

13
platform/darwin/src/MGLPolyline.h
View File

@@ -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.
*/

22
platform/darwin/src/MGLShape.h
View File

@@ -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

92
platform/darwin/src/MGLStyle.h
View File

@@ -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.
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.
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.
@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;

2
platform/darwin/test/MGLStyleTests.mm
View File

@@ -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)];

70
platform/osx/src/MGLAnnotationImage.h
View File

@@ -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

1088
platform/osx/src/MGLMapView.h
View File

File diff suppressed because it is too large Load Diff

301
platform/osx/src/MGLMapViewDelegate.h
View File

@@ -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 */
#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.
/**
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 */
#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. */
/**
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 */
#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.
/**
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

48
platform/osx/src/Mapbox.h
View File

@@ -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"