Home Widget
HomeWidget is a Plugin to make it easier to create HomeScreen Widgets on Android and iOS. HomeWidget does not allow writing Widgets with Flutter itself. It still requires writing the Widgets with native code. However, it provides a unified Interface for sending data, retrieving data and updating the Widgets
Platform Setup
In order to work correctly there needs to be some platform specific setup. Check below on how to add support for Android and iOSAndroidiOS
Usage
Setup
For iOS, you need to call HomeWidget.setAppGroupId('YOUR_GROUP_ID');
Without this you won’t be able to share data between your App and the Widget and calls to saveWidgetData
and getWidgetData
will return an error
Save Data
In order to save Data call HomeWidget.saveWidgetData<String>('id', data)
Update a Widget
In order to force a reload of the HomeScreenWidget you need to call
HomeWidget.updateWidget( name: 'HomeWidgetExampleProvider', androidName: 'HomeWidgetExampleProvider', iOSName: 'HomeWidgetExample', );
The name for Android will be chosen by checking androidName
if that was not provided it will fallback to name
. This Name needs to be equal to the Classname of the WidgetProvider
The name for iOS will be chosen by checking iOSName
if that was not provided it will fallback to name
. This name needs to be equal to the Kind specified in you Widget
Retrieve Data
To retrieve the current Data saved in the Widget call HomeWidget.getWidgetData<String>('id', defaultValue: data)
Background Update
As the methods of HomeWidget are static it is possible to use HomeWidget in the background to update the Widget even when the App is in the background.
The example App is using the flutter_workmanager plugin to achieve this. Please follow the Setup Instructions for flutter_workmanager (or your preferred background code execution plugin). Most notably make sure that Plugins get registered in iOS in order to be able to communicate with the HomeWidget Plugin. In case of flutter_workmanager this achieved by adding:
WorkmanagerPlugin.setPluginRegistrantCallback { registry in GeneratedPluginRegistrant.register(with: registry) }
Clicking
To detect if the App has been initially started by clicking the Widget you can call HomeWidget.initiallyLaunchedFromHomeWidget()
if the App was already running in the Background you can receive these Events by listening to HomeWidget.widgetClicked
. Both methods will provide Uris, so you can easily send back data from the Widget to the App to for example navigate to a content page.
In order for these methods to work you need to follow these steps:
iOS
Add .widgetUrl
to your WidgetComponent
Text(entry.message) .font(.body) .widgetURL(URL(string: "homeWidgetExample://message?message=\(entry.message)&homeWidget"))
In order to only detect Widget Links you need to add the queryParameterhomeWidget
to the URL
Android
Add an IntentFilter
to the Activity
Section in your AndroidManifest
<intent-filter>
<action android:name="es.antonborri.home_widget.action.LAUNCH" />
</intent-filter>
In your WidgetProvider add a PendingIntent to your View using HomeWidgetLaunchIntent.getActivity
val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity( context, MainActivity::class.java, Uri.parse("homeWidgetExample://message?message=$message")) setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
Background Click
Android allows interactive elements in HomeScreenWidgets. This allows to for example add a refresh button on a widget. With home_widget you can use this by following these steps:
Android/Native Part
- Add the necessary Receiver and Service to you
AndroidManifest.xml
file<receiver android:name="es.antonborri.home_widget.HomeWidgetBackgroundReceiver"> <intent-filter> <action android:name="es.antonborri.home_widget.action.BACKGROUND" /> </intent-filter> </receiver> <service android:name="es.antonborri.home_widget.HomeWidgetBackgroundService" android:permission="android.permission.BIND_JOB_SERVICE" android:exported="true"/>
- Add a
HomeWidgetBackgroundIntent.getBroadcast
PendingIntent to the View you want to add a click listener toval backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast( context, Uri.parse(“homeWidgetExample://titleClicked”) ) setOnClickPendingIntent(R.id.widget_title, backgroundIntent)
Dart
- Write a static function that takes a Uri as an argument. This will get called when a user clicks on the Viewvoid backgroundCallback(Uri data) { // do something with data … }
- Register the callback function by callingHomeWidget.registerBackgroundCallback(backgroundCallback);
Download Home Widget source code on GitHub
Provides the list of the opensource Flutter apps collection with GitHub repository.