Kvaesitso

https://kvaesitso.mm20.de/docs/
Admin
Kvaesitso is an open-source Android launcher with plugins, customizable search, widgets, and...
Tokens:16,390
Snippets:255
Trust Score:5.4
Update:4 months ago
Show doc for...
Tokens:
Raw
### Get Plugin State

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

Overrides the method to indicate whether the plugin is ready to be used or requires setup. Can return `PluginState.Ready` with optional status text, or `PluginState.SetupRequired` with an Intent and optional message.

```APIDOC
## getPluginState

### Description
Overrides the method to indicate whether the plugin is ready to be used or requires setup. Can return `PluginState.Ready` with optional status text, or `PluginState.SetupRequired` with an Intent and optional message.

### Method Signature
`suspend fun getPluginState(): PluginState`

### Parameters
None

### Return Value
- `PluginState` - An enum indicating the plugin's state. Can be `PluginState.Ready` or `PluginState.SetupRequired`.
  * `PluginState.Ready` can have a `text` property (string) to describe the plugin's current configuration.
  * `PluginState.SetupRequired` must have a `setupActivity` property (Intent) and can have a `message` property (string) describing the required setup.
```

--------------------------------

### Plugin State

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/contact-search.html

Provides the current state of the plugin, indicating whether setup is required or if it's ready for use.

```APIDOC
## Plugin State

### Description
Returns the current state of the plugin, which can be either `Ready` or `SetupRequired`. This is used to inform the launcher's user interface about the plugin's configuration status.

### Method
`suspend fun getPluginState(): PluginState`

### Parameters
None

### Request Example
```kotlin
suspend fun getPluginState(): PluginState {
    // Return PluginState.Ready or PluginState.SetupRequired
    return PluginState.Ready
}
```

### Response
#### Success Response
* `PluginState` - An enum representing the plugin's state. Can be:
    * `PluginState.Ready` - The plugin is configured and ready. Optionally includes a `text` field for a status description (e.g., "Search {username}'s files on {service}").
    * `PluginState.SetupRequired` - The plugin requires configuration. Must include a `setupActivity` Intent and optionally a `message` describing the required setup (e.g., "Sign in with {service} to search files on {service}").

#### Response Example
```json
{
  "state": "Ready",
  "text": "Search contacts on example.com"
}
```

**Important:** This method is for UI hints only. Do not rely on it as a safeguard for other plugin methods, as they might still be called regardless of the returned state. Always validate requirements within each plugin method.
```

--------------------------------

### Updated `get` function signature

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/changelogs/v2.0.0.html

The `get` function signature has been updated to accept a `GetParams` object for additional configuration.

```kotlin
suspend fun get(id: String): File?
```

```kotlin
suspend fun get(id: String, params: GetParams): File?
```

--------------------------------

### AdaptiveIconDrawable for Clock Icon

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

An example of an `AdaptiveIconDrawable` with a `LayerDrawable` as its foreground. Each clock hand is wrapped in a `RotateDrawable` with specific `fromDegrees` and `toDegrees` values for animation.

```xml
<adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
    <background android:drawable="@drawable/clock_background" />
    <foreground>
        <layer-list>
            <item>
                <rotate android:drawable="@drawable/clock_hour" android:fromDegrees="300.0"
                    android:pivotX="50.0%" android:pivotY="50.0%" android:toDegrees="5300.0" />
            </item>
            <item>
                <rotate android:drawable="@drawable/clock_minute" android:fromDegrees="60.0"
                    android:pivotX="50.0%" android:pivotY="50.0%" android:toDegrees="60060.0" />
            </item>
            <item>
                <rotate android:drawable="@drawable/clock_second" android:fromDegrees="180.0"
                    android:pivotX="50.0%" android:pivotY="50.0%" android:toDegrees="6180.0" />
            </item>
            <item android:drawable="@drawable/clock_top" />
        </layer-list>
    </foreground>
</adaptive-icon>
```

--------------------------------

### Kvaesitso App Signature Verification

Source: https://kvaesitso.mm20.de/docs/user-guide

Verify the app's signature using SHA1 and SHA256 fingerprints before installation.

```text
SHA1:   AF:1D:5F:4A:72:FB:AF:9F:CE:32:81:42:D1:ED:4A:3E:A4:E7:75:74
```

```text
SHA256: BF:65:BB:D6:17:99:73:97:80:0D:02:E0:AC:2E:45:CE:E1:53:15:15:18:54:5C:23:EF:66:B3:CB:2C:FD:F7:BC
```

--------------------------------

### Get Contact

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/contact-search.html

Retrieves a contact by its ID. This method is essential when `config.storageStrategy` is set to `StorageStrategy.StoreReference`.

```APIDOC
## Get Contact

### Description
Retrieves a contact using its unique identifier. This method must be overridden when `config.storageStrategy` is set to `StorageStrategy.StoreReference`.

### Method
`suspend fun get(id: String, params: GetParams): Contact?`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
* `id` (String) - The unique identifier of the contact to retrieve.
* `params` (GetParams) - Additional parameters for retrieving the contact:
    * `lang` (String) - The current language of the launcher, used for localizing the result.

### Request Example
```kotlin
suspend fun get(id: String, params: GetParams): Contact? {
    // Custom logic to fetch contact by ID
    return Contact(...)
}
```

### Response
#### Success Response
* `Contact?` - The requested contact object, or `null` if the contact is not found or no longer available.

#### Response Example
```json
{
  "id": "12345",
  "name": "Jane Smith"
}
```

**Note:** If the contact is no longer available, return `null` to have it removed from the launcher's database.
```

--------------------------------

### Override Plugin State Function

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/file-search.html

Override this suspend function to indicate whether a plugin requires setup or is ready to use. It can provide status text or a setup activity intent.

```kotlin
suspend fun getPluginState(): PluginState
```

--------------------------------

### Get a place

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

Retrieves a place by its ID. This method is essential when the storage strategy is set to `StorageStrategy.StoreReference`. It returns the Location object if found, or null if the place is no longer available.

```APIDOC
## Get a place

### Description
Retrieves a place by its ID. This method is essential when the storage strategy is set to `StorageStrategy.StoreReference`. It returns the Location object if found, or null if the place is no longer available.

### Method Signature
`suspend fun get(id: String, params: GetParams): Location?`

### Parameters
#### Path Parameters
* `id` (string) - Required - The ID of the place to be requested.
* `params` (GetParams) - Required - Provides additional parameters for the get operation.
  * `lang` (string) - The current language of the launcher. Used for localizing results.

### Return Value
* `Location?` - The requested Location object, or `null` if the place is no longer available.
```

--------------------------------

### Get Calendar Event

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

Overrides the method to look up a calendar event by its ID. This is used when `config.storageStrategy` is set to `StorageStrategy.StoreReference`. If the event is no longer available, return null.

```APIDOC
## get

### Description
Overrides the method to look up a calendar event by its ID. This is used when `config.storageStrategy` is set to `StorageStrategy.StoreReference`. If the event is no longer available, return null.

### Method Signature
`suspend fun get(id: String, params: GetParams): CalendarEvent?`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters for `id` parameter
* `id` (string) - The ID of the event that is being requested.

### Parameters for `params` object
* `lang` (string) - The current language of the launcher. Used to localize the result.

### Return Value
- `CalendarEvent?` - The requested event, or null if the event is no longer available.
```

--------------------------------

### Get a Place

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

Override this suspend function to retrieve a place by its ID when using StorageStrategy.StoreReference. It takes the place ID and retrieval parameters, returning the Location or null if the place is not found. This method is crucial for looking up specific place details.

```kotlin
suspend fun get(id: String, params: GetParams): Location?
```

--------------------------------

### Add Nightly App to Obtainium

Source: https://kvaesitso.mm20.de/docs/user-guide/faq.html

Configure Obtainium to fetch Kvaesitso Nightly builds. Enter the provided URL, set the source to 'Third Party F-Droid Repos', and use 'nightly' as the app ID/name.

```bash
https://fdroid.mm20.de/
```

--------------------------------

### Clone Kvaesitso Git Repository

Source: https://kvaesitso.mm20.de/docs/developer-guide/setup.html

Clone the official Kvaesitso Git repository to your local machine. This command is essential for obtaining the project's source code.

```bash
git clone https://github.com/MM2-0/Kvaesitso
```

--------------------------------

### Extending FileProvider for File Search

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/file-search.html

To implement file search, extend the FileProvider class and pass a QueryPluginConfig object to the super constructor.

```kotlin
class MyFileSearchPlugin() : FileProvider(
    QueryPluginConfig()
)
```

--------------------------------

### Add Plugin SDK Dependency

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/get-started.html

Include the Kvaesitso plugin SDK as a dependency in your project's build file. Replace '$version' with the current version.

```gradle
de.mm20.launcher2:plugin-sdk:$version
```

--------------------------------

### Add MM20 Repo to F-Droid Client

Source: https://kvaesitso.mm20.de/docs/user-guide/faq.html

Add the MM20 repository to your F-Droid client to access Kvaesitso Nightly builds. Refresh F-Droid after adding the repo.

```bash
https://fdroid.mm20.de/repo
```

--------------------------------

### Extend CalendarProvider Class

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

To create a calendar provider plugin, extend the `CalendarProvider` class and pass a `QueryPluginConfig` object to the super constructor.

```kotlin
class MyCalendarPlugin() : CalendarProvider(
    QueryPluginConfig()
)
```

--------------------------------

### Construct Temperature Values

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/weather.html

Use helper functions like Double.C, Double.F, or Double.K to construct Temperature objects based on the unit of your weather service's temperature values.

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

--------------------------------

### Get Calendar Event

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

Override this method to retrieve a calendar event by its ID when using StoreReference. Return the CalendarEvent or null if it's no longer available. The params object includes the current language for localization.

```kotlin
suspend fun get(id: String, params: GetParams): CalendarEvent?
```

--------------------------------

### Plugin Settings Activity Intent Filter

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/settings.html

Define an activity with the 'de.mm20.launcher2.action.PLUGIN_SETTINGS' action and the 'android.intent.category.DEFAULT' category to enable launching plugin settings.

```xml
<activity
    android:name=".SettingsActivity"
    android:exported="true">

    <intent-filter>
        <action android:name="de.mm20.launcher2.action.PLUGIN_SETTINGS" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>
```

--------------------------------

### Extend LocationProvider for Places Search

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

To implement a places search provider, extend the `LocationProvider` class and pass a `QueryPluginConfig` object to the super constructor.

```kotlin
class MyplaceSearchPlugin() : LocationProvider(
    QueryPluginConfig()
)
```

--------------------------------

### drawable.xml for Manual Icon Picking

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

List all icons available for manual selection in drawable.xml, located in res/xml/. Each icon is defined with an <item> tag. Optional <category> tags can group icons.

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <item drawable="messages" />
    <category title="System" />
    <item drawable="settings" />
    <item drawable="settings_alt_1" />
</resources>
```

--------------------------------

### Plugin Package Label

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Sets the label for the entire plugin package. If not provided, the application label is used.

```xml
<meta-data
    android:name="de.mm20.launcher2.plugin.label"
    android:value="@string/plugin_package_name" />
```

--------------------------------

### Single Plugin Label

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Sets the label for an individual plugin, used in various launcher UI elements.

```xml
<content-provider
    android:label="@string/plugin_label" />
```

--------------------------------

### Implementing the Search Function

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/file-search.html

Override the suspend fun search(query: String, params: SearchParams): List<File> function to perform file searches. The params object provides allowNetwork and lang information.

```kotlin
suspend fun search(query: String, params: SearchParams): List<File>
```

--------------------------------

### Extend WeatherProvider Class

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/weather.html

To create a weather provider plugin, extend the WeatherProvider class and pass a WeatherPluginConfig object to the super constructor.

```kotlin
class MyWeatherProviderPlugin() : WeatherProvider(
    WeatherPluginConfig()
)
```

--------------------------------

### Extend ContactProvider Class

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/contact-search.html

To create a contact search plugin, extend the ContactProvider class and pass a QueryPluginConfig object to the super constructor.

```kotlin
class MyContactSearchPlugin() : ContactProvider(
    QueryPluginConfig()
)
```

--------------------------------

### appfilter.xml Structure

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

The appfilter.xml file maps icons to app components. It must be placed in res/xml/, res/raw/, or assets/. The basic structure includes a root <resources> tag.

```xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- icons are added here -->
</resources>
```

--------------------------------

### Plugin Package Description

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Provides a description for the plugin package, displayed in the plugin list and detail page.

```xml
<meta-data
    android:name="de.mm20.launcher2.plugin.description"
    android:value="@string/plugin_package_description" />
```

--------------------------------

### Multiple Variants for Autogenerated Icons

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Provide multiple variations for autogenerated icon parts (iconback, iconupon, iconmask) by appending numbers to the 'img' attribute. The launcher will randomly select one variant.

```xml
<iconback img1="iconback" img2="iconback2" />
```

--------------------------------

### Single Plugin Description

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Provides a static description for a single plugin. This can be overridden by the plugin for dynamic information.

```xml
<meta-data
    android:name="de.mm20.launcher2.plugin.description"
    android:value="@string/plugin_description" />
```

--------------------------------

### Plugin Package Icon

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Sets the icon for the plugin package. If not provided, the application icon is used.

```xml
<meta-data
    android:name="de.mm20.launcher2.plugin.icon"
    android:resource="@drawable/ic_plugin_icon" />
```

--------------------------------

### Register Plugin in AndroidManifest.xml

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/get-started.html

Register your plugin class as a content provider in the AndroidManifest.xml file. Ensure 'android:authorities' is unique and the intent-filter is correctly set.

```xml
<provider android:name=".MyFirstPlugin" android:authorities="your.package.name.authority"
    android:exported="true">
    <intent-filter>
        <action android:name="de.mm20.launcher2.action.PLUGIN" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</provider>
```

--------------------------------

### Kvaesitso F-Droid Repository

Source: https://kvaesitso.mm20.de/docs/user-guide

Add this F-Droid repository to receive the latest updates for Kvaesitso.

```text
https://fdroid.mm20.de
```

--------------------------------

### Implement Search Functionality

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

Override the `search` function to handle location queries. This function takes a `LocationQuery` and `SearchParams` and returns a list of `Location` objects. Ensure the plugin can restore search results promptly, especially when using `StorageStrategy.StoreReference`.

```kotlin
suspend fun search(query: LocationQuery, params: SearchParams): List<Location>
```

--------------------------------

### Implement Search Function

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/contact-search.html

Override the suspend fun search(query: String, params: SearchParams): List<Contact> function to perform contact searches. The query parameter is the search term, and params provides additional search parameters like allowNetwork and lang.

```kotlin
suspend fun search(query: String, params: SearchParams): List<Contact>
```

--------------------------------

### Dynamic Calendar Icon Configuration

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Enable dynamic calendar icons by adding a <calendar> entry to appfilter.xml. Specify the app component and a prefix for the daily icon drawables (e.g., calendar_1, calendar_2, ... calendar_31).

```xml
<calendar component="ComponentInfo{com.google.android.calendar/com.android.calendar.LaunchActivity}"
    prefix="calendar_" />
```

--------------------------------

### User Agent Format for Meteorologisk institutt

Source: https://kvaesitso.mm20.de/docs/developer-guide/external-apis/weather.html

This is the required format for the User-Agent header when using the Meteorologisk institutt API. Ensure your contact information is correctly placed within the string.

```xml
User-Agent: "{app package name}/signature:{app siganture hash} {@string/metno_contact}"
```

--------------------------------

### Appfilter.xml for Dynamic Clock Icon

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Defines a normal icon entry and a dynamic clock icon entry in `appfilter.xml`. The dynamic-clock entry specifies which drawable to use and maps layers to clock hands.

```xml
<resources>
    <item
        component="ComponentInfo{com.google.android.deskclock/com.android.deskclock.DeskClockTabActivity}"
        drawable="clock" />
    <dynamic-clock defaultHour="10" defaultMinute="10" defaultSecond="30" drawable="clock"
        hourLayerIndex="0" minuteLayerIndex="1" secondLayerIndex="2" />
</resources>
```

--------------------------------

### Fetch Weather Data by Coordinates

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/weather.html

Implement this suspend function to fetch weather data using latitude and longitude. This is called when 'Auto location' is enabled.

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

--------------------------------

### Updated `search` function signature

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/changelogs/v2.0.0.html

The `search` function signature has been updated to include a `SearchParams` object for additional configuration options like network allowance and language.

```kotlin
suspend fun search(query: String, allowNetwork: Boolean): List<File>
```

```kotlin
suspend fun search(query: String, params: SearchParams): List<File>
```

--------------------------------

### Plugin Package Author

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Specifies the name of the plugin author.

```xml
<meta-data
    android:name="de.mm20.launcher2.plugin.author"
    android:value="Your Name" />
```

--------------------------------

### Single Plugin Icon

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/metadata.html

Sets the icon for an individual plugin, used for search result badges in search plugins.

```xml
<content-provider
    android:icon="@drawable/ic_plugin" />
```

--------------------------------

### Autogenerated Icon Fallback Parts

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Define elements for generating fallback icons when an app lacks a specific icon. This includes scaling, background (iconback), foreground (iconupon), and masking (iconmask) layers.

```xml
<resources>
    <scale factor="1.0" />
    <iconback img="iconback" />
    <iconupon img="iconupon" />
    <iconmask img="iconmask" />
</resources>
```

--------------------------------

### Refresh a place

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

Allows the launcher to refresh stored place data. This method is called when a user views a place's details. It can return an updated Location object or null if the place is no longer available. Exceptions can be thrown for temporary unavailability.

```APIDOC
## Refresh a place

### Description
Allows the launcher to refresh stored place data. This method is called when a user views a place's details. It can return an updated Location object or null if the place is no longer available. Exceptions can be thrown for temporary unavailability.

### Method Signature
`suspend fun refresh(item: Location, params: RefreshParams): Location?`

### Parameters
#### Path Parameters
* `item` (Location) - Required - The version of the place currently stored by the launcher.
* `params` (RefreshParams) - Required - Provides additional parameters for the refresh operation.
  * `lang` (string) - The current language of the launcher. Used for localizing results.
  * `lastUpdated` (long) - The timestamp (in milliseconds) when `item` was last updated. Used to determine if a refresh is needed.

### Return Value
* `Location?` - The updated Location object, or `null` if the place is no longer available.
```

--------------------------------

### Mapping Icons in appfilter.xml

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Use the <item> tag in appfilter.xml to associate app components with specific drawable icons. The 'component' attribute specifies the target app, and 'drawable' refers to the icon file in res/drawable/.

```xml
<item component="ComponentInfo{com.android.deskclock/com.android.deskclock.DeskClockTabActivity}"
    drawable="clock" />
```

--------------------------------

### Define Plugin Class

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/get-started.html

Create a new class for your plugin. This class will extend one of the plugin base classes depending on its functionality.

```kotlin
class MyFirstPlugin
```

--------------------------------

### Implement Search Method for Calendar Events

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

Override the `search` suspend function to handle calendar event searches. This method receives a `CalendarQuery` object containing search parameters and a `SearchParams` object for additional options.

```kotlin
suspend fun search(query: CalendarQuery, params: SearchParams): List<CalendarEvent>
```

--------------------------------

### Fetch Weather Data by Location Object

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/weather.html

Implement this suspend function to fetch weather data for a specific location object. This is called when a fixed location is set or when the plugin manages the location.

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

--------------------------------

### AndroidManifest.xml Intent Filters for Icon Packs

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Declare an activity with specific intent filters in your AndroidManifest.xml to identify your app as an icon pack. Ensure the activity is exported.

```xml
<activity android:name="[...]" android:exported="true">
    <intent-filter>
        <action android:name="org.adw.ActivityStarter.THEMES" />
    </intent-filter>
    <intent-filter>
        <action android:name="com.novalauncher.THEME" />
    </intent-filter>
    <intent-filter>
        <!-- Themed icons; only add this if your icon pack supports themed icons -->
        <action android:name="app.lawnchair.icons.THEMED_ICON" />
    </intent-filter>
</activity>
```

--------------------------------

### Refresh a Place

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/places-search.html

Override this suspend function to update a stored place when using StorageStrategy.StoreCopy. It receives the current stored item and refresh parameters, returning the updated Location or null if the place is no longer available. Throw an exception for temporary unavailability.

```kotlin
suspend fun refresh(item: Location, params: RefreshParams): Location?
```

--------------------------------

### Override Contact Refresh Logic

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/contact-search.html

Override this method to define how the launcher refreshes a stored contact. The return value replaces the stored contact or is null if the contact is removed. Throw an exception for temporary unavailability.

```kotlin
suspend fun refresh(item: Contact, params: RefreshParams): Contact?
```

--------------------------------

### Override File Refresh Function

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/file-search.html

Override this suspend function to update a stored file copy. The launcher uses this when a user views file details. Return the updated file or null if it's no longer available.

```kotlin
suspend fun refresh(item: File, params: RefreshParams): File?
```

--------------------------------

### Implement getCalendarLists Method

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/calendar.html

Override the `getCalendarLists` suspend function to return a list of `CalendarList` objects. This method should return at least one list.

```kotlin
suspend fun getCalendarLists(): List<CalendarList>
```

--------------------------------

### Declare Themed Icon Support

Source: https://kvaesitso.mm20.de/docs/developer-guide/integrations/icon-packs.html

Add this intent filter to your AndroidManifest.xml to enable the themed icon toggle in the icon pack picker.

```xml
<intent-filter>
    <action android:name="app.lawnchair.icons.THEMED_ICON" />
</intent-filter>
```

--------------------------------

### Override File Retrieval Function

Source: https://kvaesitso.mm20.de/docs/developer-guide/plugins/plugin-types/file-search.html

Override this suspend function to look up a file by its ID when the storage strategy is set to StoreReference. Return the file or null if it's unavailable.

```kotlin
suspend fun get(id: String, params: GetParams): File?
```
Tokens:
Raw