w3w-autosuggest-edittext-android

Android library for what3words suggestion edittext.

License

License

Categories

Categories

Auto Application Layer Libs Code Generators
GroupId

GroupId

com.what3words
ArtifactId

ArtifactId

w3w-autosuggest-edittext-android
Last Version

Last Version

1.2.1
Release Date

Release Date

Type

Type

aar
Description

Description

w3w-autosuggest-edittext-android
Android library for what3words suggestion edittext.
Project URL

Project URL

https://github.com/what3words/w3w-android-components
Source Code Management

Source Code Management

https://github.com/what3words/w3w-android-components

Download w3w-autosuggest-edittext-android

How to add to project

<!-- https://jarcasting.com/artifacts/com.what3words/w3w-autosuggest-edittext-android/ -->
<dependency>
    <groupId>com.what3words</groupId>
    <artifactId>w3w-autosuggest-edittext-android</artifactId>
    <version>1.2.1</version>
    <type>aar</type>
</dependency>
// https://jarcasting.com/artifacts/com.what3words/w3w-autosuggest-edittext-android/
implementation 'com.what3words:w3w-autosuggest-edittext-android:1.2.1'
// https://jarcasting.com/artifacts/com.what3words/w3w-autosuggest-edittext-android/
implementation ("com.what3words:w3w-autosuggest-edittext-android:1.2.1")
'com.what3words:w3w-autosuggest-edittext-android:aar:1.2.1'
<dependency org="com.what3words" name="w3w-autosuggest-edittext-android" rev="1.2.1">
  <artifact name="w3w-autosuggest-edittext-android" type="aar" />
</dependency>
@Grapes(
@Grab(group='com.what3words', module='w3w-autosuggest-edittext-android', version='1.2.1')
)
libraryDependencies += "com.what3words" % "w3w-autosuggest-edittext-android" % "1.2.1"
[com.what3words/w3w-autosuggest-edittext-android "1.2.1"]

Dependencies

compile (7)

Group / Artifact Type Version
org.jetbrains.kotlin : kotlin-stdlib jar 1.4.10
org.jetbrains.kotlin : kotlin-android-extensions-runtime jar 1.4.10
androidx.recyclerview » recyclerview jar 1.1.0
androidx.core » core-ktx jar 1.3.2
com.what3words : w3w-android-wrapper jar 3.1.8
com.intentfilter » android-permissions jar 2.0.54
androidx.constraintlayout » constraintlayout jar 2.0.4

Project Modules

There are no modules declared in this project.

what3words w3w-android-components

An Android library to use the what3words v3 API autosuggest.

alt textalt textalt text

To obtain an API key, please visit https://what3words.com/select-plan and sign up for an account.

Installation

The artifact is available through Maven Central

Gradle

implementation 'com.what3words:w3w-android-components:2.0.2'

Documentation

See the what3words public API documentation

Usage

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourpackage.yourapp">

    <uses-permission android:name="android.permission.INTERNET" />
    ...

if minSdkVersion < 24 add this to build.gradle (app level)

compileOptions {
    sourceCompatibility JavaVersion.VERSION_1_8
    targetCompatibility JavaVersion.VERSION_1_8
}

activity_main.xml

<androidx.constraintlayout.widget.ConstraintLayout
	  xmlns:android="http://schemas.android.com/apk/res/android"
	  xmlns:app="http://schemas.android.com/apk/res-auto"
	  android:layout_width="match_parent"
	  android:layout_height="match_parent">

	 <com.what3words.components.text.W3WAutoSuggestEditText
		  android:id="@+id/suggestionEditText"
		  android:layout_width="0dp"
		  android:layout_height="wrap_content"
		  app:layout_constraintEnd_toEndOf="parent"
		  app:layout_constraintStart_toStartOf="parent"
		  app:layout_constraintTop_toTopOf="parent" />

</androidx.constraintlayout.widget.ConstraintLayout>

Kotlin

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

	suggestionEditText.apiKey("YOUR_API_KEY_HERE")
            .returnCoordinates(false)
            .onSelected { w3wSuggestion ->
                if (w3wSuggestion != null) {
                    Log.i( "MainActivity","words: ${w3wSuggestion.suggestion.words}, country: ${w3wSuggestion.suggestion.country}, distance: ${w3wSuggestion.suggestion.distanceToFocusKm}, near: ${w3wSuggestion.suggestion.nearestPlace}, latitude: ${w3wSuggestion.coordinates?.lat}, longitude: ${w3wSuggestion.coordinates?.lng}"
                    )
                } else {
                    Log.i("MainActivity", "invalid w3w address")
                }
            }
            .onError {
                Log.e("MainActivity", "${it.key} - ${it.message}")
            }
}

Java

public class MainActivity extends AppCompatActivity {

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);
        W3WAutoSuggestEditText autoSuggestEditText = findViewById(R.id.suggestionEditText);
        autoSuggestEditText.apiKey("YOUR_API_KEY_HERE")
                .returnCoordinates(false)
                .onSelected(null, null, (W3WSuggestion w3wSuggestion) -> {
                    if (w3wSuggestion != null) {
                        Log.i("MainActivity", String.format("words: %s, country: %s, near: %s", w3wSuggestion.getSuggestion().getWords(), w3wSuggestion.getSuggestion().getCountry(), w3wSuggestion.getSuggestion().getNearestPlace()));
                    } else {
                        Log.i("MainActivity", "invalid w3w address");
                    }
                })
                .onError(null, (APIResponse.What3WordsError what3WordsError) -> Log.e("MainActivity", String.format("%s - %s", what3WordsError.getKey(), what3WordsError.getMessage())));
    }

If you run our Enterprise Suite API Server yourself, you may specify the URL to your own server like so:

 suggestionEditText.apiKey("YOUR_API_KEY_HERE", "https://api.yourserver.com")

General properties:

property default value type description XML Programatically
apiKey N/A String Your what3words API key. mandatory ✔️
hint e.g. lock.spout.radar String Placeholder text to display in the input in its default empty state. ✔️
errorMessage No valid what3words address found String Overwrite the validation error message with a custom value. ✔️ ✔️
focus N/A Coordinates This is a location, specified as a latitude/longitude (often where the user making the query is). If specified, the results will be weighted to give preference to those near the focus ✔️
clipToCountry N/A String Clip results to a given country or comma separated list of countries. Example value:"GB,US". ✔️
clipToCircle N/A Coordinates, Int Clip results to a circle, specified by Coordinate(lat,lng) and kilometres, where kilometres in the radius of the circle. ✔️
clipToBoundingBox N/A BoundingBox Clip results to a bounding box specified using co-ordinates. ✔️
clipToPolygon N/A List of Coordinates Clip results to a bounding box specified using co-ordinates. ✔️
returnCoordinates false Boolean Calls the what3words API to obtain the coordinates for the selected 3 word address (to then use on a map or pass through to a logistic company etc) ✔️ ✔️
allowInvalid3wa false Boolean Allow invalid 3 word address ✔️
imageTintColor #E11F26 Color Changes /// image colour. ✔️
suggestionsListPosition BELOW Enum Suggestion list position which can be below (default) the EditText or above ✔️ ✔️

Enable voice autosuggest:

alt textalt textalt text

The component also allows for voice input using the what3words Voice API. This feature allows the user to say 3 words and using speech recognition technology displays 3 word address suggestions to the user.

Before enabling Voice AutoSuggest you will need to add a Voice API plan in your account.

By default the voice language is set to English but this can be changed using the voiceLanguage property (for list of available languages please check the properties table below). Voice input respects the clipping and focus options applied within the general properties. We recommend applying clipping and focus where possible to display as accurate suggestions as possible. To enable voice you can do with programmatically or directly in the XML.

AndroidManifest.xml

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.yourpackage.yourapp">

    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.RECORD_AUDIO" />
    ...

activity_main.xml

 <com.what3words.components.text.W3WAutoSuggestEditText
		  android:id="@+id/suggestionEditText"
		  android:layout_width="0dp"
		  android:layout_height="wrap_content"
		  app:layout_constraintEnd_toEndOf="parent"
		  app:layout_constraintStart_toStartOf="parent"
		  app:layout_constraintTop_toTopOf="parent"
		  app:voiceEnabled="true" />

or

 suggestionEditText.apiKey("YOUR_API_KEY_HERE")
	        .returnCoordinates(false)
	        .voiceEnabled(true)
		...

Voice properties:

property default value type description XML Programatically
voiceEnabled false Boolean Enables voice suggestion to allow the user to say the three word address instead of writing it. ✔️ ✔️
voiceFullscreen false Boolean Voice activation will be fullscreen instead of inline. ✔️ ✔️
voiceLanguage en String Available voice languages: ar for Arabic, cmn for Mandarin Chinese, de for German, en Global English (default), es for Spanish, hi for Hindi, ja for Japanese and ko for Korean ✔️ ✔️

Voice only:

If you want to use voice-only (no text input) please look at our voice-sample app in this repo for examples of how to use our W3WAutoSuggestVoice component.

Advanced usage:

If you want to check different ways to use our component please look at our advanced-sample app in this repo for examples of how to use and customize our W3WAutoSuggestText component.

alt text

Styles:

Use our base style as parent and you can set the custom properties available with XML on the table above and the normal EditText styling, i.e:

<style name="YourCustomStyle" parent="Widget.AppCompat.W3WAutoSuggestEditText">
	<item name="android:textColor">#000000</item>  
	<item name="android:textColorHint">#888888</item>  
	<item name="errorMessage">Your custom error message</item>  
	<item name="android:hint">Your custom placeholder</item>
    <item name="android:textAppearance">@style/YourCustomStyleTextAppearance</item>  
</style>  
  
<style name="YourCustomStyleTextAppearance" parent="TextAppearance.AppCompat">  
	 <item name="android:textSize">22sp</item>  
	 <item name="android:fontFamily">sans-serif-medium</item>
</style>

alt textalt textalt text

Full documentation:

Existing components:

Name Summary
W3WAutoSuggestEditText class W3WAutoSuggestEditText : AppCompatEditText
A AppCompatEditText to simplify the integration of what3words text and voice auto-suggest API in your app.
W3WAutoSuggestVoice class W3WAutoSuggestVoice : ConstraintLayout
A View to simplify the integration of what3words voice auto-suggest API in your app.
W3WAutoSuggestErrorMessage class W3WAutoSuggestErrorMessage : AppCompatTextView
A AppCompatTextView styled and ready to show error messages.
W3WAutoSuggestPicker class W3WAutoSuggestPicker : RecyclerView
A RecyclerView to show W3WSuggestion returned by w3w auto suggest component modularized to allow developers to choose picker location on the screen.
com.what3words

what3words

addressing the world

Versions

Version
1.2.1
1.2.0
1.1.0
1.0.0