diff options
Diffstat (limited to 'platform/osx/src/MGLMapViewDelegate.h')
| -rw-r--r-- | platform/osx/src/MGLMapViewDelegate.h | 307 |
1 files changed, 164 insertions, 143 deletions
diff --git a/platform/osx/src/MGLMapViewDelegate.h b/platform/osx/src/MGLMapViewDelegate.h index fcd013284d..0b7eec84ac 100644 --- a/platform/osx/src/MGLMapViewDelegate.h +++ b/platform/osx/src/MGLMapViewDelegate.h @@ -10,68 +10,77 @@ NS_ASSUME_NONNULL_BEGIN @class MGLPolyline; @class MGLShape; -/** The MGLMapViewDelegate protocol defines a set of optional methods that you - can use to receive messages from an MGLMapView instance. Because many map - operations require the MGLMapView class to load data asynchronously, the map - view calls these methods to notify your application when specific operations - complete. The map view also uses these methods to request information about - annotations displayed on the map, such as the styles and interaction modes - to apply to individual annotations. */ +/** + The `MGLMapViewDelegate` protocol defines a set of optional methods that you + can use to receive messages from an `MGLMapView` instance. Because many map + operations require the `MGLMapView` class to load data asynchronously, the map + view calls these methods to notify your application when specific operations + complete. The map view also uses these methods to request information about + annotations displayed on the map, such as the styles and interaction modes to + apply to individual annotations. + */ @protocol MGLMapViewDelegate <NSObject> @optional -#pragma mark Responding to map viewpoint changes -/** @name Responding to Map Viewpoint Changes */ - -/** Tells the delegate that the viewpoint depicted by the map view is about to - change. - - This method is called whenever the currently displayed map camera will start - changing for any reason. - - @param mapView The map view whose viewpoint will change. - @param animated Whether the change will cause an animated effect on the map. +#pragma mark Responding to Map Viewpoint Changes + +/** + Tells the delegate that the viewpoint depicted by the map view is about to + change. + + This method is called whenever the currently displayed map camera will start + changing for any reason. + + @param mapView The map view whose viewpoint will change. + @param animated Whether the change will cause an animated effect on the map. */ - (void)mapView:(MGLMapView *)mapView cameraWillChangeAnimated:(BOOL)animated; -/** Tells the delegate that the viewpoint depicted by the map view is changing. - - This method is called as the currently displayed map camera changes due to - animation. During movement, this method may be called many times to report - updates to the viewpoint. Therefore, your implementation of this method - should be as lightweight as possible to avoid affecting performance. - - @param mapView The map view whose viewpoint is changing. */ +/** + Tells the delegate that the viewpoint depicted by the map view is changing. + + This method is called as the currently displayed map camera changes due to + animation. During movement, this method may be called many times to report + updates to the viewpoint. Therefore, your implementation of this method should + be as lightweight as possible to avoid affecting performance. + + @param mapView The map view whose viewpoint is changing. + */ - (void)mapViewCameraIsChanging:(MGLMapView *)mapView; -/** Tells the delegate that the viewpoint depicted by the map view has finished - changing. - - This method is called whenever the currently displayed map camera has - finished changing. - - @param mapView The map view whose viewpoint has changed. - @param animated Whether the change caused an animated effect on the map. */ +/** + Tells the delegate that the viewpoint depicted by the map view has finished + changing. + + This method is called whenever the currently displayed map camera has finished + changing. + + @param mapView The map view whose viewpoint has changed. + @param animated Whether the change caused an animated effect on the map. + */ - (void)mapView:(MGLMapView *)mapView cameraDidChangeAnimated:(BOOL)animated; -#pragma mark Loading the map -/** @name Loading the Map */ +#pragma mark Loading the Map -/** Tells the delegate that the map view will begin to load. - - This method is called whenever the map view starts loading, including when a - new style has been set and the map must reload. - - @param mapView The map view that is starting to load. */ +/** + Tells the delegate that the map view will begin to load. + + This method is called whenever the map view starts loading, including when a + new style has been set and the map must reload. + + @param mapView The map view that is starting to load. + */ - (void)mapViewWillStartLoadingMap:(MGLMapView *)mapView; -/** Tells the delegate that the map view has finished loading. - - This method is called whenever the map view finishes loading, either after - the initial load or after a style change has forced a reload. - - @param mapView The map view that has finished loading. */ +/** + Tells the delegate that the map view has finished loading. + + This method is called whenever the map view finishes loading, either after the + initial load or after a style change has forced a reload. + + @param mapView The map view that has finished loading. + */ - (void)mapViewDidFinishLoadingMap:(MGLMapView *)mapView; - (void)mapViewWillStartRenderingMap:(MGLMapView *)mapView; @@ -79,119 +88,131 @@ NS_ASSUME_NONNULL_BEGIN - (void)mapViewWillStartRenderingFrame:(MGLMapView *)mapView; - (void)mapViewDidFinishRenderingFrame:(MGLMapView *)mapView fullyRendered:(BOOL)fullyRendered; -#pragma mark Managing the display of annotations -/** @name Managing the Display of Annotations */ - -/** Returns an annotation image object to mark the given point annotation object - on the map. - - @param mapView The map view that requested the annotation image. - @param annotation The object representing the annotation that is about to be - displayed. - @return The image object to display for the given annotation or `nil` if you - want to display the default marker image. */ +#pragma mark Managing the Display of Annotations + +/** + Returns an annotation image object to mark the given point annotation object on + the map. + + @param mapView The map view that requested the annotation image. + @param annotation The object representing the annotation that is about to be + displayed. + @return The image object to display for the given annotation or `nil` if you + want to display the default marker image. + */ - (nullable MGLAnnotationImage *)mapView:(MGLMapView *)mapView imageForAnnotation:(id <MGLAnnotation>)annotation; -/** Returns the alpha value to use when rendering a shape annotation. - - A value of 0.0 results in a completely transparent shape. A value of 1.0, - the default, results in a completely opaque shape. - - @param mapView The map view rendering the shape annotation. - @param annotation The annotation being rendered. - @return An alpha value between 0 and 1.0. */ +/** + Returns the alpha value to use when rendering a shape annotation. + + A value of 0.0 results in a completely transparent shape. A value of 1.0, the + default, results in a completely opaque shape. + + @param mapView The map view rendering the shape annotation. + @param annotation The annotation being rendered. + @return An alpha value between 0 and 1.0. + */ - (CGFloat)mapView:(MGLMapView *)mapView alphaForShapeAnnotation:(MGLShape *)annotation; -/** Returns the color to use when rendering the outline of a shape annotation. - - The default stroke color is the selected menu item color. If a pattern - color is specified, the result is undefined. - - @param mapView The map view rendering the shape annotation. - @param annotation The annotation being rendered. - @return A color to use for the shape outline. */ +/** + Returns the color to use when rendering the outline of a shape annotation. + + The default stroke color is the selected menu item color. If a pattern color is + specified, the result is undefined. + + @param mapView The map view rendering the shape annotation. + @param annotation The annotation being rendered. + @return A color to use for the shape outline. + */ - (NSColor *)mapView:(MGLMapView *)mapView strokeColorForShapeAnnotation:(MGLShape *)annotation; -/** Returns the color to use when rendering the fill of a polygon annotation. - - The default fill color is selected menu item color. If a pattern color - is specified, the result is undefined. - - @param mapView The map view rendering the polygon annotation. - @param annotation The annotation being rendered. - @return The polygon’s interior fill color. */ +/** + Returns the color to use when rendering the fill of a polygon annotation. + + The default fill color is selected menu item color. If a pattern color is + specified, the result is undefined. + + @param mapView The map view rendering the polygon annotation. + @param annotation The annotation being rendered. + @return The polygon’s interior fill color. + */ - (NSColor *)mapView:(MGLMapView *)mapView fillColorForPolygonAnnotation:(MGLPolygon *)annotation; -/** Returns the line width in points to use when rendering the outline of a - polyline annotation. - - By default, the polyline is outlined with a line 3.0 points wide. - - @param mapView The map view rendering the polygon annotation. - @param annotation The annotation being rendered. - @return A line width for the polyline, measured in points. */ +/** + Returns the line width in points to use when rendering the outline of a + polyline annotation. + + By default, the polyline is outlined with a line 3.0 points wide. + + @param mapView The map view rendering the polygon annotation. + @param annotation The annotation being rendered. + @return A line width for the polyline, measured in points. + */ - (CGFloat)mapView:(MGLMapView *)mapView lineWidthForPolylineAnnotation:(MGLPolyline *)annotation; -#pragma mark Selecting annotations -/** @name Selecting annotations */ +#pragma mark Selecting Annotations -/** Tells the delegate that one of its annotations has been selected. - - You can use this method to track changes to the selection state of - annotations. - - @param mapView The map view containing the annotation. - @param annotation The annotation that was selected. */ +/** + Tells the delegate that one of its annotations has been selected. + + You can use this method to track changes to the selection state of annotations. + + @param mapView The map view containing the annotation. + @param annotation The annotation that was selected. + */ - (void)mapView:(MGLMapView *)mapView didSelectAnnotation:(id <MGLAnnotation>)annotation; -/** Tells the delegate that one of its annotations has been deselected. - - You can use this method to track changes in the selection state of - annotations. - - @param mapView The map view containing the annotation. - @param annotation The annotation that was deselected. */ +/** + Tells the delegate that one of its annotations has been deselected. + + You can use this method to track changes in the selection state of annotations. + + @param mapView The map view containing the annotation. + @param annotation The annotation that was deselected. + */ - (void)mapView:(MGLMapView *)mapView didDeselectAnnotation:(id <MGLAnnotation>)annotation; -#pragma mark Displaying information about annotations -/** @name Displaying Information About Annotations */ - -/** Returns a Boolean value indicating whether the annotation is able to display - extra information in a callout popover. - - This method is called after an annotation is selected, before any callout is - displayed for the annotation. - - If the return value is `YES`, a callout popover is shown when the user - clicks on a selected annotation. The default callout displays the - annotation’s title and subtitle. You can customize the popover’s contents by - implementing the -mapView:calloutViewControllerForAnnotation: method. - - If the return value is `NO`, or if this method is unimplemented, or if the - annotation lacks a title, the annotation will not show a callout even when - selected. - - @param mapView The map view that has selected the annotation. - @param annotation The object representing the annotation. - @return A Boolean value indicating whether the annotation should show a - callout. +#pragma mark Displaying Information About Annotations + +/** + Returns a Boolean value indicating whether the annotation is able to display + extra information in a callout popover. + + This method is called after an annotation is selected, before any callout is + displayed for the annotation. + + If the return value is `YES`, a callout popover is shown when the user clicks + on a selected annotation. The default callout displays the annotation’s title + and subtitle. You can customize the popover’s contents by implementing the + `-mapView:calloutViewControllerForAnnotation:` method. + + If the return value is `NO`, or if this method is unimplemented, or if the + annotation lacks a title, the annotation will not show a callout even when + selected. + + @param mapView The map view that has selected the annotation. + @param annotation The object representing the annotation. + @return A Boolean value indicating whether the annotation should show a + callout. */ - (BOOL)mapView:(MGLMapView *)mapView annotationCanShowCallout:(id <MGLAnnotation>)annotation; -/** Returns a view controller to manage the callout popover’s content view. - - Like any instance of NSPopover, an annotation callout manages its contents - with a view controller. The annotation object is the view controller’s - represented object. This means that you can bind controls in the view - controller’s content view to KVO-compliant properties of the annotation - object, such as -title and -subtitle. - - If each annotation should have an identical callout, you can set the - MGLMapView instance’s -setCalloutViewController: method instead. - - @param mapView The map view that is requesting a callout view controller. - @param annotation The object representing the annotation. - @return A view controller for the given annotation. */ +/** + Returns a view controller to manage the callout popover’s content view. + + Like any instance of `NSPopover`, an annotation callout manages its contents + with a view controller. The annotation object is the view controller’s + represented object. This means that you can bind controls in the view + controller’s content view to KVO-compliant properties of the annotation object, + such as `title` and `subtitle`. + + If each annotation should have an identical callout, you can set the + `MGLMapView` instance’s `-setCalloutViewController:` method instead. + + @param mapView The map view that is requesting a callout view controller. + @param annotation The object representing the annotation. + @return A view controller for the given annotation. + */ - (nullable NSViewController *)mapView:(MGLMapView *)mapView calloutViewControllerForAnnotation:(id <MGLAnnotation>)annotation; @end |