A Swift library for what3words UI components. This Swift Components Package provides a straightforward way to add what3word interface functionality your app such as autosuggest text fields, map views, or what3words grid lines into your app.
It includes:
- An Autosuggest Component available as a UITextField, or UISearchController
- Map Components providing straightforward ways to include what3words squares on your MKMapView, or a full featured map view controller.
- These components work with iOS 9.0 or higher.
- This package depends on the what3words swift wrapper.
- For information on using this package with Objective-C read this.
- If you are upgrading from any version 1.x.x, see the upgrade guide.
To use this library you’ll need a what3words API key, which can be signed up for here. If you wish to use the Voice API calls then you must add a Voice API plan to your account.
You can install with Swift Package Manager by adding the URL below to Swift Packages under your project settings:
https://github.com/what3words/w3w-swift-components.git
Import the libraries:
import W3WSwiftApi
import W3WSwiftComponents
import CoreLocationIf you are using the Voice API on device, you should include Microphone permissions in your Info.plist:
The W3WAutoSuggestTextField is a UITextField that will suggest three word addresses as the user enters text. Optionally, there is a voice recognition option.
An iOS UIKit example project can be found at Examples/TextField/TextField.xcodeproj
This conforms to our W3WAutoSuggestTextFieldProtocol. As such, the interface is documented at Documentation/Autosuggest/autosuggest.md.
The W3WAutoSuggestSearchController is a UISearchController that will suggest three word addresses as the user enters text. This allows embedding this functionality in things such asUINavigationController. Optionally, there is a voice recognition option.
An iOS UIKit example project can be found at Examples/SearchController/SearchController.xcodeproj
This conforms to our W3WAutoSuggestTextFieldProtocol. As such, the interface is documented at Documentation/Autosuggest/autosuggest.md.
Map Helper allows you to easily integrate what3words map features into an existing map.
W3WMapHelper conforms to W3WMapViewProtocol. A function reference for it can be found at Documentation/Map/map.md
An iOS UIKit example project can be found at Examples/MapHelper/MapHelper.xcodeproj
let api = What3WordsV3(apiKey: "YourApiKey")
let mapHelper = W3WMapHelper(api, map: yourMKMapView)
If your app already has a ViewController that has a map, W3WMapHelper provides convenience functions to add to your MKMapViewDelegate functions for what3words grid and pin annotations to appear on your map. The example linked to above shows where you would place the calls, and how to instantiate the W3WMapHelper.
W3WMapView conforms to W3WMapViewProtocol . A function reference for it can be found at Documentation/Map/map.md
An iOS UIKit example project can be found at Examples/MapView/MapView.xcodeproj
let api = What3WordsV3(apiKey: "YourApiKey")
let mapview = W3WMapView(api)
We created W3WMapView as a quick and dirty way to quickly get what3words functionality into your app.
Simply replace your MKMapView with W3WMapView, and your app should behave the same as before except it will draw what3words grid lines, and have some new functions available, like addMarker(at: "filled.count.soap").
It's derived from MKMapView but Apple does not recommend deriving new objects from MKMapView presumably because it's interface could change in the future, so view this as a quick and dirty way to get the functionality into your app.
The better approach would be to use W3WMapHelper which is designed to fit nicely into your MKMapViewDelegate conforming class, presumably a UIViewController.
W3WMapViewController conforms to W3WMapViewProtocol . A function reference for it can be found at Documentation/Map/map.md
The iOS UIKit example project can be found at Examples/MapComponent/MapComponent.xcodeproj
let api = What3WordsV3(apiKey: "YourApiKey")
let vc = W3WMapViewController(api)
This demonstrates W3WMapViewController which is a high level component that has easy to use what3words functionality.
If you already have a map in your application then you will want to use W3WMapHelper instead. Find the example called MapHelper.
If you have no map in your app and want to quickly include one with some default behaviours then this one might be for you.
The measurement system in these components are set to the user's preference or locale automatically, but you can override this to .metric, or .imperial:
W3WSettings.measurement = .metricThe W3WAutosuggest components have been translated into about 50 languages, and Localizable.strings files for these are in the Resources of this package. In order for them to work, as with any iOS localisation settings, be sure to add the languages you want to use in your project settings under Info -> Localizations.