[osx] Documentation comments for public classes

Added documentation comments for all the public headers that aren’t being shared with iOS.

Removed an animated: parameter from -selectAnnotation: and -deselectAnnotation:: because callout popovers may extend beyond the entire window, there is no need to scroll the map to make the entire callout visible.

Added missing geometric conversion methods.

Renamed -mapView:regionWillChangeAnimated: et al. to say “camera” instead of “region”. “Region” leaves ambiguity about whether properties like rotation and pitch trigger this method. “Camera” associates these methods with the camera property, which seems apt.
This commit is contained in:
Minh Nguyễn
2015-12-02 16:05:41 -08:00
committed by Minh Nguyễn
parent 73324ae2f8
commit ea57be5598
12 changed files with 737 additions and 94 deletions

View File

@@ -29,7 +29,7 @@
'../platform/darwin/MGLStyle.mm',
'../include/mbgl/darwin/MGLGeometry.h',
'../platform/darwin/MGLGeometry_Private.h',
'../platform/darwin/MGLGeometry.m',
'../platform/darwin/MGLGeometry.mm',
'../include/mbgl/darwin/MGLAnnotation.h',
'../include/mbgl/darwin/MGLShape.h',
'../platform/darwin/MGLShape.m',

View File

@@ -29,7 +29,7 @@
'../platform/darwin/MGLStyle.mm',
'../include/mbgl/darwin/MGLGeometry.h',
'../platform/darwin/MGLGeometry_Private.h',
'../platform/darwin/MGLGeometry.m',
'../platform/darwin/MGLGeometry.mm',
'../include/mbgl/darwin/MGLAnnotation.h',
'../include/mbgl/darwin/MGLShape.h',
'../platform/darwin/MGLShape.m',

View File

@@ -4,21 +4,39 @@
NS_ASSUME_NONNULL_BEGIN
/** The MGLAccountManager object provides a global way to set a Mapbox API access token, as well as other settings used framework-wide. */
/** The MGLAccountManager object provides a global way to set a Mapbox API
access token, as well as other settings used framework-wide. */
@interface MGLAccountManager : NSObject
#pragma mark Authorizing access
/** @name Authorizing Access */
/** Set the Mapbox API access token for the framework.
*
* You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework.
* @param accessToken The Mapbox API access token. */
/** Set the
[Mapbox access token](https://www.mapbox.com/help/define-access-token/) to
used by all instances of MGLMapView in the current application.
Mapbox-hosted vector tiles and styles require an API access token, which you
can obtain from the
[Mapbox account page](https://www.mapbox.com/studio/account/tokens/). 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.
@param accessToken A Mapbox access token. Calling this method with a value
of `nil` has no effect.
@note You must set the access token before attempting to load any
Mapbox-hosted style. Therefore, you should generally set it before
creating an instance of MGLMapView. The recommended way to set an access
token is to add an entry to your application’s Info.plist file with the
key `MGLMapboxAccessToken` and the type String. Alternatively, you may
call this method from your application delegate’s
-applicationDidFinishLaunching: method. */
+ (void)setAccessToken:(nullable NSString *)accessToken;
/** Retreive the Mapbox API access token for the framework.
*
* You can set an access token on MGLAccountManager or on an individual map view. The same token is used throughout the framework.
* @return accessToken The Mapbox API access token. */
/** Returns the
[Mapbox access token](https://www.mapbox.com/help/define-access-token/) in
use by instances of MGLMapView in the current application. */
+ (nullable NSString *)accessToken;
@end

View File

@@ -4,15 +4,53 @@
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. */
@interface MGLAnnotationImage : NSObject
#pragma mark Initializing and preparing the image object
/** @name 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. */
+ (instancetype)annotationImageWithImage:(NSImage *)image reuseIdentifier:(NSString *)reuseIdentifier;
#pragma mark Getting and setting attributes
/** @name 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.
*/
@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.
*/
@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

View File

@@ -19,13 +19,12 @@ NS_ASSUME_NONNULL_BEGIN
// with the existing NSURL property. Fortunately, IB strips out the two
// underscores for display.
/**
URL of the style currently displayed in the receiver.
/** 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.
*/
relative to the application’s resource path. Leave this field blank for the
default style. */
@property (nonatomic, nullable) IBInspectable NSString *styleURL__;
// Convenience properties related to the initial viewport. These properties
@@ -46,28 +45,20 @@ NS_ASSUME_NONNULL_BEGIN
// inspectable from the runtime name, but runtime names don’t always make sense
// in UI.
/**
A Boolean value that determines whether the user may zoom the map, changing
its zoom level.
*/
/** A Boolean value that determines whether the user may zoom the map, changing
its zoom level. */
@property (nonatomic) IBInspectable BOOL allowsZooming;
/**
A Boolean value that determines whether the user may scroll around the map,
changing its center coordinate.
*/
/** A Boolean value that determines whether the user may scroll around the map,
changing its center coordinate. */
@property (nonatomic) IBInspectable BOOL allowsScrolling;
/**
A Boolean value that determines whether the user may rotate the map,
changing its direction.
*/
/** A Boolean value that determines whether the user may rotate the map,
changing its direction. */
@property (nonatomic) IBInspectable BOOL allowsRotating;
/**
A Boolean value that determines whether the user may tilt the map, changing
its pitch.
*/
/** A Boolean value that determines whether the user may tilt the map, changing
its pitch. */
@property (nonatomic) IBInspectable BOOL allowsTilting;
#endif

View File

@@ -5,10 +5,20 @@
NS_ASSUME_NONNULL_BEGIN
/** Options for enabling debugging features in an MGLMapView instance. */
typedef NS_OPTIONS(NSUInteger, MGLMapDebugMaskOptions) {
/** Edges of tile boundaries are shown as thick, red lines to help diagnose
tile clipping issues. */
MGLMapDebugTileBoundariesMask = 1 << 1,
/** Each tile shows its tile coordinate (x/y/z) in the upper-left corner. */
MGLMapDebugTileInfoMask = 1 << 2,
/** Each tile shows a timestamp indicating when it was loaded. */
MGLMapDebugTimestampsMask = 1 << 3,
/** Edges of glyphs and symbols are shown as faint, green lines to help
diagnose collision and label placement issues. */
MGLMapDebugCollisionBoxesMask = 1 << 4,
};
@@ -18,78 +28,461 @@ 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
[Mapbox Vector Tile Specification](https://github.com/mapbox/vector-tile-spec).
It styles them with a style that conforms to the
[Mapbox GL style specification](https://www.mapbox.com/mapbox-gl-style-spec/).
Such styles can be designed in [Mapbox Studio](https://www.mapbox.com/studio/)
and hosted on mapbox.com.
A collection of Mapbox-hosted styles is available through the MGLStyle
class. These basic styles use
[Mapbox Streets](https://www.mapbox.com/developers/vector-tiles/mapbox-streets)
or [Mapbox Satellite](https://www.mapbox.com/satellite/) 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
[Mapbox account page](https://www.mapbox.com/studio/account/tokens/). 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 */
/** 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:(CGRect)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. */
- (instancetype)initWithFrame:(CGRect)frame styleURL:(nullable NSURL *)styleURL;
#pragma mark Accessing the delegate
/** @name 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. */
@property (nonatomic, weak, nullable) IBOutlet id <MGLMapViewDelegate> delegate;
#pragma mark Configuring the map’s appearance
/** @name 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. */
@property (nonatomic, null_resettable) NSURL *styleURL;
/** 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. */
- (IBAction)reloadStyle:(id)sender;
/** 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.
*/
@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,
[requires](https://www.mapbox.com/help/mapbox-logo/) 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,
[requires](https://www.mapbox.com/help/attribution/) 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 */
/** 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. */
- (void)setCenterCoordinate:(CLLocationCoordinate2D)coordinate animated:(BOOL)animated;
/**
The zoom level of the receiver.
/** 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 that can be displayed by the receiver using the
current style. */
@property (nonatomic, readonly) double maximumZoomLevel;
/** The maximum zoom level that can be displayed by the receiver using the
current style. */
@property (nonatomic, readonly) double minimumZoomLevel;
/** 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.
*/
@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. */
- (void)setDirection:(CLLocationDirection)direction animated:(BOOL)animated;
/** 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;
@property (nonatomic, getter=isScrollEnabled) BOOL scrollEnabled;
/** 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;
#pragma mark Configuring gesture recognition
/** @name 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. */
@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. */
@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. */
@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. */
@property (nonatomic, getter=isPitchEnabled) BOOL pitchEnabled;
#pragma mark Annotating the map
/** @name 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`. */
@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. */
- (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. */
- (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. */
- (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. */
- (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. */
- (nullable MGLAnnotationImage *)dequeueReusableAnnotationImageWithIdentifier:(NSString *)identifier;
#pragma mark Managing annotation selections
/** @name Managing Annotation Selections */
/** 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;
- (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
- (void)deselectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated;
/** 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. */
- (void)deselectAnnotation:(id <MGLAnnotation>)annotation;
#pragma mark Finding annotations
/** @name 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.
*/
- (id <MGLAnnotation>)annotationAtPoint:(NSPoint)point;
#pragma mark Overlaying the map
/** @name 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. */
- (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. */
- (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. */
- (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. */
- (void)removeOverlays:(NS_ARRAY_OF(id <MGLOverlay>) *)overlays;
- (CLLocationCoordinate2D)convertPoint:(NSPoint)point toCoordinateFromView:(nullable NSView *)view;
#pragma mark Converting geographic coordinates
/** @name 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. */
- (NSPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable NSView *)view;
- (MGLCoordinateBounds)convertRectToCoordinateBounds:(NSRect)rect;
/** 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. */
- (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. */
- (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. */
- (CLLocationDistance)metersPerPointAtLatitude:(CLLocationDegrees)latitude;
#pragma mark Debugging the map
/** @name 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. */
@property (nonatomic) MGLMapDebugMaskOptions debugMask;
@end

View File

@@ -10,15 +10,68 @@ 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. */
@protocol MGLMapViewDelegate <NSObject>
@optional
- (void)mapView:(MGLMapView *)mapView regionWillChangeAnimated:(BOOL)animated;
- (void)mapViewRegionIsChanging:(MGLMapView *)mapView;
- (void)mapView:(MGLMapView *)mapView regionDidChangeAnimated:(BOOL)animated;
#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.
*/
- (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. */
- (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. */
- (void)mapView:(MGLMapView *)mapView cameraDidChangeAnimated:(BOOL)animated;
#pragma mark Loading the map
/** @name 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. */
- (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. */
- (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapView;
- (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView;
@@ -26,17 +79,118 @@ 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. */
- (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. */
- (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 black. 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 blue. 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. */
- (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotation;
- (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation;
- (nullable NSViewController *)mapView:(MGLMapView *)mapView calloutViewControllerForAnnotation:(id <MGLAnnotation>)annotation;
#pragma mark Selecting annotations
/** @name 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. */
- (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. */
- (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.
*/
- (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.
@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
NS_ASSUME_NONNULL_END

View File

@@ -1,3 +0,0 @@
#import "MGLGeometry.h"
const MGLCoordinateSpan MGLCoordinateSpanZero = {0, 0};

View File

@@ -0,0 +1,21 @@
#import "MGLGeometry_Private.h"
const MGLCoordinateSpan MGLCoordinateSpanZero = {0, 0};
CGRect MGLExtendRect(CGRect rect, CGPoint point) {
if (point.x < rect.origin.x) {
rect.size.width += rect.origin.x - point.x;
rect.origin.x = point.x;
}
if (point.x > rect.origin.x + rect.size.width) {
rect.size.width += point.x - (rect.origin.x + rect.size.width);
}
if (point.y < rect.origin.y) {
rect.size.height += rect.origin.y - point.y;
rect.origin.y = point.y;
}
if (point.y > rect.origin.y + rect.size.height) {
rect.size.height += point.y - (rect.origin.y + rect.size.height);
}
return rect;
}

View File

@@ -1,10 +1,17 @@
#import "MGLGeometry.h"
#import <TargetConditionals.h>
#if TARGET_OS_IPHONE
#import <UIKit/UIKit.h>
#endif
#import <mbgl/map/map.hpp>
#import <mbgl/util/geo.hpp>
/// Returns the smallest rectangle that contains both the given rectangle and
/// the given point.
CGRect MGLExtendRect(CGRect rect, CGPoint point);
NS_INLINE mbgl::LatLng MGLLatLngFromLocationCoordinate2D(CLLocationCoordinate2D coordinate) {
return mbgl::LatLng(coordinate.latitude, coordinate.longitude);
}
@@ -28,12 +35,12 @@ NS_INLINE BOOL MGLCoordinateInCoordinateBounds(CLLocationCoordinate2D coordinate
return bounds.contains(MGLLatLngFromLocationCoordinate2D(coordinate));
}
#if TARGET_OS_MAC
NS_INLINE mbgl::EdgeInsets MGLEdgeInsetsFromNSEdgeInsets(NSEdgeInsets insets) {
return { insets.top, insets.left, insets.bottom, insets.right };
}
#elif TARGET_OS_IOS
#if TARGET_OS_IPHONE
NS_INLINE mbgl::EdgeInsets MGLEdgeInsetsFromNSEdgeInsets(UIEdgeInsets insets) {
return { insets.top, insets.left, insets.bottom, insets.right };
}
#else
NS_INLINE mbgl::EdgeInsets MGLEdgeInsetsFromNSEdgeInsets(NSEdgeInsets insets) {
return { insets.top, insets.left, insets.bottom, insets.right };
}
#endif

View File

@@ -317,7 +317,7 @@ static NSString * const MGLDroppedPinAnnotationImageIdentifier = @"dropped";
- (void)dropPinAtPoint:(NSPoint)point {
DroppedPinAnnotation *annotation = [self pinAtPoint:point];
[self.mapView addAnnotation:annotation];
[self.mapView selectAnnotation:annotation animated:YES];
[self.mapView selectAnnotation:annotation];
}
- (DroppedPinAnnotation *)pinAtPoint:(NSPoint)point {

View File

@@ -465,6 +465,22 @@ public:
_delegateHasStrokeColorsForShapeAnnotations = [_delegate respondsToSelector:@selector(mapView:strokeColorForShapeAnnotation:)];
_delegateHasFillColorsForShapeAnnotations = [_delegate respondsToSelector:@selector(mapView:fillColorForPolygonAnnotation:)];
_delegateHasLineWidthsForShapeAnnotations = [_delegate respondsToSelector:@selector(mapView:lineWidthForPolylineAnnotation:)];
if ([self.delegate respondsToSelector:@selector(mapView:regionWillChangeAnimated:)]) {
NSLog(@"-mapView:regionWillChangeAnimated: is not supported by the OS X SDK, but %@ implements it anyways. "
@"Please implement -[%@ mapView:cameraWillChangeAnimated:] instead.",
NSStringFromClass([delegate class]), NSStringFromClass([delegate class]));
}
if ([self.delegate respondsToSelector:@selector(mapViewRegionIsChanging:)]) {
NSLog(@"-mapViewRegionIsChanging: is not supported by the OS X SDK, but %@ implements it anyways. "
@"Please implement -[%@ mapViewCameraIsChanging:] instead.",
NSStringFromClass([delegate class]), NSStringFromClass([delegate class]));
}
if ([self.delegate respondsToSelector:@selector(mapView:regionDidChangeAnimated:)]) {
NSLog(@"-mapView:regionDidChangeAnimated: is not supported by the OS X SDK, but %@ implements it anyways. "
@"Please implement -[%@ mapView:cameraDidChangeAnimated:] instead.",
NSStringFromClass([delegate class]), NSStringFromClass([delegate class]));
}
}
#pragma mark Style
@@ -507,7 +523,7 @@ public:
#pragma mark View hierarchy and drawing
- (void)viewWillMoveToWindow:(NSWindow *)newWindow {
[self deselectAnnotation:self.selectedAnnotation animated:NO];
[self deselectAnnotation:self.selectedAnnotation];
if (!self.dormant && !newWindow) {
self.dormant = YES;
_mbglMap->pause();
@@ -661,9 +677,9 @@ public:
case mbgl::MapChangeRegionWillChange:
case mbgl::MapChangeRegionWillChangeAnimated:
{
if ([self.delegate respondsToSelector:@selector(mapView:regionWillChangeAnimated:)]) {
if ([self.delegate respondsToSelector:@selector(mapView:cameraWillChangeAnimated:)]) {
BOOL animated = change == mbgl::MapChangeRegionWillChangeAnimated;
[self.delegate mapView:self regionWillChangeAnimated:animated];
[self.delegate mapView:self cameraWillChangeAnimated:animated];
}
break;
}
@@ -674,8 +690,8 @@ public:
[self updateCompass];
[self updateAnnotationCallouts];
if ([self.delegate respondsToSelector:@selector(mapViewRegionIsChanging:)]) {
[self.delegate mapViewRegionIsChanging:self];
if ([self.delegate respondsToSelector:@selector(mapViewCameraIsChanging:)]) {
[self.delegate mapViewCameraIsChanging:self];
}
break;
}
@@ -692,9 +708,9 @@ public:
[self updateAnnotationCallouts];
[self updateAnnotationTrackingAreas];
if ([self.delegate respondsToSelector:@selector(mapView:regionDidChangeAnimated:)]) {
if ([self.delegate respondsToSelector:@selector(mapView:cameraDidChangeAnimated:)]) {
BOOL animated = change == mbgl::MapChangeRegionDidChangeAnimated;
[self.delegate mapView:self regionDidChangeAnimated:animated];
[self.delegate mapView:self cameraDidChangeAnimated:animated];
}
break;
}
@@ -846,7 +862,7 @@ public:
}
- (MGLCoordinateBounds)visibleCoordinateBounds {
return [self convertRectToCoordinateBounds:self.bounds];
return [self convertRect:self.bounds toCoordinateBoundsFromView:self];
}
- (void)setVisibleCoordinateBounds:(MGLCoordinateBounds)bounds {
@@ -990,10 +1006,10 @@ public:
if (hitAnnotationTag != _selectedAnnotationTag) {
id <MGLAnnotation> annotation = [self annotationWithTag:hitAnnotationTag];
NSAssert(annotation, @"Cannot select nonexistent annotation with ID %i", hitAnnotationTag);
[self selectAnnotation:annotation animated:YES];
[self selectAnnotation:annotation];
}
} else {
[self deselectAnnotation:self.selectedAnnotation animated:YES];
[self deselectAnnotation:self.selectedAnnotation];
}
}
@@ -1353,7 +1369,7 @@ public:
_annotationContextsByAnnotationTag.erase(annotationTag);
if (annotationTag == _selectedAnnotationTag) {
[self deselectAnnotation:annotation animated:NO];
[self deselectAnnotation:annotation];
}
if (annotationTag == _lastSelectedAnnotationTag) {
@@ -1481,7 +1497,7 @@ public:
/// Returns the tags of the annotations coincident with the given rectangle.
- (std::vector<MGLAnnotationTag>)annotationTagsInRect:(NSRect)rect {
mbgl::LatLngBounds queryBounds = [self convertRectToLatLngBounds:rect];
mbgl::LatLngBounds queryBounds = [self convertRect:rect toLatLngBoundsFromView:self];
return _mbglMap->getPointAnnotationsInBounds(queryBounds);
}
@@ -1507,11 +1523,11 @@ public:
// Select the annotation if it’s visible.
if (MGLCoordinateInCoordinateBounds(firstAnnotation.coordinate, self.visibleCoordinateBounds)) {
[self selectAnnotation:firstAnnotation animated:NO];
[self selectAnnotation:firstAnnotation];
}
}
- (void)selectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated
- (void)selectAnnotation:(id <MGLAnnotation>)annotation
{
// Only point annotations can be selected.
if (!annotation || [annotation isKindOfClass:[MGLMultiPoint class]]) {
@@ -1524,7 +1540,7 @@ public:
}
// Deselect the annotation before reselecting it.
[self deselectAnnotation:selectedAnnotation animated:NO];
[self deselectAnnotation:selectedAnnotation];
// Add the annotation to the map if it hasn’t been added yet.
MGLAnnotationTag annotationTag = [self annotationTagForAnnotation:annotation];
@@ -1552,7 +1568,6 @@ public:
&& [self.delegate respondsToSelector:@selector(mapView:annotationCanShowCallout:)]
&& [self.delegate mapView:self annotationCanShowCallout:annotation]) {
NSPopover *callout = [self calloutForAnnotation:annotation];
callout.animates = animated;
// Hang the callout off the right edge of the annotation image’s
// alignment rect, or off the left edge in a right-to-left UI.
@@ -1626,14 +1641,13 @@ public:
return [self dequeueReusableAnnotationImageWithIdentifier:symbolName];
}
- (void)deselectAnnotation:(id <MGLAnnotation>)annotation animated:(BOOL)animated {
- (void)deselectAnnotation:(id <MGLAnnotation>)annotation {
if (!annotation || self.selectedAnnotation != annotation) {
return;
}
// Close the callout popover gracefully.
NSPopover *callout = self.calloutForSelectedAnnotation;
callout.animates = animated;
[callout performClose:self];
self.selectedAnnotation = nil;
@@ -1821,40 +1835,50 @@ public:
#pragma mark Geometric methods
- (CLLocationCoordinate2D)convertPoint:(NSPoint)point toCoordinateFromView:(nullable NSView *)view {
return MGLLocationCoordinate2DFromLatLng([self convertPoint:point toLatLngFromView:view]);
}
/// Converts a point in the view’s coordinate system to a coordinate pair.
- (mbgl::LatLng)convertPoint:(NSPoint)point toLatLngFromView:(nullable NSView *)view {
NSPoint convertedPoint = [self convertPoint:point fromView:view];
return _mbglMap->latLngForPixel(mbgl::PrecisionPoint(convertedPoint.x, convertedPoint.y));
}
- (NSPoint)convertCoordinate:(CLLocationCoordinate2D)coordinate toPointToView:(nullable NSView *)view {
return [self convertLatLng:MGLLatLngFromLocationCoordinate2D(coordinate) toPointToView:view];
}
/// Converts a coordinate pair to a point in the view’s coordinate system.
/// Converts a geographic coordinate to a point in the view’s coordinate system.
- (NSPoint)convertLatLng:(mbgl::LatLng)latLng toPointToView:(nullable NSView *)view {
mbgl::vec2<double> pixel = _mbglMap->pixelForLatLng(latLng);
return [self convertPoint:NSMakePoint(pixel.x, pixel.y) toView:view];
}
/// Converts a rectangle in the view’s coordinate system to a coordinate
/// bounding box.
- (MGLCoordinateBounds)convertRectToCoordinateBounds:(NSRect)rect {
return MGLCoordinateBoundsFromLatLngBounds([self convertRectToLatLngBounds:rect]);
- (CLLocationCoordinate2D)convertPoint:(NSPoint)point toCoordinateFromView:(nullable NSView *)view {
return MGLLocationCoordinate2DFromLatLng([self convertPoint:point toLatLngFromView:view]);
}
/// Converts a rectangle in the view’s coordinate system to a coordinate
/// Converts a point in the view’s coordinate system to a geographic coordinate.
- (mbgl::LatLng)convertPoint:(NSPoint)point toLatLngFromView:(nullable NSView *)view {
NSPoint convertedPoint = [self convertPoint:point fromView:view];
return _mbglMap->latLngForPixel(mbgl::PrecisionPoint(convertedPoint.x, convertedPoint.y));
}
- (NSRect)convertCoordinateBounds:(MGLCoordinateBounds)bounds toRectToView:(nullable NSView *)view {
return [self convertLatLngBounds:MGLLatLngBoundsFromCoordinateBounds(bounds) toRectToView:view];
}
/// Converts a geographic bounding box to a rectangle in the view’s coordinate
/// system.
- (NSRect)convertLatLngBounds:(mbgl::LatLngBounds)bounds toRectToView:(nullable NSView *)view {
NSRect rect = { [self convertLatLng:bounds.sw toPointToView:view], NSZeroSize };
rect = MGLExtendRect(rect, [self convertLatLng:bounds.ne toPointToView:view]);
return rect;
}
- (MGLCoordinateBounds)convertRect:(NSRect)rect toCoordinateBoundsFromView:(nullable NSView *)view {
return MGLCoordinateBoundsFromLatLngBounds([self convertRect:rect toLatLngBoundsFromView:view]);
}
/// Converts a rectangle in the given view’s coordinate system to a geographic
/// bounding box.
- (mbgl::LatLngBounds)convertRectToLatLngBounds:(NSRect)rect {
- (mbgl::LatLngBounds)convertRect:(NSRect)rect toLatLngBoundsFromView:(nullable NSView *)view {
mbgl::LatLngBounds bounds = mbgl::LatLngBounds::getExtendable();
bounds.extend([self convertPoint:rect.origin toLatLngFromView:self]);
bounds.extend([self convertPoint:{ NSMaxX(rect), NSMinY(rect) } toLatLngFromView:self]);
bounds.extend([self convertPoint:{ NSMaxX(rect), NSMaxY(rect) } toLatLngFromView:self]);
bounds.extend([self convertPoint:{ NSMinX(rect), NSMaxY(rect) } toLatLngFromView:self]);
bounds.extend([self convertPoint:rect.origin toLatLngFromView:view]);
bounds.extend([self convertPoint:{ NSMaxX(rect), NSMinY(rect) } toLatLngFromView:view]);
bounds.extend([self convertPoint:{ NSMaxX(rect), NSMaxY(rect) } toLatLngFromView:view]);
bounds.extend([self convertPoint:{ NSMinX(rect), NSMaxY(rect) } toLatLngFromView:view]);
// The world is wrapping if a point just outside the bounds is also within
// the rect.
@@ -1872,7 +1896,7 @@ public:
}
// If the world is wrapping, extend the bounds to cover all longitudes.
if (NSPointInRect([self convertLatLng:outsideLatLng toPointToView:self], rect)) {
if (NSPointInRect([self convertLatLng:outsideLatLng toPointToView:view], rect)) {
bounds.sw.longitude = -180;
bounds.ne.longitude = 180;
}