diff --git a/.github/workflows/flutter-beta.yml b/.github/workflows/flutter-beta.yml
index 526ad9f8..99aca360 100644
--- a/.github/workflows/flutter-beta.yml
+++ b/.github/workflows/flutter-beta.yml
@@ -1,6 +1,7 @@
name: Build Flutter Beta
on:
+ workflow_dispatch:
push:
branches:
- flutter-beta
@@ -15,7 +16,10 @@ concurrency:
jobs:
quality:
name: Quality Checks
- runs-on: ubuntu-latest
+ runs-on: macos-14
+ defaults:
+ run:
+ working-directory: packages/home_widget
steps:
- uses: actions/checkout@v2
@@ -23,12 +27,13 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: beta
- - name: Get Packages
- run: flutter pub get
+ - uses: bluefireteam/melos-action@v3
- name: Analyze
- run: flutter analyze
+ run: melos analyze
+ - name: Install Formatters
+ run: brew install swift-format ktfmt
- name: Format
- run: dart format . --set-exit-if-changed
+ run: melos format:all
- name: Publishability
run: flutter pub publish --dry-run
- name: Test
@@ -45,11 +50,10 @@ jobs:
uses: codecov/codecov-action@v1
with:
token: ${{ secrets.CODECOV_TOKEN }}
- - uses: VeryGoodOpenSource/very_good_coverage@v1.2.0
+ path: ./packages/home_widget/coverage/lcov.info
android:
name: Android Integration Tests
- needs: quality
runs-on: ubuntu-latest
steps:
@@ -57,6 +61,7 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: beta
+ - uses: bluefireteam/melos-action@v3
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
@@ -71,20 +76,22 @@ jobs:
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
- working-directory: example
script: flutter test integration_test/android_test.dart -d emulator-5554
+ working-directory: packages/home_widget/example
# iOS Test based on https://medium.com/flutter-community/run-flutter-driver-tests-on-github-actions-13c639c7e4ab
# by @kate_sheremet
ios:
name: iOS Integration Tests
- needs: quality
strategy:
matrix:
device:
- "iPhone 14"
fail-fast: false
runs-on: macos-14
+ defaults:
+ run:
+ working-directory: packages/home_widget/example
steps:
- uses: actions/checkout@v2
- uses: maxim-lobanov/setup-xcode@v1
@@ -93,10 +100,10 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: beta
+ - uses: bluefireteam/melos-action@v3
- uses: futureware-tech/simulator-action@v1
id: simulator
with:
model: ${{ matrix.device }}
- name: "Run iOS integration tests"
- run: flutter test integration_test/ios_test.dart -d ${{steps.simulator.outputs.udid}}
- working-directory: example
\ No newline at end of file
+ run: flutter test integration_test/ios_test.dart -d ${{steps.simulator.outputs.udid}}
\ No newline at end of file
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
index 1bbcb4e4..c71f178b 100644
--- a/.github/workflows/main.yml
+++ b/.github/workflows/main.yml
@@ -1,6 +1,7 @@
name: Build
on:
+ workflow_dispatch:
push:
branches:
- main
@@ -17,7 +18,10 @@ concurrency:
jobs:
quality:
name: Quality Checks
- runs-on: ubuntu-latest
+ runs-on: macos-14
+ defaults:
+ run:
+ working-directory: packages/home_widget
steps:
- uses: actions/checkout@v2
@@ -25,12 +29,13 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: stable
- - name: Get Packages
- run: flutter pub get
+ - uses: bluefireteam/melos-action@v3
- name: Analyze
- run: flutter analyze
+ run: melos analyze
+ - name: Install Formatters
+ run: brew install swift-format ktfmt
- name: Format
- run: dart format . --set-exit-if-changed
+ run: melos format:all
- name: Publishability
run: flutter pub publish --dry-run
- name: Test
@@ -47,11 +52,10 @@ jobs:
uses: codecov/codecov-action@v1
with:
token: ${{ secrets.CODECOV_TOKEN }}
- - uses: VeryGoodOpenSource/very_good_coverage@v1.2.0
+ path: ./packages/home_widget/coverage/lcov.info
android:
name: Android Integration Tests
- needs: quality
runs-on: ubuntu-latest
steps:
@@ -59,6 +63,7 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: stable
+ - uses: bluefireteam/melos-action@v3
- name: Enable KVM
run: |
echo 'KERNEL=="kvm", GROUP="kvm", MODE="0666", OPTIONS+="static_node=kvm"' | sudo tee /etc/udev/rules.d/99-kvm4all.rules
@@ -73,20 +78,22 @@ jobs:
uses: reactivecircus/android-emulator-runner@v2
with:
api-level: 29
- working-directory: example
script: flutter test integration_test/android_test.dart -d emulator-5554
+ working-directory: packages/home_widget/example
# iOS Test based on https://medium.com/flutter-community/run-flutter-driver-tests-on-github-actions-13c639c7e4ab
# by @kate_sheremet
ios:
name: iOS Integration Tests
- needs: quality
strategy:
matrix:
device:
- "iPhone 14"
fail-fast: false
runs-on: macos-14
+ defaults:
+ run:
+ working-directory: packages/home_widget/example
steps:
- uses: actions/checkout@v2
- uses: maxim-lobanov/setup-xcode@v1
@@ -95,10 +102,10 @@ jobs:
- uses: subosito/flutter-action@v1
with:
channel: stable
+ - uses: bluefireteam/melos-action@v3
- uses: futureware-tech/simulator-action@v1
id: simulator
with:
model: ${{ matrix.device }}
- name: "Run iOS integration tests"
- run: flutter test integration_test/ios_test.dart -d ${{steps.simulator.outputs.udid}}
- working-directory: example
\ No newline at end of file
+ run: flutter test integration_test/ios_test.dart -d ${{steps.simulator.outputs.udid}}
\ No newline at end of file
diff --git a/README.md b/README.md
deleted file mode 100644
index c325b116..00000000
--- a/README.md
+++ /dev/null
@@ -1,675 +0,0 @@
-# Home Widget
-
-[](https://pub.dartlang.org/packages/home_widget)
-[](https://pub.dev/packages/home_widget/score)
-[](https://pub.dev/packages/home_widget/score)
-[](https://pub.dev/packages/home_widget/score)
-[](https://github.com/ABausG/home_widget/actions/workflows/main.yml?query=branch%3Amain)
-[](https://codecov.io/gh/ABausG/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
-
-| iOS | Android |
-|----------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------|
-| 
| 
|
-
-## 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 iOS
-
-iOS
-
-### Add a Widget to your App in Xcode
-Add a widget extension by going File > New > Target > Widget Extension
-
-
-
-
-### Add GroupId
-You need to add a groupId to the App and the Widget Extension
-
-**Note: in order to add groupIds you need a paid Apple Developer Account**
-
-Go to your [Apple Developer Account](https://developer.apple.com/account/resources/identifiers/list/applicationGroup) and add a new group.
-Add this group to your Runner and the Widget Extension inside XCode: Signing & Capabilities > App Groups > +.
-(To swap between your App, and the Extension change the Target)
-
-
-
-### Sync CFBundleVersion (optional)
-This step is optional, this will sync the widget extension build version with your app version, so you don't get warnings of mismatch version from App Store Connect when uploading your app.
-
-
-
-In your Runner (app) target go to Build Phases > + > New Run Script Phase and add the following script:
-```bash
-generatedPath="$SRCROOT/Flutter/Generated.xcconfig"
-
-# Read and trim versionNumber and buildNumber
-versionNumber=$(grep FLUTTER_BUILD_NAME "$generatedPath" | cut -d '=' -f2 | xargs)
-buildNumber=$(grep FLUTTER_BUILD_NUMBER "$generatedPath" | cut -d '=' -f2 | xargs)
-
-infoPlistPath="$SRCROOT/HomeExampleWidget/Info.plist"
-
-# Check and add CFBundleVersion if it does not exist
-/usr/libexec/PlistBuddy -c "Print :CFBundleVersion" "$infoPlistPath" 2>/dev/null
-if [ $? != 0 ]; then
- /usr/libexec/PlistBuddy -c "Add :CFBundleVersion string $buildNumber" "$infoPlistPath"
-else
- /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $buildNumber" "$infoPlistPath"
-fi
-
-# Check and add CFBundleShortVersionString if it does not exist
-/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "$infoPlistPath" 2>/dev/null
-if [ $? != 0 ]; then
- /usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string $versionNumber" "$infoPlistPath"
-else
- /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $versionNumber" "$infoPlistPath"
-fi
-
-```
-
-Replace `HomeExampleWidget` with the name of the widget extension folder that you have created.
-
-
-### Write your Widget
-Check the [Example App](example/ios/HomeWidgetExample/HomeWidgetExample.swift) for an Implementation of a Widget.
-A more detailed overview on how to write Widgets for iOS 14 can be found on the [Apple Developer documentation](https://developer.apple.com/documentation/swiftui/widget).
-In order to access the Data send with Flutter can be access with
-```swift
-let data = UserDefaults.init(suiteName:"YOUR_GROUP_ID")
-```
-Android (Jetpack Glance)
-
-### Add Jetpack Glance as a dependency to you app's Gradle File
-```groovy
-implementation 'androidx.glance:glance-appwidget:LATEST-VERSION'
-```
-
-### Create Widget Configuration into `android/app/src/main/res/xml`
-```xml
-
-
-```
-
-### Add WidgetReceiver to AndroidManifest
-```xml
-
-
-
-
-
-
-```
-
-### Create WidgetReceiver
-
-To get automatic Updates you should extend from [HomeWidgetGlanceWidgetReceiver](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetGlanceWidgetReceiver.kt)
-
-Your Receiver should then look like this
-
-```kotlin
-package es.antonborri.home_widget_example.glance
-
-import HomeWidgetGlanceWidgetReceiver
-
-class HomeWidgetReceiver : HomeWidgetGlanceWidgetReceiver() {
- override val glanceAppWidget = HomeWidgetGlanceAppWidget()
-}
-```
-
-### Build Your AppWidget
-
-```kotlin
-
-class HomeWidgetGlanceAppWidget : GlanceAppWidget() {
-
- /**
- * Needed for Updating
- */
- override val stateDefinition = HomeWidgetGlanceStateDefinition()
-
- override suspend fun provideGlance(context: Context, id: GlanceId) {
- provideContent {
- GlanceContent(context, currentState())
- }
- }
-
- @Composable
- private fun GlanceContent(context: Context, currentState: HomeWidgetGlanceState) {
- // Use data to access the data you save with
- val data = currentState.preferences
-
-
- // Build Your Composable Widget
- Column(
- ...
- }
-
-```
-
-Android (XML)
-
-### Create Widget Layout inside `android/app/src/main/res/layout`
-
-### Create Widget Configuration into `android/app/src/main/res/xml`
-```xml
-
-
-
-```
-
-### Add WidgetReceiver to AndroidManifest
-```xml
-
-
-
-
-
-
-```
-
-### Write your WidgetProvider
-For convenience, you can extend from [HomeWidgetProvider](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetProvider.kt) which gives you access to a SharedPreferences Object with the Data in the `onUpdate` method.
-In case you don't want to use the convenience Method you can access the Data using
-```kotlin
-import es.antonborri.home_widget.HomeWidgetPlugin
-...
-HomeWidgetPlugin.getData(context)
-```
-which will give you access to the same SharedPreferences
-
-### More Information
-For more Information on how to create and configure Android Widgets, check out [this guide](https://developer.android.com/develop/ui/views/appwidgets) on the Android Developers Page.
-
-iOS
-
-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
-
-Dart
-
-1. Write a **static** function that takes a Uri as an argument. This will get called when a user clicks on the View
- ```dart
- @pragma("vm:entry-point")
- FutureOr backgroundCallback(Uri data) async {
- // do something with data
- ...
- }
- ```
- `@pragma('vm:entry-point')` must be placed above the `callback` function to avoid tree shaking in release mode.
-
-2. Register the callback function by calling
- ```dart
- HomeWidget.registerInteractivityCallback(backgroundCallback);
- ```
-iOS
-
-1. Adjust your Podfile to add `home_widget` as a dependency to your WidgetExtension
- ```rb
- target 'YourWidgetExtension' do
- use_frameworks!
- use_modular_headers!
-
- pod 'home_widget', :path => '.symlinks/plugins/home_widget/ios'
- end
- ```
-2. To be able to use plugins with the Background Callback add this to your AppDelegate's `application` function
- ```swift
- if #available(iOS 17, *) {
- HomeWidgetBackgroundWorker.setPluginRegistrantCallback { registry in
- GeneratedPluginRegistrant.register(with: registry)
- }
- }
- ```
-3. Create a custom `AppIntent` in your App Target (Runner) and make sure to select both your App and your WidgetExtension in the Target Membership panel
-
- 
-
- In this Intent you should import `home_widget` and call `HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)` in the perform method. `url` and `appGroup` can be either hardcoded or set as parameters from the Widget
- ```swift
- import AppIntents
- import Flutter
- import Foundation
- import home_widget
-
- @available(iOS 16, *)
- public struct BackgroundIntent: AppIntent {
- static public var title: LocalizedStringResource = "HomeWidget Background Intent"
-
- @Parameter(title: "Widget URI")
- var url: URL?
-
- @Parameter(title: "AppGroup")
- var appGroup: String?
-
- public init() {}
-
- public init(url: URL?, appGroup: String?) {
- self.url = url
- self.appGroup = appGroup
- }
-
- public func perform() async throws -> some IntentResult {
- await HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)
-
- return .result()
- }
- }
- ```
-4. Add a Button to your Widget. This Button might be encapsulated by a Version check. Pass in an instance of the `AppIntent` created in the previous step
- ```swift
- Button(
- intent: BackgroundIntent(
- url: URL(string: "homeWidgetExample://titleClicked"), appGroup: widgetGroupId)
- ) {
- Text(entry.title).bold().font( /*@START_MENU_TOKEN@*/.title /*@END_MENU_TOKEN@*/)
- }.buttonStyle(.plain)
- ```
-5. With the current setup the Widget is now Interactive as long as the App is still in the background. If you want to have the Widget be able to wake the App up you need to add the following to your `AppIntent` file
- ```swift
- @available(iOS 16, *)
- @available(iOSApplicationExtension, unavailable)
- extension BackgroundIntent: ForegroundContinuableIntent {}
- ```
- This code tells the system to always perform the Intent in the App and not in a process attached to the Widget. Note however that this will start your Flutter App using the normal main entrypoint meaning your full app might be run in the background. To counter this you should add checks in the very first Widget you build inside `runApp` to only perform necessary calls/setups while the App is launched in the background
-Android Jetpack Glance
-
-1. Add the necessary Receiver and Service to your `AndroidManifest.xml` file
- ```
-
-
-
-
-
-
- ```
-2. Create a custom Action
- ```kotlin
- class InteractiveAction : ActionCallback {
- override suspend fun onAction(context: Context, glanceId: GlanceId, parameters: ActionParameters) {
- val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(context, Uri.parse("homeWidgetExample://titleClicked"))
- backgroundIntent.send()
- }
- }
- ```
-3. Add the Action as a modifier to a view
- ```kotlin
- Text(
- title,
- style = TextStyle(fontSize = 36.sp, fontWeight = FontWeight.Bold),
- modifier = GlanceModifier.clickable(onClick = actionRunCallback()),
- )
- ```
-
-Android XML
-
-1. Add the necessary Receiver and Service to your `AndroidManifest.xml` file
- ```
-
-
-
-
-
-
- ```
-2. Add a `HomeWidgetBackgroundIntent.getBroadcast` PendingIntent to the View you want to add a click listener to
- ```kotlin
- val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(
- context,
- Uri.parse("homeWidgetExample://titleClicked")
- )
- setOnClickPendingIntent(R.id.widget_title, backgroundIntent)
- ```
-Dart
-For example, say you have a chart in your Flutter app configured with `CustomPaint`:
-
-```dart
-class LineChart extends StatelessWidget {
- const LineChart({
- super.key,
- });
-
- @override
- Widget build(BuildContext context) {
- return CustomPaint(
- painter: LineChartPainter(),
- child: const SizedBox(
- height: 200,
- width: 200,
- ),
- );
- }
-}
-```
-
-
-
-Rewriting the code to create this chart on both Android and iOS might be time consuming.
-Instead, you can generate a png file of the Flutter widget and save it to a shared container
-between your Flutter app and the home screen widget.
-
-```dart
-var path = await HomeWidget.renderFlutterWidget(
- const LineChart(),
- key: 'lineChart',
- logicalSize: const Size(400, 400),
-);
-```
-- `LineChart()` is the widget that will be rendered as an image.
-- `key` is the key in the key/value storage on the device that stores the path of the file for easy retrieval on the native side
-iOS
-To retrieve the image and display it in a widget, you can use the following SwiftUI code:
-
-1. In your `TimelineEntry` struct add a property to retrieve the path:
- ```swift
- struct MyEntry: TimelineEntry {
- …
- let lineChartPath: String
- }
- ```
-
-2. Get the path from the `UserDefaults` in `getSnapshot`:
- ```swift
- func getSnapshot(
- ...
- let lineChartPath = userDefaults?.string(forKey: "lineChart") ?? "No screenshot available"
- ```
-3. Create a `View` to display the chart and resize the image based on the `displaySize` of the widget:
- ```swift
- struct WidgetEntryView : View {
- …
- var ChartImage: some View {
- if let uiImage = UIImage(contentsOfFile: entry.lineChartPath) {
- let image = Image(uiImage: uiImage)
- .resizable()
- .frame(width: entry.displaySize.height*0.5, height: entry.displaySize.height*0.5, alignment: .center)
- return AnyView(image)
- }
- print("The image file could not be loaded")
- return AnyView(EmptyView())
- }
- …
- }
- ```
-
-4. Display the chart in the body of the widget's `View`:
- ```swift
- VStack {
- Text(entry.title)
- Text(entry.description)
- ChartImage
- }
- ```
-
-
-Android (Jetpack Glance)
-
-```kotlin
-// Access data
-val data = currentState.preferences
-
-// Get Path
-val imagePath = data.getString("lineChart", null)
-
-// Add Image to Compose Tree
-imagePath?.let {
- val bitmap = BitmapFactory.decodeFile(it)
- Image(androidx.glance.ImageProvider(bitmap), null)
-}
-```
-
-Android (XML)
-
-1. Add an image UI element to your xml file:
- ```xml
-
- ```
-2. Update your Kotlin code to get the chart image and put it into the widget, if it exists.
- ```kotlin
- class NewsWidget : AppWidgetProvider() {
- override fun onUpdate(
- context: Context,
- appWidgetManager: AppWidgetManager,
- appWidgetIds: IntArray,
- ) {
- for (appWidgetId in appWidgetIds) {
- // Get reference to SharedPreferences
- val widgetData = HomeWidgetPlugin.getData(context)
- val views = RemoteViews(context.packageName, R.layout.news_widget).apply {
- // Get chart image and put it in the widget, if it exists
- val imagePath = widgetData.getString("lineChart", null)
- val imageFile = File(imagePath)
- val imageExists = imageFile.exists()
- if (imageExists) {
- val myBitmap: Bitmap = BitmapFactory.decodeFile(imageFile.absolutePath)
- setImageViewBitmap(R.id.widget_image, myBitmap)
- } else {
- println("image not found!, looked @: $imagePath")
- }
- // End new code
- }
- appWidgetManager.updateAppWidget(appWidgetId, views)
- }
- }
- }
- ```
-iOS
-
-Add `.widgetUrl` to your WidgetComponent
-```swift
-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 queryParameter`homeWidget` to the URL
-Android Jetpack Glance
-
-Add an `IntentFilter` to the `Activity` Section in your `AndroidManifest`
-```
-
-
-
-```
-
-Add the following modifier to your Widget (import from HomeWidget)
-```kotlin
-Text(
- message,
- style = TextStyle(fontSize = 18.sp),
- modifier = GlanceModifier.clickable(
- onClick = actionStartActivity(
- context,
- Uri.parse("homeWidgetExample://message?message=$message")
- )
- )
-)
-```
-
-Android XML
-
-Add an `IntentFilter` to the `Activity` Section in your `AndroidManifest`
-```
-
-
-
-```
-
-In your WidgetProvider add a PendingIntent to your View using `HomeWidgetLaunchIntent.getActivity`
-```kotlin
-val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity(
- context,
- MainActivity::class.java,
- Uri.parse("homeWidgetExample://message?message=$message"))
-setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
-```
-
-iOS
+
+### Add a Widget to your App in Xcode
+Add a widget extension by going File > New > Target > Widget Extension
+
+
+
+
+### Add GroupId
+You need to add a groupId to the App and the Widget Extension
+
+**Note: in order to add groupIds you need a paid Apple Developer Account**
+
+Go to your [Apple Developer Account](https://developer.apple.com/account/resources/identifiers/list/applicationGroup) and add a new group.
+Add this group to your Runner and the Widget Extension inside XCode: Signing & Capabilities > App Groups > +.
+(To swap between your App, and the Extension change the Target)
+
+
+
+### Sync CFBundleVersion (optional)
+This step is optional, this will sync the widget extension build version with your app version, so you don't get warnings of mismatch version from App Store Connect when uploading your app.
+
+
+
+In your Runner (app) target go to Build Phases > + > New Run Script Phase and add the following script:
+```bash
+generatedPath="$SRCROOT/Flutter/Generated.xcconfig"
+
+# Read and trim versionNumber and buildNumber
+versionNumber=$(grep FLUTTER_BUILD_NAME "$generatedPath" | cut -d '=' -f2 | xargs)
+buildNumber=$(grep FLUTTER_BUILD_NUMBER "$generatedPath" | cut -d '=' -f2 | xargs)
+
+infoPlistPath="$SRCROOT/HomeExampleWidget/Info.plist"
+
+# Check and add CFBundleVersion if it does not exist
+/usr/libexec/PlistBuddy -c "Print :CFBundleVersion" "$infoPlistPath" 2>/dev/null
+if [ $? != 0 ]; then
+ /usr/libexec/PlistBuddy -c "Add :CFBundleVersion string $buildNumber" "$infoPlistPath"
+else
+ /usr/libexec/PlistBuddy -c "Set :CFBundleVersion $buildNumber" "$infoPlistPath"
+fi
+
+# Check and add CFBundleShortVersionString if it does not exist
+/usr/libexec/PlistBuddy -c "Print :CFBundleShortVersionString" "$infoPlistPath" 2>/dev/null
+if [ $? != 0 ]; then
+ /usr/libexec/PlistBuddy -c "Add :CFBundleShortVersionString string $versionNumber" "$infoPlistPath"
+else
+ /usr/libexec/PlistBuddy -c "Set :CFBundleShortVersionString $versionNumber" "$infoPlistPath"
+fi
+
+```
+
+Replace `HomeExampleWidget` with the name of the widget extension folder that you have created.
+
+
+### Write your Widget
+Check the [Example App](example/ios/HomeWidgetExample/HomeWidgetExample.swift) for an Implementation of a Widget.
+A more detailed overview on how to write Widgets for iOS 14 can be found on the [Apple Developer documentation](https://developer.apple.com/documentation/swiftui/widget).
+In order to access the Data send with Flutter can be access with
+```swift
+let data = UserDefaults.init(suiteName:"YOUR_GROUP_ID")
+```
+Android (Jetpack Glance)
+
+### Add Jetpack Glance as a dependency to you app's Gradle File
+```groovy
+implementation 'androidx.glance:glance-appwidget:LATEST-VERSION'
+```
+
+### Create Widget Configuration into `android/app/src/main/res/xml`
+```xml
+
+
+```
+
+### Add WidgetReceiver to AndroidManifest
+```xml
+
+
+
+
+
+
+```
+
+### Create WidgetReceiver
+
+To get automatic Updates you should extend from [HomeWidgetGlanceWidgetReceiver](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetGlanceWidgetReceiver.kt)
+
+Your Receiver should then look like this
+
+```kotlin
+package es.antonborri.home_widget_example.glance
+
+import HomeWidgetGlanceWidgetReceiver
+
+class HomeWidgetReceiver : HomeWidgetGlanceWidgetReceiver() {
+ override val glanceAppWidget = HomeWidgetGlanceAppWidget()
+}
+```
+
+### Build Your AppWidget
+
+```kotlin
+
+class HomeWidgetGlanceAppWidget : GlanceAppWidget() {
+
+ /**
+ * Needed for Updating
+ */
+ override val stateDefinition = HomeWidgetGlanceStateDefinition()
+
+ override suspend fun provideGlance(context: Context, id: GlanceId) {
+ provideContent {
+ GlanceContent(context, currentState())
+ }
+ }
+
+ @Composable
+ private fun GlanceContent(context: Context, currentState: HomeWidgetGlanceState) {
+ // Use data to access the data you save with
+ val data = currentState.preferences
+
+
+ // Build Your Composable Widget
+ Column(
+ ...
+ }
+
+```
+
+Android (XML)
+
+### Create Widget Layout inside `android/app/src/main/res/layout`
+
+### Create Widget Configuration into `android/app/src/main/res/xml`
+```xml
+
+
+
+```
+
+### Add WidgetReceiver to AndroidManifest
+```xml
+
+
+
+
+
+
+```
+
+### Write your WidgetProvider
+For convenience, you can extend from [HomeWidgetProvider](android/src/main/kotlin/es/antonborri/home_widget/HomeWidgetProvider.kt) which gives you access to a SharedPreferences Object with the Data in the `onUpdate` method.
+In case you don't want to use the convenience Method you can access the Data using
+```kotlin
+import es.antonborri.home_widget.HomeWidgetPlugin
+...
+HomeWidgetPlugin.getData(context)
+```
+which will give you access to the same SharedPreferences
+
+### More Information
+For more Information on how to create and configure Android Widgets, check out [this guide](https://developer.android.com/develop/ui/views/appwidgets) on the Android Developers Page.
+
+iOS
+
+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
+
+Dart
+
+1. Write a **static** function that takes a Uri as an argument. This will get called when a user clicks on the View
+ ```dart
+ @pragma("vm:entry-point")
+ FutureOr backgroundCallback(Uri data) async {
+ // do something with data
+ ...
+ }
+ ```
+ `@pragma('vm:entry-point')` must be placed above the `callback` function to avoid tree shaking in release mode.
+
+2. Register the callback function by calling
+ ```dart
+ HomeWidget.registerInteractivityCallback(backgroundCallback);
+ ```
+iOS
+
+1. Adjust your Podfile to add `home_widget` as a dependency to your WidgetExtension
+ ```rb
+ target 'YourWidgetExtension' do
+ use_frameworks!
+ use_modular_headers!
+
+ pod 'home_widget', :path => '.symlinks/plugins/home_widget/ios'
+ end
+ ```
+2. To be able to use plugins with the Background Callback add this to your AppDelegate's `application` function
+ ```swift
+ if #available(iOS 17, *) {
+ HomeWidgetBackgroundWorker.setPluginRegistrantCallback { registry in
+ GeneratedPluginRegistrant.register(with: registry)
+ }
+ }
+ ```
+3. Create a custom `AppIntent` in your App Target (Runner) and make sure to select both your App and your WidgetExtension in the Target Membership panel
+
+ 
+
+ In this Intent you should import `home_widget` and call `HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)` in the perform method. `url` and `appGroup` can be either hardcoded or set as parameters from the Widget
+ ```swift
+ import AppIntents
+ import Flutter
+ import Foundation
+ import home_widget
+
+ @available(iOS 16, *)
+ public struct BackgroundIntent: AppIntent {
+ static public var title: LocalizedStringResource = "HomeWidget Background Intent"
+
+ @Parameter(title: "Widget URI")
+ var url: URL?
+
+ @Parameter(title: "AppGroup")
+ var appGroup: String?
+
+ public init() {}
+
+ public init(url: URL?, appGroup: String?) {
+ self.url = url
+ self.appGroup = appGroup
+ }
+
+ public func perform() async throws -> some IntentResult {
+ await HomeWidgetBackgroundWorker.run(url: url, appGroup: appGroup!)
+
+ return .result()
+ }
+ }
+ ```
+4. Add a Button to your Widget. This Button might be encapsulated by a Version check. Pass in an instance of the `AppIntent` created in the previous step
+ ```swift
+ Button(
+ intent: BackgroundIntent(
+ url: URL(string: "homeWidgetExample://titleClicked"), appGroup: widgetGroupId)
+ ) {
+ Text(entry.title).bold().font( /*@START_MENU_TOKEN@*/.title /*@END_MENU_TOKEN@*/)
+ }.buttonStyle(.plain)
+ ```
+5. With the current setup the Widget is now Interactive as long as the App is still in the background. If you want to have the Widget be able to wake the App up you need to add the following to your `AppIntent` file
+ ```swift
+ @available(iOS 16, *)
+ @available(iOSApplicationExtension, unavailable)
+ extension BackgroundIntent: ForegroundContinuableIntent {}
+ ```
+ This code tells the system to always perform the Intent in the App and not in a process attached to the Widget. Note however that this will start your Flutter App using the normal main entrypoint meaning your full app might be run in the background. To counter this you should add checks in the very first Widget you build inside `runApp` to only perform necessary calls/setups while the App is launched in the background
+Android Jetpack Glance
+
+1. Add the necessary Receiver and Service to your `AndroidManifest.xml` file
+ ```
+
+
+
+
+
+
+ ```
+2. Create a custom Action
+ ```kotlin
+ class InteractiveAction : ActionCallback {
+ override suspend fun onAction(context: Context, glanceId: GlanceId, parameters: ActionParameters) {
+ val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(context, Uri.parse("homeWidgetExample://titleClicked"))
+ backgroundIntent.send()
+ }
+ }
+ ```
+3. Add the Action as a modifier to a view
+ ```kotlin
+ Text(
+ title,
+ style = TextStyle(fontSize = 36.sp, fontWeight = FontWeight.Bold),
+ modifier = GlanceModifier.clickable(onClick = actionRunCallback()),
+ )
+ ```
+
+Android XML
+
+1. Add the necessary Receiver and Service to your `AndroidManifest.xml` file
+ ```
+
+
+
+
+
+
+ ```
+2. Add a `HomeWidgetBackgroundIntent.getBroadcast` PendingIntent to the View you want to add a click listener to
+ ```kotlin
+ val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(
+ context,
+ Uri.parse("homeWidgetExample://titleClicked")
+ )
+ setOnClickPendingIntent(R.id.widget_title, backgroundIntent)
+ ```
+Dart
+For example, say you have a chart in your Flutter app configured with `CustomPaint`:
+
+```dart
+class LineChart extends StatelessWidget {
+ const LineChart({
+ super.key,
+ });
+
+ @override
+ Widget build(BuildContext context) {
+ return CustomPaint(
+ painter: LineChartPainter(),
+ child: const SizedBox(
+ height: 200,
+ width: 200,
+ ),
+ );
+ }
+}
+```
+
+
+
+Rewriting the code to create this chart on both Android and iOS might be time consuming.
+Instead, you can generate a png file of the Flutter widget and save it to a shared container
+between your Flutter app and the home screen widget.
+
+```dart
+var path = await HomeWidget.renderFlutterWidget(
+ const LineChart(),
+ key: 'lineChart',
+ logicalSize: const Size(400, 400),
+);
+```
+- `LineChart()` is the widget that will be rendered as an image.
+- `key` is the key in the key/value storage on the device that stores the path of the file for easy retrieval on the native side
+iOS
+To retrieve the image and display it in a widget, you can use the following SwiftUI code:
+
+1. In your `TimelineEntry` struct add a property to retrieve the path:
+ ```swift
+ struct MyEntry: TimelineEntry {
+ …
+ let lineChartPath: String
+ }
+ ```
+
+2. Get the path from the `UserDefaults` in `getSnapshot`:
+ ```swift
+ func getSnapshot(
+ ...
+ let lineChartPath = userDefaults?.string(forKey: "lineChart") ?? "No screenshot available"
+ ```
+3. Create a `View` to display the chart and resize the image based on the `displaySize` of the widget:
+ ```swift
+ struct WidgetEntryView : View {
+ …
+ var ChartImage: some View {
+ if let uiImage = UIImage(contentsOfFile: entry.lineChartPath) {
+ let image = Image(uiImage: uiImage)
+ .resizable()
+ .frame(width: entry.displaySize.height*0.5, height: entry.displaySize.height*0.5, alignment: .center)
+ return AnyView(image)
+ }
+ print("The image file could not be loaded")
+ return AnyView(EmptyView())
+ }
+ …
+ }
+ ```
+
+4. Display the chart in the body of the widget's `View`:
+ ```swift
+ VStack {
+ Text(entry.title)
+ Text(entry.description)
+ ChartImage
+ }
+ ```
+
+
+Android (Jetpack Glance)
+
+```kotlin
+// Access data
+val data = currentState.preferences
+
+// Get Path
+val imagePath = data.getString("lineChart", null)
+
+// Add Image to Compose Tree
+imagePath?.let {
+ val bitmap = BitmapFactory.decodeFile(it)
+ Image(androidx.glance.ImageProvider(bitmap), null)
+}
+```
+
+Android (XML)
+
+1. Add an image UI element to your xml file:
+ ```xml
+
+ ```
+2. Update your Kotlin code to get the chart image and put it into the widget, if it exists.
+ ```kotlin
+ class NewsWidget : AppWidgetProvider() {
+ override fun onUpdate(
+ context: Context,
+ appWidgetManager: AppWidgetManager,
+ appWidgetIds: IntArray,
+ ) {
+ for (appWidgetId in appWidgetIds) {
+ // Get reference to SharedPreferences
+ val widgetData = HomeWidgetPlugin.getData(context)
+ val views = RemoteViews(context.packageName, R.layout.news_widget).apply {
+ // Get chart image and put it in the widget, if it exists
+ val imagePath = widgetData.getString("lineChart", null)
+ val imageFile = File(imagePath)
+ val imageExists = imageFile.exists()
+ if (imageExists) {
+ val myBitmap: Bitmap = BitmapFactory.decodeFile(imageFile.absolutePath)
+ setImageViewBitmap(R.id.widget_image, myBitmap)
+ } else {
+ println("image not found!, looked @: $imagePath")
+ }
+ // End new code
+ }
+ appWidgetManager.updateAppWidget(appWidgetId, views)
+ }
+ }
+ }
+ ```
+iOS
+
+Add `.widgetUrl` to your WidgetComponent
+```swift
+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 queryParameter`homeWidget` to the URL
+Android Jetpack Glance
+
+Add an `IntentFilter` to the `Activity` Section in your `AndroidManifest`
+```
+
+
+
+```
+
+Add the following modifier to your Widget (import from HomeWidget)
+```kotlin
+Text(
+ message,
+ style = TextStyle(fontSize = 18.sp),
+ modifier = GlanceModifier.clickable(
+ onClick = actionStartActivity(
+ context,
+ Uri.parse("homeWidgetExample://message?message=$message")
+ )
+ )
+)
+```
+
+Android XML
+
+Add an `IntentFilter` to the `Activity` Section in your `AndroidManifest`
+```
+
+
+
+```
+
+In your WidgetProvider add a PendingIntent to your View using `HomeWidgetLaunchIntent.getActivity`
+```kotlin
+val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity(
+ context,
+ MainActivity::class.java,
+ Uri.parse("homeWidgetExample://message?message=$message"))
+setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
+```
+
+