Weather Provider Plugins

Weather provider plugins need to extend the WeatherProvider class:

class MyWeatherProviderPlugin : WeatherProvider(
    WeatherPluginConfig()
)

In the super constructor call, pass a WeatherPluginConfig object.

Plugin config

In the plugin config, you can set the following properties:

• minUpdateInterval: Minimum time (in ms) that needs to pass before the provider can be queried again. The launcher respects this value as long as the user does not change the weather settings ( provider or location).

• managedLocation: If true, the plugin will manage the location itself. This means that the user cannot change the location settings in the launcher.

Location search

If your weather provider service provides an API to lookup locations, you should override

suspend fun findLocations(query: String, lang: String): List<WeatherLocation>

This method is called when a user has Auto location disabled and they are trying to set a new location.

The default implementation uses the Android Geocoder, but this API has the limitation that it relies on Google Play Services so you should use your own implementation whenever feasable.

findLocations returns a list of WeatherLocation s. Return an empty list if no location has been found.

Location types

There are three types of locations:

• WeatherLocation.LatLon: use this if your weather service identifies locations by their geo coordinates.
• WeatherLocation.Id: use this if your weather service has an internal ID system to identify locations.
• WeatherLocation.Managed: a special location that indicates that the plugin should determine the location itself.

Featch weather data

Implement both getWeatherData methods:

suspend fun getWeatherData(lat: Double, lon: Double, lang: String?): List<Forecast>?`

suspend fun getWeatherData(location: WeatherLocation, lang: String?): List<Forecast>?

The first method is called when the user has Auto location enabled. lat and lon the last known coordinates of the user.

The second method is called when the user has set their location to a fixed location. In most cases, location will be a value that has been returned by findLocations before, but it's possible that location is a WeatherLocation.LatLon if the user has changed the provider after setting a fixed location. If you haven't overridden findLocations, this will always be a WeatherLocation.LatLon. If managedLocation is set to true, this method is called with WeatherLocation.Managed.

Both methods return a list of Forecast s. If an error occurs, you can throw an exception or return null, in this case the launcher will keep the old data and start another attempt at a later time.

Forecast objects need at least a timestamp (unix time in millis), a temperature, a condition, an icon, a location name, and a provider name.

• The condition should preferably be localized in the user's language, which is provided by the lang parameter.

• To construct a Temperature, you can use the Double.C, Double.F, or Double.K helper functions, depending on whether the numeric value returned by your weather service API is in degrees celsius, degrees fahrenheit, or kelvin:

  val temp = tempValueInCelcius.C
  val temp2 = tempValueInFahrenheit.F
  val temp3 = tempValueInKelvin.K

  Similar helper functions are available to construct

  • Pressure (Double.hPa, and Double.mbar), and
  • WindSpeed values (Double.m_s, Double.km_h, and Double.mph)

• location is the name of the location.

  • In fixed location mode, you should read this value from the location parameter, to ensure that the name in the weather widget matches the name that the user has set in preferences.
  • In auto location mode, if your weather service does not give you a location name, you can use the getLocationName method to reverse geocode the location name using Android's Geocoder API.

Plugin state

Some plugins need to be configured before they can be used. For example, users might need to connect an account, or provide an API key.

If your plugin has such requirements, you can override

suspend fun getPluginState(): PluginState

This method can either return PluginState.Ready, or PluginState.SetupRequired.

• PluginState.Ready can have a status text to describe what the plugin does in its current configuration. For example "Search {username}'s files on {service}". This overrides the plugin's description.
• PluginState.SetupRequired needs to have a setupActivity Intent that starts the setup. You can also provide a message to describe what kind of setup needs to be performed. For example "Sign in with {service} to search files on {service}"

IMPORTANT

This method is only meant to provide hints to the launcher's user interface. You should not rely on it as a safeguard for your other plugin methods. There is still a chance that your other plugin methods are called regardless of the return value of this method. Make sure to check your requirements in the other plugin methods as well.

Examples

• OpenWeatherMap plugin
• Breezy Weather plugin