app_widget 0.0.4 app_widget: ^0.0.4 copied to clipboard
flutter app widget
app_widget #
flutter app widget
Getting Started #
Since flutter engine are build on android activity, we cannot directly build the the widget interface using flutter. Hence it need to be build using the native way. This plugin attempt to exposed as much useful API to flutter to reduce going back and forth to native.
Plaform Support #
Android | iOS |
---|---|
✔️ |
Android #
This plugin introduce some api from the android native and provide some suggestion on how to include an app widget with you flutter application.
App widget is a like a mini app and are actually separated from your main app. It have limited capability on it's own and can't actually talk to the main app directly after the first configuration.
This mean after the first config, there is no way we can talk directly to the widget. There are two way we can update the widget:
- Using sharedPreferences and AppWidgetProvider
- Using workmanager scheduled task
Using this package #
Platform setup #
Android
-
Add widget layout
-
Add
appwidget-provider
infoandroid/app/src/main/res/xml/my-widget-provider-info
<?xml version="1.0" encoding="utf-8"?>
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
android:minWidth="80dp"
android:minHeight="80dp"
android:targetCellWidth="3"
android:targetCellHeight="2"
android:updatePeriodMillis="86400000"
android:initialLayout="@layout/example_layout"
android:configure="tech.noxasch.app_widget_example.MainActivity"
android:widgetCategory="home_screen"
android:widgetFeatures="reconfigurable">
</appwidget-provider>
<!--
android:configure - named it to your app MainActivity
android:initialLayout - should point to an actual layout for the widget
refer to https://developer.android.com/develop/ui/views/appwidgets/overview
-->
- Update Android manifest
android/app/src/main/AndroidManifest
- add intent-filter to the
MainActivity
activity block if you want to support widget initial configuration
<activity
android:name=".MainActivity"
...>
...
<!-- add this -->
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_CONFIGURE"/>
</intent-filter>
</activity>
- add appwidget provider for widget update and deleted intent
<receiver android:exported="true" android:name="MyWidgetProvider">
<intent-filter>
<action android:name="android.appwidget.action.APPWIDGET_UPDATE"/>
<action android:name="android.appwidget.action.APPWIDGET_DELETED"/>
</intent-filter>
<meta-data android:name="android.appwidget.provider"
android:resource="@xml/app_widget_example_info" />
</receiver>
-
Create the widget provider Inherit from Android
AppWidgetProvider
and implement the required method if needed. Since the plugin already provice interface to update widget, we can leave theonUpdate
method and handle it on dart side.Probably you want to implement
onDeleted
method to handle cleanup like removing the widget Id from sharePrefences allow user to add multiple widget. -
Update MainActivity to handle
onConfigure
intent
// add this import
import tech.noxasch.app_widget.AppWidgetPlugin
// this need to be implemented manually
class MainActivity: FlutterActivity() {
override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
super.configureFlutterEngine(flutterEngine)
// add this line
if (intent.action == AppWidgetManager.ACTION_APPWIDGET_CONFIGURE) {
AppWidgetPlugin.Companion.handleConfigureAction(context, intent)
}
}
}
-
Implement android WidgetProvider
-
Handling update in native (Optional) - TODO
-
Implement workmanager in flutter - TODO
In App Usage and Dart/Flutter Api #
This section shows how to use the exposed api by the plugin in your app.
// instantiate appWidgetPlugin
final appWidgetPlugin = AppWidgetPlugin();
appWidgetPlugin.configureWidget(...)
appWidgetPlugin.cancelConfigure()
handling onConfigureWidget
void onConfigureWidget(int widgetId) {
// handle widget configuration
// use launchUrl and deeplink redirect to configuration page
}
// onConfigureWidget callback are optional
// without this it will use default value that you set
final appWidgetPlugin = AppWidgetPlugin(
onConfigureWidget: onConfigureWidget
);
// this changes will reflect on the widget
// only use this method in widget configuration screen as
// it method will close the app which require to signal the widget config completion
appWidgetPlugin.configureWidget(
androidAppName: 'tech.noxasch.app_widget_example',
widgetId: _widgetId!,
widgetLayout: 'example_layout',
textViewIdValueMap: {
'widget_title': 'MY WIDGET',
'widget_message': 'This is my widget message'
});
handling onClickWidget
void onClickWidget(int widgetId) {
// handle click widget event
// do something
// use launchUrl and deeplink redirect
}
// onClickWidget callback are optional
final appWidgetPlugin = AppWidgetPlugin(
onConfigureWidget: onConfigureWidget,
onClickWidget: onClickWidget
);
Updating widget
Most of the time you'll want to update widget via workmanager. See below how to use the extension in workmanager
appWidgetPlugin.updateWidget(
androidAppName: 'tech.noxasch.app_widget_example',
widgetId: _widgetId!,
widgetLayout: 'example_layout',
textViewIdValueMap: {
'widget_title': 'MY WIDGET',
'widget_message': 'This is my widget message'
});
Using Workmanager
TODO
Checklist #
- ✅ Unit Test
- ❌ update documentation
- ❌ Update example app
- ❌ Update Screenshot