-
Notifications
You must be signed in to change notification settings - Fork 1
MapController
The map controller handles basic map options and controls for a MKMapView. It provides automatic functions for adding/removing annotations, finding directions, zooming the map view and searching the annotations plotted on the map.
Declaration
Swift
private let minimumZoomArc = 0.007 //approximately 1/2 mile (1 degree of arc ~= 69 miles)
---
<br>
### maximumDegreesArc
**Declaration**
> <sub>**Swift**</sub>
> ```swift
private let maximumDegreesArc: Double = 360
Declaration
Swift
private let annotationRegionPadFactor: Double = 1.15
---
<br>
### identifier
The reuse identifier for the annotations for the map view. This should be overriden when subclassing.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open var identifier: String
Dictates if the users location has been initially plotted.
Declaration
Swift
public var hasPlottedInitUsersLocation = false
---
<br>
### failedToPlotUsersLocation
Dictates if the users location was not able to be plotted, due permissions issues, etc.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public var failedToPlotUsersLocation = false
The view controller related to the map controller.
Declaration
Swift
@IBOutlet public weak var viewController: UIViewController!
---
<br>
### mapView
The map view related to the map controller.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
@IBOutlet public weak var mapView: MKMapView?
Used for plotting all annotations to ditermine annotation clustering.
Declaration
Swift
public let offscreenMapView = MKMapView(frame: CGRect())
---
<br>
### _mapView
Private instance of map view, that returns the offscreen map view only if clustering is on.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
private var _mapView: MKMapView?
Determins if the map controller should cluster the annotations on the map, or plot them all directly. THe default is true.
Declaration
Swift
@IBInspectable public var shouldUseAnnotationClustering: Bool = true
---
<br>
### marginFactor
This value controls the number of off screen annotations displayed.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
@IBInspectable public var marginFactor: Double = 2
Adjust this based on the deimensions of your annotation views.
Declaration
Swift
@IBInspectable public var bucketSize: Double = 60
---
<br>
### currentlyUpdatingVisableAnnotations
**Declaration**
> <sub>**Swift**</sub>
> ```swift
private var currentlyUpdatingVisableAnnotations = false
Declaration
Swift
private var shouldTryToUpdateVisableAnnotationsAgain = false
---
<br>
### autoAssingDelegate
**Declaration**
> <sub>**Swift**</sub>
> ```swift
@IBInspectable var autoAssingDelegate: Bool = true
true if the user is currently being tracked in the map view or false if not.
Declaration
Swift
public var trackingUser: Bool = false
---
<br>
### shouldRequestLocationServices
Determins if the location manager should request access to location services on setup. By default this is set to false.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
@IBInspectable public var shouldRequestLocationServices: Bool = false
The location manager automatically created when assigning the map view to the map controller. It’s only use if for getting the user’s access to location services.
Declaration
Swift
private var locationManager: CLLocationManager?
---
<br>
### addresses
An array of addresses plotted on the map view.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public var addresses: [Address]
Declaration
Swift
private var addressesDict = AnyHashable: Address
---
<br>
### annotations
A dictionary of annotations plotted to the map view with the address object as the key.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public var annotations = [AnyHashable: Any]()
When the map automatically zooms to show all, if this value is set to true, then the users annoation is automatically included in that.
Declaration
Swift
@IBInspectable public var zoomToShowAllIncludesUser: Bool = true
---
<br>
### regionSpanBeforeChange
**Declaration**
> <sub>**Swift**</sub>
> ```swift
private var regionSpanBeforeChange: MKCoordinateSpan?
Declaration
Swift
let clusterCalculationsQueue = DispatchQueue.global(qos: .userInitiated)
---
<br>
### cancelClusterCalculations
**Declaration**
> <sub>**Swift**</sub>
> ```swift
var cancelClusterCalculations = false
Declaration
Swift
deinit
---
<br>
### resetMap()
Resets the map controller, clearing the addresses, annotations and removing all annotations and polylines on the map view.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func resetMap()
Attempt to purge the map view to free up some memory.
Declaration
Swift
private func purgeMap()
---
<br>
## Location Services <br>
### requestAccessToLocationServices(_:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public class func requestAccessToLocationServices(_ locationManager: CLLocationManager)
## Plot/Remove Annotations Methods
Plot an array of addresses to the map view.
Declaration
Swift
public func plot(addresses: [Address])
**Parameters**
<table>
<tr><td> `addresses` </td><td> An array of addresses to plot. </td></tr>
<table>
---
<br>
### plot(address:asBulk:)
Plot an address to the map view.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func plot(address: Address, asBulk: Bool = false)
Parameters
| `address` | An address to plot. |
| `asBulk` | Tells the controller if this is part of a bulk command. Leave to false for better performance. |
Remove all annotations plotted to the map.
Declaration
Swift
public func removeAllAnnotations(includingCached: Bool = false)
**Parameters**
<table>
<tr><td> `includingCached` </td><td> If true then the cached annotations dictionary is also cleared. </td></tr>
<table>
---
<br>
### clearData()
Clears all of the annotations from the map, including caced, and clears the addresses array.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func clearData()
## Annotation Clustering
This function is automatically called when an address is added or the map region changes.
Declaration
Swift
public final func updateVisableAnnotations()
---
<br>
### calculateAndUpdateClusterAnnotations(_:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
internal final func calculateAndUpdateClusterAnnotations(_ complete: @escaping () -> Void)
Declaration
Swift
private final func calculateClusterInGrid(mapView: MKMapView, offscreenMapView: MKMapView, gridMapRect: MKMapRect)
---
<br>
### calculatedAnnotationInGrid(mapView:gridMapRect:allAnnotations:visableAnnotations:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
private final func calculatedAnnotationInGrid(mapView: MKMapView, gridMapRect: MKMapRect, allAnnotations: Set<Annotation>, visableAnnotations: Set<Annotation>) -> Annotation?
## Zoom Map Methods
Zoom the map view to a coordinate.
Declaration
Swift
open func zoom(toCoordinate coordinare: CLLocationCoordinate2D)
**Parameters**
<table>
<tr><td> `coordinare` </td><td> The coordinate to zoom to. </td></tr>
<table>
---
<br>
### zoom(toAnnotation:)
Zoom the map view to an annotation.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func zoom(toAnnotation annotation: MKAnnotation)
Parameters
| `annotation` | The annotation to zoom to. |
Zoom the map to show multiple annotations.
Declaration
Swift
open func zoom(toAnnotations annotations: [MKAnnotation])
**Parameters**
<table>
<tr><td> `annotations` </td><td> The annotations to zoom to. </td></tr>
<table>
---
<br>
### zoom(toMapPoints:)
Zoom the map to show multiple map points.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func zoom(toMapPoints points: [MKMapPoint])
Parameters
| `points` | Swift array of MKMapPoints to zoom to. |
Zoom the map to show multiple map points.
Declaration
Swift
open func zoom(toMapPoints points: UnsafeMutablePointer, count: Int)
**Parameters**
<table>
<tr><td> `points` </td><td> C array array of MKMapPoints to zoom to. </td></tr>
<tr><td> `count` </td><td> The number of points in the C array. </td></tr>
<table>
---
<br>
### zoom(toRegion:)
Zoom the map to show a region.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func zoom(toRegion region: MKCoordinateRegion)
Parameters
| `region` | The region to zoom the map to. |
Zoom the map to show the users current location.
Declaration
Swift
open func zoomToCurrentLocation()
---
<br>
### zoomToShowAll(includingUser:)
Zoom the map to show all points plotted on the map.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func zoomToShowAll(includingUser: Bool = true)
Parameters
| `includingUser` | If true then the users annotation is also included in the points. If false then only plotted points are zoomed to. |
Zooms the map to an address object.
Declaration
Swift
open func zoom(toAddress address: Address)
**Parameters**
<table>
<tr><td> `address` </td><td> The address object to zoom to. </td></tr>
<table>
---
<br>
### zoom(toPolyline:)
Zooms the map to a polyline.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func zoom(toPolyline polyline: MKPolyline)
Parameters
| `polyline` | The polyline to zoom to. |
## Polyline and Route Methods
Removes all the polylines plotted on the map view.
Declaration
Swift
public func removeAllPolylines()
---
<br>
### routeBetween(sourceCoordinate:destinationCoordinate:transportType:complete:)
Gets a route between a source and destination.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func routeBetween(sourceCoordinate source: CLLocationCoordinate2D, destinationCoordinate destination: CLLocationCoordinate2D, transportType: MKDirectionsTransportType = .automobile, complete: @escaping (_ route: MKRoute?, _ error: Error?) -> Void)
Parameters
| `source` | The coordinate of the source location. |
| `destination` | The coordinate of the destination location. |
| `transportType` | The transportation type to create the route. |
| `complete` | Returns an optional route and error. |
Gets a route between a source and destination.
Declaration
Swift
public func routeBetween(sourceMapItem source: MKMapItem, destinationMapItem destination: MKMapItem, transportType: MKDirectionsTransportType = .automobile, complete: @escaping (_ route: MKRoute?, _ error: Error?) -> Void)
**Parameters**
<table>
<tr><td> `source` </td><td> The map item of the source location. </td></tr>
<tr><td> `destination` </td><td> The map item of the destination location. </td></tr>
<tr><td> `transportType` </td><td> The transportation type to create the route. </td></tr>
<tr><td> `complete` </td><td> Returns an optional route and error. </td></tr>
<table>
---
<br>
### directionsToCurrentLocation(fromCoordinate:inApp:)
Gets directions to a coordinate from the users current location.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func directionsToCurrentLocation(fromCoordinate coordinate: CLLocationCoordinate2D, inApp: Bool = true)
Parameters
| `coordinate` | The coordinate to get directions to. |
| `inApp` | If true diretions are plotted in-app on the map view. If false then the Maps.app is opened with the directions requested. |
Plots a route as a polyline after removing all previous reotes, and then zoom to display the new route.
Declaration
Swift
public func plot(route: MKRoute)
**Parameters**
<table>
<tr><td> `route` </td><td> The route to plot. </td></tr>
<table>
---
<br>
## Helper Methods <br>
### normalize(regionSpan:)
Normalizes a regions space with the constants preset.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func normalize(regionSpan span: MKCoordinateSpan) -> MKCoordinateSpan
Parameters
| `span` | The span to normalize. |
Return Value
The normalized span.
Deselects any showing annotation view callout on the map.
Declaration
Swift
public func deselectAllAnnotations()
---
<br>
## MKMapViewDelegate Methods <br>
### mapView(_:viewFor:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public final func mapView(_ mapView: MKMapView, viewFor annotation: MKAnnotation) -> MKAnnotationView?
Called by mapView:viewForAnnotation: in the map controller.
Declaration
Swift
open func configureAnnotationView(mapView: MKMapView, viewForAnnotation annotation: MKAnnotation) -> MKAnnotationView?
**Parameters**
<table>
<tr><td> `mapView` </td><td> The map view that requested the annotation view. </td></tr>
<tr><td> `annotation` </td><td> The object representing the annotation that is about to be displayed. In addition to your custom annotations, this object could be an MKUserLocation object representing the user’s current location. </td></tr>
<table>
**Return Value**
The annotation view to display for the specified annotation or nil if you want to display a standard annotation view.
---
<br>
### mapView(_:annotationView:calloutAccessoryControlTapped:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func mapView(_ mapView: MKMapView, annotationView view: MKAnnotationView, calloutAccessoryControlTapped control: UIControl)
Called by mapView:annotationView:calloutAccessoryControlTapped: in the map controller.
Declaration
Swift
open func calloutAccessoryControlTapped(mapView: MKMapView, annotationView view: MKAnnotationView, controlTapped control: UIControl)
**Parameters**
<table>
<tr><td> `mapView` </td><td> The map view containing the specified annotation view. </td></tr>
<tr><td> `view` </td><td> The annotation view whose button was tapped. </td></tr>
<tr><td> `control` </td><td> The control that was tapped. </td></tr>
<table>
---
<br>
### mapView(_:rendererFor:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
public func mapView(_ mapView: MKMapView, rendererFor overlay: MKOverlay) -> MKOverlayRenderer
Called by mapView:rendererForOverlay: in the map controller.
Declaration
Swift
open func configureOverlayRenderer(mapView: MKMapView, overlay: MKOverlay) -> MKOverlayRenderer
**Parameters**
<table>
<tr><td> `mapView` </td><td> The map view that requested the renderer object. </td></tr>
<tr><td> `overlay` </td><td> The overlay object that is about to be displayed. </td></tr>
<table>
**Return Value**
The renderer to use when presenting the specified overlay on the map. If you return nil, no content is drawn for the specified overlay object.
---
<br>
### mapView(_:regionWillChangeAnimated:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func mapView(_ mapView: MKMapView, regionWillChangeAnimated animated: Bool)
Declaration
Swift
open func mapView(_ mapView: MKMapView, regionDidChangeAnimated animated: Bool)
---
<br>
### mapView(_:didUpdate:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func mapView(_ mapView: MKMapView, didUpdate userLocation: MKUserLocation)
Declaration
Swift
open func mapView(_ mapView: MKMapView, didChange mode: MKUserTrackingMode, animated: Bool)
---
<br>
### mapView(_:didFailToLocateUserWithError:)
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func mapView(_ mapView: MKMapView, didFailToLocateUserWithError error: Error)
Declaration
Swift
open func locationManager(_ manager: CLLocationManager, didChangeAuthorization status: CLAuthorizationStatus)
---
<br>
## Search Methods <br>
### searchAddresses(_:)
Performs a predicate search on the addresses dictionary that begins with the search string.
**Declaration**
> <sub>**Swift**</sub>
> ```swift
open func searchAddresses(_ searchString: String) -> [Address]
Parameters
| `searchString` | The string to search the addresses by name or simple address. |
Return Value
An array of addresses that meet the predicate search criteria.