All kinds of locations to pick – Users can pick locations from their current location, search results or a list of locations provided by your app.

Fully customizable – LocationPicker provides a great deal of customizability allowing all text to be customized along with the colors and icons. Original UI elements like UISearchBar, UITableView, MKMapItem are also accessible if you want to do some deep customization.

That’s all you need to have a fully functional location picker in your app. How easy!

Note: To use current location, don’t forget to add NSLocationWhenInUseUsageDescription to your info.plist

Customization

Methods

func addButtons

This method provides 3 optional parameter. doneButtonItem and cancelButtonItem can be set as the customized UIBarButtonItem object. doneButtonOrientation is used to determine how to align these two buttons. If none of the parameters is provided, two system style buttons would be used, and the done button would be put on the right side.

After this method is called, these two buttons can be accessed via barButtonItems property.

func setColors

This method aims to set colors more conveniently. themColor will be set to currentLocationIconColor, searchResultLocationIconColor, alternativeLocationIconColor, pinColor. primaryTextColor and secondaryTextColor can also be set by this method.

func setLocationDeniedAlertControllerTitle

This method provides the text of locationDeniedAlertController simultaneously.

If this method is not called, the alert controller will be presented like this

Grant button will direct user to the Settings where location access can be changed.

Boolean

Property name

Default

Target

Remark

allowArbitraryLocation

false

Allows the selection of locations that did not match or exactly match search results

Image

The image of the icon showed in current location cell, this image’s color won’t be affected by property currentLocationIconColor

searchResultLocationIconImage

searchResultLocationCell.iconView.image

The image of the icon showed in search result location cells, this image’s color won’t be affected by property searchResultLocationIconColor

alternativeLocationIconImage

alternativeLocationCell.iconView.image

The image of the icon showed in alternative location cells, this image’s color won’t be affected by property alternativeLocationIconColor

Other

Property name

Type

Default

Remark

alternativeLocations

[LocationItem]?

nil

Locations that show under current location and search result locations

locationDeniedAlertController

UIAlertController?

nil

Alert controller that appear when user request current location but denied the app’s location permission

defaultLongitudinalDistance

Double

1000

Longitudinal distance of the map view shows when user select a location and before zoom in or zoom out

searchDistance

Double

10000

Distance in meters that is used to search locations

Note:

Alternative locations can also be provided via Data Source.

You don’t need to set the locationDeniedAlertController if you are satisfied with the alert controller included in LocationPicker. You can change the text of the default alert controller via func setLocationDeniedAlertControllerTitle. If you want to do something other than presenting an alert controller, you can adopt Permission Denied Handler callback.

Callbacks

LocationPicker provides three different types of callbacks, they are Closure, Delegate and Data Source and Override, you can choose whichever you like. In most cases, using closures is the most convenient way. If you are already subclassing LocationPicker, override may be the best choice.

Closure

Location Pick

This completion closure is used to get user’s final decision. It would be executed only once for every LocationPicker object when it is about to be dismissed.

locationPicker.pickCompletion = { (pickedLocationItem) in
// Do something with the location the user picked.
}

Location Selection

This completion closure is used to get user’s every location selection. It would be executed every time user chooses a location in the list or drag the map view.

locationPicker.selectCompletion = { (selectedLocationItem) in
// Do something with user's every selection.
}

Location Deletion

If alternativeLocations is not empty and alternativeLocationEditable is set to true, this closure will be executed when user delete a location item in the table view.

Permission Denied Handler

By default, when user request current location but denied the app’s location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this closure.

Permission Denied Handler

By default, when user request current location but denied the app’s location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this delegate method.

Permission Denied Handler

By default, when user request current location but denied the app’s location access, LocationPicker will present an alert controller that links to the Settings. You can change the text in the alert controller by calling func setLocationDeniedAlertControllerTitle. If you need to do something other than presenting an alert controller, you can set this method.

Location Item

LocationItem is a encapsulation class of MKMapItem to save you from importing MapKit everywhere in your project. To make it more convenient to use, it equips with several computing properties to access the MKMapItem.

Storage

LocationItem is conformed to NSCoding, which means LocationItem object can be encoded to NSData object and decoded back.

Equatable

The hash value of LocationItem is "(coordinate.latitude), (coordinate.longitude)".hashValue, so objects that have the same latitude and longitude are equal.

Properties

Property name

Type

Target

Remark

name

String

mapItem.name

The name of the location

coordinate

(latitude: Double, longitude: Double)?

mapItem.placemark.coordinate

The coordinate of the location and converted to tuple. If the user is offline or there is no search result and the allowArbitraryLocation property of LocationPicker is set to true, this property will be nil

addressDictionary

[NSObject: AnyObject]?

mapItem.placemark.addressDictionary

The address dictionary of the location

formattedAddressString

String?

addressDictionary?["FormattedAddressLines"]

The address text formatted according to user’s region

If you want to access other properties of MKMapItem object, just call locationItem.mapItem.

Initialization

init(mapItem: MKMapItem)

Since LocationItem is just the encapsulation of MKMapItem, of course you can create a LocationItem with a MKMapItem object.

init(locationName: String)

Change Log

Contribute

If you encounter any bugs or other problems, please create issues or pull requests.

If you want to add more features to LocationPicker, you are more than welcome to create pull requests.

If you are good at English, please correct my English.

If you like the project, please star it and share with others.

If you have used LocationPicker in your App, please tell me by creating an issue.

License

The MIT License (MIT)

Copyright (c) 2016 Jerome Tan

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.