HomeWidget

https://docs.page/ABausG/home_widget
Admin
HomeWidget is a Flutter plugin that provides a unified interface for creating, updating, and...
Tokens:13,158
Snippets:206
Trust Score:8.4
Update:6 months ago
Show doc for...
Tokens:
Raw
### Example Widget Configuration Data

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

This is an example of the configuration data structure for a Greeting widget, showing how 'name' and 'punctuation' are represented. This structure is what `HomeWidget.getInstalledWidgets()` might return.

```json
{
    "name": "Documentation",
    "punctuation": {
        "id": "!!!"
    }
}
```

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

### Get Installed Widgets with Configuration

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Retrieve a list of installed widgets and their configurations using `HomeWidget.getInstalledWidgets()`. Note that this method returns an empty list on iOS Simulators and should be tested on a real iOS device.

```dart
final configuration = await HomeWidget.getInstalledWidgets();
```

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

### Get Installed Widgets

Source: https://docs.page/ABausG/home_widget/features/analytics

Retrieve a list of widgets currently installed by the user. Note that iOS limits unique widget entries based on size and type.

```dart
final List<HomeWidgetInfo> info = await HomeWidget.getInstalledWidgets();
```

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

### Android Glance Setup

Source: https://docs.page/ABausG/home_widget/usage/update-widget

Configuration required for Android Glance widgets to support HomeWidget updates.

```APIDOC
## Android Glance Configuration

### Description
To ensure an Android Glance Widget receives updates, the HomeWidgetGlanceStateDefinition must be implemented within the widget class.

### Request Example
override val stateDefinition: GlanceStateDefinition<*>?
  get() = HomeWidgetGlanceStateDefinition()
```

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

### Initialize App Launch from Widget (Background)

Source: https://docs.page/ABausG/home_widget/features/detect-clicks

Use this method when your app is started from the background by a widget click. It returns a Future containing the Uri used to launch the app, or null if not launched by a widget.

```dart
HomeWidget.initiallyLaunchedFromHomeWidget();
```

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

### Widget Layout XML

Source: https://docs.page/ABausG/home_widget/android-xml/setup

Create the visual layout for your widget using RemoteViews. This example shows a simple LinearLayout with a TextView.

```xml
<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:background="#FFFFFF"
    android:gravity="center"
    android:orientation="vertical"
    android:padding="8dp">
        <TextView
            android:id="@+id/text_counter"
            android:layout_width="match_parent"
            android:layout_height="wrap_content"
            android:gravity="center"
            android:text="0"
            android:textAppearance="@android:style/TextAppearance.Material.Large" />
</LinearLayout>

```

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

### Kotlin WidgetProvider Implementation

Source: https://docs.page/ABausG/home_widget/android-xml/setup

Extend `HomeWidgetProvider` to easily access widget data via SharedPreferences in the `onUpdate` method. This example updates a TextView with a counter value.

```kotlin
// Remember to set a package in order for home_widget to find the Provider
package es.antonborri.home_widget_counter

import es.antonborri.home_widget.HomeWidgetProvider

class CounterWidgetProvider : HomeWidgetProvider() {
    override fun onUpdate(
            context: Context,
            appWidgetManager: AppWidgetManager,
            appWidgetIds: IntArray,
            widgetData: SharedPreferences) {
        appWidgetIds.forEach { widgetId ->
            val views = RemoteViews(context.packageName, R.layout.counter_widget).apply {
                val count = widgetData.getInt("counter", 0)
                setTextViewText(R.id.text_counter, count.toString())
            }
            // This line is important to trigger the update
            appWidgetManager.updateAppWidget(widgetId, views)
        }
    }
}


```

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

### Access Configuration in Widget UI

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Access the defined configuration fields within your SwiftUI Widget Entry View. This example displays the 'name' parameter passed from the configuration.

```swift
struct ConfigurableWidgetEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text("Hello")
            Text(entry.configuration.name)
        }
    }
}
```

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

### Define a Flutter Widget for Rendering

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Define a StatelessWidget that will be rendered as a PNG image. This example uses CustomPaint to draw a line chart.

```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,
      ),
    );
  }
}

```

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

### Define Configuration Parameter in AppIntent.swift

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Add fields to your Widget's configuration by modifying the generated ConfigurationAppIntent class. This example shows how to add a 'Name' parameter.

```swift
@Parameter(title: "Name", default: "World")
var name: String
```

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

### Declare Configuration Activity in AndroidManifest.xml

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Register the `WidgetConfigurationActivity` in your `AndroidManifest.xml` with an intent filter for `android.appwidget.action.APPWIDGET_CONFIGURE`. Ensure it mirrors the Flutter embedding setup of your `MainActivity`.

```xml
<activity
    android:name=".WidgetConfigurationActivity"
    android:exported="true"
    android:launchMode="singleTop"
    ... >
    <meta-data
        android:name="io.flutter.embedding.android.NormalTheme"
        android:resource="@style/NormalTheme" />
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_CONFIGURE" />
    </intent-filter>
</activity>

```

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

### Define PunctuationEntity and PunctuationQuery

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Define AppEntity and EntityQuery to manage custom data like punctuation for widget configurations. Ensure the entity is Codable for easy data extraction by home_widget. This setup allows Flutter to best extract values from a configuration.

```swift
@Parameter(title: "Punctuation")
var punctuation: PunctuationEntity
}

// Make Entity Codable so home_widget
// That way home_widget can best extract the values from a configuration
struct PunctuationEntity: AppEntity, Codable {

let id: String

static var typeDisplayRepresentation: TypeDisplayRepresentation = "Punctuation"
static var defaultQuery = PunctuationQuery()

var displayRepresentation: DisplayRepresentation {
    DisplayRepresentation(title: "\(id)")
}
}

struct PunctuationQuery: EntityQuery {

func punctuations() -> [PunctuationEntity] {
    let userDefaults = UserDefaults(suiteName: "YOUR_APP_GROUP")

    do {
    let jsonPunctuations = (userDefaults?.string(forKey: "punctuations") ?? "[\"!\"]").data(
        using: .utf8)! // Ensure data is not nil
    let stringArray = try JSONDecoder().decode([String].self, from: jsonPunctuations)
    return stringArray.map {
        PunctuationEntity(id: $0)

    }
    } catch {
    return [PunctuationEntity(id: "!")]
    }

}

func entities(for identifiers: [PunctuationEntity.ID]) async throws -> [PunctuationEntity] {
    let results = punctuations().filter { identifiers.contains($0.id) }
    return results
}

func suggestedEntities() async throws -> [PunctuationEntity] {
    return punctuations()
}

func defaultResult() async -> PunctuationEntity? {
    try? await suggestedEntities().first
}

}
```

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

### Remove Podfile Adjustment for home_widget

Source: https://docs.page/ABausG/home_widget/migrations/swift-package-manager

Remove the home_widget entry from your Podfile when migrating to Swift Package Manager. After removal, run 'pod install'.

```ruby
target 'YourWidgetExtension' do
   use_frameworks!
   use_modular_headers!

   pod 'home_widget', :path => '.symlinks/plugins/home_widget/ios'
end

```

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

### Accessing Configuration in Widget View

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Display custom configuration values within your Flutter widget's view. This example shows how to access and display the 'name' and 'punctuation.id' from the widget's entry configuration.

```swift
struct ConfigurableWidgetEntryView: View {
var entry: Provider.Entry

var body: some View {
    VStack {
    Text("Hello")
    Text(entry.configuration.name)
    Text(entry.configuration.punctuation.id)
    }
}
}
```

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

### Get Image Path from UserDefaults in iOS

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Retrieve the image path from `UserDefaults` within the `getSnapshot` function using the specified key.

```swift
func getSnapshot(
    ...
    let lineChartPath = userDefaults?.string(forKey: "lineChart") ?? "No screenshot available"

```

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

### Save Widget Data from Flutter

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Use `HomeWidget.saveWidgetData` to store data from your Flutter app that can be used as options in the widget's configuration panel. This example saves a list of punctuations.

```dart
final punctuations = [
    '!',
    '!!!',
    '.',
    '?',
    // Wave Emoji
    '\u{1F44B}',
];
await HomeWidget.saveWidgetData(
    'punctuations',
    jsonEncode(punctuations),
);
```

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

### Add Clickable Modifier in Android

Source: https://docs.page/ABausG/home_widget/features/detect-clicks

Apply the `.clickable` modifier from HomeWidget to your Text element in Android. This allows you to specify an action to start an activity with a given Uri.

```kotlin
Text(
   message,
   style = TextStyle(fontSize = 18.sp),
   modifier = GlanceModifier.clickable(
     onClick = actionStartActivity<MainActivity>(
       context,
       Uri.parse("homeWidgetExample://message?message=$message")
     )
   )
)
```

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

### Widget Configuration XML

Source: https://docs.page/ABausG/home_widget/setup/android

Create a configuration file in `res/xml` to define properties like size constraints and preview layouts for your widget.

```xml
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:resizeMode="horizontal|vertical"
    android:updatePeriodMillis="10000">
</appwidget-provider>
```

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

### Define and Use a Second Dart Entry Point

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Define a second Dart entry point function, `configureMain`, marked with `@pragma('vm:entry-point')`. This function should initialize Flutter, check if launched for widget configuration using `HomeWidget.initiallyLaunchedFromHomeWidgetConfigure()`, and either run your configuration UI or fall back to `main()`.

```dart
@pragma('vm:entry-point')
Future<void> configureMain() async {
  WidgetsFlutterBinding.ensureInitialized();
  final configuredWidgetId =
      await HomeWidget.initiallyLaunchedFromHomeWidgetConfigure();

  if (configuredWidgetId != null) {
    return runApp(MaterialApp(
      home: YourConfigurationScreen(widgetId: configuredWidgetId),
    ));
  }
  return main();
}

```

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

### Build Widget View

Source: https://docs.page/ABausG/home_widget/setup/ios

Construct the SwiftUI layout using the data provided by the TimelineEntry.

```swift
struct WidgetEntryView : View {
    var entry: Provider.Entry

    var body: some View {
        VStack {
            Text(entry.counter.description)
        }
    }
}
```

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

### Implement IntentTimelineProvider

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Create an IntentTimelineProvider for SiriKit Intents to manage widget timeline entries. Includes placeholder, snapshot, and timeline generation logic.

```swift
struct IntentProvider: IntentTimelineProvider {
    typealias Entry = SimpleEntry

    typealias Intent = GreetingIntentIntent

    func placeholder(in context: Context) -> SimpleEntry {
        SimpleEntry(date: Date(), name: "World")
    }

    func getSnapshot(
        for configuration: GreetingIntentIntent, in context: Context,
        completion: @escaping (SimpleEntry) -> Void
    ) {
        completion(SimpleEntry(date: Date(), name: configuration.Name))
    }

    func getTimeline(
        for configuration: GreetingIntentIntent, in context: Context,
        completion: @escaping (Timeline<SimpleEntry>) -> Void
    ) {
        var entries: [SimpleEntry] = []

        // Generate a timeline consisting of five entries an hour apart, starting from the current date.
        let currentDate = Date()
        for hourOffset in 0..<5 {
        let entryDate = Calendar.current.date(byAdding: .hour, value: hourOffset, to: currentDate)!
        let entry = SimpleEntry(date: entryDate, name: configuration.Name)
        entries.append(entry)
        }

        completion(Timeline(entries: entries, policy: .atEnd))
    }
}
```

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

### Create a Dedicated Configuration Activity

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Subclass `FlutterActivity` and override `getDartEntrypointFunctionName` to specify a custom Dart entry point for widget configuration. This ensures Flutter runs `configureMain` instead of the default `main`.

```kotlin
package es.antonborri.configurable_widget

import io.flutter.embedding.android.FlutterActivity

class WidgetConfigurationActivity : FlutterActivity() {
  override fun getDartEntrypointFunctionName(): String = "configureMain"
}

```

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

### Enable Foreground Continuation for AppIntent

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Extend the AppIntent to allow the widget to wake the main application.

```swift
@available(iOS 16, *)
@available(iOSApplicationExtension, unavailable)
extension BackgroundIntent: ForegroundContinuableIntent {}
```

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

### Enable Compose Support in Gradle

Source: https://docs.page/ABausG/home_widget/setup/android

Enable Compose support in your application's build.gradle file to use Jetpack Glance.

```gradle
android {
    ...
    buildFeatures {
        compose true
    }
}
```

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

### POST /saveImage

Source: https://docs.page/ABausG/home_widget/features/save-files

Decodes an ImageProvider and saves the first frame as a PNG file in the shared storage.

```APIDOC
## POST saveImage

### Description
Decodes an ImageProvider and saves the first frame as a PNG file in the shared storage. Animated images will only have the first frame saved.

### Parameters
#### Request Body
- **key** (String) - Required - The key to associate with the saved image path.
- **imageProvider** (ImageProvider) - Required - The image source to be rendered and saved.

### Request Example
```dart
await HomeWidget.saveImage(
  'avatar',
  NetworkImage('https://example.com/photo.png'),
);
```
```

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

### Widget Configuration XML

Source: https://docs.page/ABausG/home_widget/android-xml/setup

Define widget properties like size, resize modes, and update intervals in this XML file. This is essential for basic widget functionality.

```xml
<appwidget-provider xmlns:android="http://schemas.android.com/apk/res/android"
    android:initialLayout="@layout/glance_default_loading_layout"
    android:minWidth="40dp"
    android:minHeight="40dp"
    android:resizeMode="horizontal|vertical"
    android:updatePeriodMillis="10000">
</appwidget-provider>

```

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

### Set Click Listener with PendingIntent

Source: https://docs.page/ABausG/home_widget/android-xml/interactive-widgets

Use HomeWidgetBackgroundIntent.getBroadcast to create a PendingIntent for widget click interactions.

```kotlin
val backgroundIntent = HomeWidgetBackgroundIntent.getBroadcast(
    context,
    Uri.parse("homeWidgetExample://titleClicked")
)
setOnClickPendingIntent(R.id.widget_title, backgroundIntent)
```

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

### Configure Supported Widget Families

Source: https://docs.page/ABausG/home_widget/features/ios-lock-screen

Specify the widget families supported by your app, including accessory widgets for the Lock Screen.

```swift
var body: some WidgetConfiguration {
  ...
  .description("Lock Screen Widgets")
  .supportedFamilies([
      .systemSmall,
      .systemMedium,
      // Accessory Widgets are available on the Lock Screen only
      .accessoryCircular
  ])

}
```

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

### WidgetReceiver Implementation

Source: https://docs.page/ABausG/home_widget/setup/android

Extend `HomeWidgetGlanceWidgetReceiver` and provide your `AppWidget` instance to enable automatic widget updates.

```kotlin
// Remember to set a package in order for home_widget to find the Receiver
package es.antonborri.home_widget_example.glance

import es.antonborri.home_widget.HomeWidgetGlanceWidgetReceiver

class HomeWidgetReceiver : HomeWidgetGlanceWidgetReceiver<AppWidget>() {
    override val glanceAppWidget = AppWidget()
}
```

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

### Listen for Widget Clicks (App Running)

Source: https://docs.page/ABausG/home_widget/features/detect-clicks

When your app is already running, listen to this stream to detect clicks on widget elements. It provides a Stream of Uris that launched the app.

```dart
HomeWidget.widgetClicked;
```

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

### Configure CocoaPods for iOS WidgetExtension

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Add the home_widget dependency to the Podfile for the WidgetExtension target.

```ruby
target 'YourWidgetExtension' do
   use_frameworks!
   use_modular_headers!

   pod 'home_widget', :path => '.symlinks/plugins/home_widget/ios'
end
```

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

### Define Widget Entry Structure

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Define the SimpleEntry struct to hold widget data, supporting both AppIntent and SiriIntent configurations by using properties.

```swift
struct SimpleEntry: TimelineEntry {
    let date: Date
    let configuration: ConfigurationAppIntent 
    let name: String
    var punctuation: String? = nil
}
```

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

### Set PendingIntent in WidgetProvider

Source: https://docs.page/ABausG/home_widget/android-xml/detect-clicks

Use HomeWidgetLaunchIntent to create a pending intent and associate it with a view ID.

```kotlin
val pendingIntentWithData = HomeWidgetLaunchIntent.getActivity(
        context,
        MainActivity::class.java,
        Uri.parse("homeWidgetExample://message?message=$message"))
setOnClickPendingIntent(R.id.widget_message, pendingIntentWithData)
```

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

### Implement InteractiveAction

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Create a custom action class that implements ActionCallback to handle widget interactions.

```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()
    }
}
```

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

### Finish Widget Configuration

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Call `HomeWidget.finishHomeWidgetConfigure()` when the user has completed the configuration. This sets the activity result to `RESULT_OK`, returns the widget ID to the system, and closes the configuration activity.

```dart
await HomeWidget.finishHomeWidgetConfigure();

```

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

### Register Plugin in AppDelegate

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Initialize the background worker and register the plugin in the AppDelegate for iOS 17+.

```swift
if #available(iOS 17, *) {
 HomeWidgetBackgroundWorker.setPluginRegistrantCallback { registry in
     GeneratedPluginRegistrant.register(with: registry)
 }
}
```

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

### AppWidget Definition

Source: https://docs.page/ABausG/home_widget/setup/android

Define your widget's layout and state management by extending `GlanceAppWidget`. Ensure `stateDefinition` is overridden to enable home_widget updates.

```kotlin
// Other imports...
import es.antonborri.home_widget.HomeWidgetGlanceState
import es.antonborri.home_widget.HomeWidgetGlanceStateDefinition

class AppWidget : GlanceAppWidget() {

  override val stateDefinition: GlanceStateDefinition<*>?
    get() = HomeWidgetGlanceStateDefinition()

  override suspend fun provideGlance(context: Context, id: GlanceId) {
    provideContent {
      GlanceContent(context, currentState())
    }
  }

  @Composable
  private fun GlanceContent(context: Context, currentState: HomeWidgetGlanceState) {
    val prefs = currentState.preferences
    val counter = prefs.getInt("counter", 0)
    Box(modifier = GlanceModifier.background(Color.White).padding(16.dp)) {
      Column() {
        Text(
            counter.toString()
        )
      }
    }
  }
}
```

```kotlin
override val stateDefinition: GlanceStateDefinition<*>?
  get() = HomeWidgetGlanceStateDefinition()
```

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

### Implement IntentHandler for Dynamic Data

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Implement the IntentHandler class to provide dynamic options for intent parameters, such as punctuation, by fetching data from UserDefaults.

```swift
import Intents

class IntentHandler: INExtension, GreetingIntentIntentHandling {

func providePunctuationOptionsCollection(for intent: GreetingIntentIntent) async throws -> INObjectCollection<Punctuation> {
    let userDefaults = UserDefaults(suiteName: "YOUR_APP_GROUP")
    
    do {
        let jsonPunctuations = (userDefaults?.string(forKey: "punctuations") ?? "[\"!\"]").data(using: .utf8)!
        let stringArray = try JSONDecoder().decode([String].self, from: jsonPunctuations)
        let items = stringArray.map {
            Punctuation(identifier: $0, display: $0)
        }
        return INObjectCollection(items: items)
        
    } catch {
        return INObjectCollection(items: [Punctuation(identifier: "!", display: "!")])
    }
}
}
```

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

### Implement AppIntent for Background Tasks

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Define a custom AppIntent to trigger the HomeWidgetBackgroundWorker 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()
   }
}
```

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

### POST /saveFile

Source: https://docs.page/ABausG/home_widget/features/save-files

Writes arbitrary bytes to the shared storage area and registers the file path under a specific key.

```APIDOC
## POST saveFile

### Description
Writes arbitrary bytes to the shared storage area and registers the file path under a specific key. The file is stored at {container}/home_widget/{key}.{extension}.

### Parameters
#### Request Body
- **key** (String) - Required - A non-empty string identifier that must not contain /, \, .., or spaces.
- **data** (Uint8List) - Required - The bytes to be written.
- **extension** (String) - Optional - The file extension (e.g., 'json').

### Request Example
```dart
import 'dart:convert';
import 'dart:typed_data';

final json = jsonEncode({'count': 3});
final path = await HomeWidget.saveFile(
  'stats',
  Uint8List.fromList(utf8.encode(json)),
  extension: 'json',
);
```
```

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

### Implement TimelineProvider

Source: https://docs.page/ABausG/home_widget/setup/ios

Define the provider to manage widget updates, using UserDefaults to retrieve data saved from the Flutter application.

```swift
struct Provider: TimelineProvider {
    func placeholder(in context: Context) -> CounterEntry {
        CounterEntry(date: Date(), counter: 0)
    }

    func getSnapshot(in context: Context, completion: @escaping (SimpleEntry) -> ()) {
        let prefs = UserDefaults(suiteName: "group.YOUR_GROUP_ID")
        let counter = prefs?.integer(forKey: "counter")
        let entry = CounterEntry(date: Date(), counter: counter ?? 0)
        completion(entry)
    }

    func getTimeline(in context: Context, completion: @escaping (Timeline<Entry>) -> ()) {
        getSnapshot(in: context) { (entry) in
            let timeline = Timeline(entries: [entry], policy: .atEnd)
            completion(timeline)
        }
    }
}
```

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

### Save an image from an ImageProvider

Source: https://docs.page/ABausG/home_widget/features/save-files

Decodes an ImageProvider and saves the first frame as a PNG file.

```dart
await HomeWidget.saveImage(
  'avatar',
  NetworkImage('https://example.com/photo.png'),
);
```

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

### Register Widget in AndroidManifest.xml

Source: https://docs.page/ABausG/home_widget/setup/android

Register your `HomeWidgetReceiver` in the `AndroidManifest.xml` file, including the necessary intent filter and meta-data for widget updates.

```xml
<receiver android:name=".glance.HomeWidgetReceiver"
          android:exported="true">
   <intent-filter>
      <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
   </intent-filter>
   <meta-data
           android:name="android.appwidget.provider"
           android:resource="@xml/home_widget_glance_example" />
</receiver>
```

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

### Configure Widget Definition for iOS Versions

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Adapt the widget's body to use AppIntentConfiguration for iOS 17.0+ and IntentConfiguration for older versions, ensuring compatibility.

```swift
var body: some WidgetConfiguration {
    if #available(iOS 17.0, *) {
    AppIntentConfiguration(
        return AppIntentConfiguration(
            kind: kind, intent: ConfigurationAppIntent.self, provider: Provider() 
        ) {
            entry in
            ConfigurableWidgetEntryView(entry: entry)
            .containerBackground(.fill.tertiary, for: .widget)
        }
    )
    } else { 
        return IntentConfiguration(
            kind: kind, 
            intent: GreetingIntentIntent.self, 
            provider: IntentProvider()
        ) {
            entry in
            ConfigurableWidgetEntryView(entry: entry)
        } 
    }
}
```

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

### Display Rendered Image in Android Glance Widget

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Use the retrieved image path to load a bitmap and display it using `Image` in an Android Glance Widget.

```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)
}

```

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

### Display Rendered Image in iOS SwiftUI View

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Create a SwiftUI `View` to display the rendered Flutter widget image. Resize the image based on the widget's `displaySize`.

```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())
    }
…
}

```

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

### Configure AndroidManifest.xml for Background Receiver

Source: https://docs.page/ABausG/home_widget/android-xml/interactive-widgets

Register the HomeWidgetBackgroundReceiver in the Android manifest to handle background actions.

```xml
<receiver android:name="es.antonborri.home_widget.HomeWidgetBackgroundReceiver"  android:exported="true">
    <intent-filter>
        <action android:name="es.antonborri.home_widget.action.BACKGROUND" />
    </intent-filter>
</receiver>
```

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

### Configure AppWidgetProvider for Reconfigurability

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

In your `appwidget-provider` XML, set `android:widgetFeatures` to `reconfigurable` and specify the fully qualified class name of your configuration activity in `android:configure`. This enables the system's widget configuration flow.

```xml
<appwidget-provider
    xmlns:android="http://schemas.android.com/apk/res/android"
    ... 
    android:widgetFeatures="reconfigurable"
    android:configure="com.example.app.WidgetConfigurationActivity" />

```

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

### Request to Pin Widget on Android

Source: https://docs.page/ABausG/home_widget/features/pin-widget

Initiates an action to pin a widget to the HomeScreen on Android. This method is only supported on Android API 26+.

```dart
HomeWidget.requestPinWidget(
    name: 'HomeWidgetExampleProvider',
    androidName: 'HomeWidgetExampleProvider',
    qualifiedAndroidName: 'com.example.app.HomeWidgetExampleProvider',
);
```

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

### Register Plugins in AppDelegate

Source: https://docs.page/ABausG/home_widget/features/background-updates

Register plugins in the iOS AppDelegate to enable background communication with the HomeWidget plugin.

```swift
WorkmanagerPlugin.setPluginRegistrantCallback { registry in
    GeneratedPluginRegistrant.register(with: registry)
}
```

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

### Define Background Callback in Flutter

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Create a static function to handle widget click events. The @pragma annotation is required to prevent tree shaking in release builds.

```dart
@pragma("vm:entry-point")
FutureOr<void> backgroundCallback(Uri? data) async {
  // do something with data
  ...
}
```

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

### AndroidManifest WidgetReceiver Registration

Source: https://docs.page/ABausG/home_widget/android-xml/setup

Register your `WidgetProvider` in the `AndroidManifest.xml` file. Ensure the `android.appwidget.provider` meta-data points to your configuration XML.

```xml
<receiver android:name="HomeWidgetExampleProvider" android:exported="true">
    <intent-filter>
        <action android:name="android.appwidget.action.APPWIDGET_UPDATE" />
    </intent-filter>
    <meta-data android:name="android.appwidget.provider"
        android:resource="@xml/home_widget_example" />
</receiver>

```

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

### Update Widget

Source: https://docs.page/ABausG/home_widget/usage/update-widget

Initiates a reload of the HomeScreenWidget to reflect new data or state changes.

```APIDOC
## Update Widget

### Description
Initiates a reload of the HomeScreenWidget. Depending on the platform setup, specific arguments are required to identify the widget provider or receiver.

### Method
Function Call

### Parameters
- **name** (String) - Optional - Used for identification.
- **androidName** (String) - Optional - The class name of the Android Widget Receiver.
- **iOSName** (String) - Optional - Must match the 'kind' defined for the iOS Widget.
- **qualifiedAndroidName** (String) - Optional - The full class path to the Android Widget Receiver.

### Request Example
HomeWidget.updateWidget(
    name: 'HomeWidgetExampleProvider',
    androidName: 'HomeWidgetExampleProvider',
    iOSName: 'HomeWidgetExample',
    qualifiedAndroidName: 'com.example.app.HomeWidgetExampleProvider',
);
```

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

### Register Configuration Intent in AppDelegate

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Register your custom Configuration Intent with the home_widget plugin in your AppDelegate. This step is crucial for the widget to correctly look up and use the provided configuration, especially for iOS 17 and later.

```swift
import Flutter
import UIKit
import home_widget

@main
@objc class AppDelegate: FlutterAppDelegate {
override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
) -> Bool {
    GeneratedPluginRegistrant.register(with: self)
    if #available(iOS 17.0, *) {
    HomeWidgetPlugin.setConfigurationLookup(to: [
        "ConfigurableWidget": ConfigurationAppIntent.self
    ])
    }
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
}
}
```

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

### Accessing Widget Data Directly

Source: https://docs.page/ABausG/home_widget/android-xml/setup

If not extending `HomeWidgetProvider`, you can access the widget data SharedPreferences directly using `HomeWidgetPlugin.getData(context)`.

```kotlin
import es.antonborri.home_widget.HomeWidgetPlugin
...
HomeWidgetPlugin.getData(context)


```

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

### Configure IntentFilter in AndroidManifest

Source: https://docs.page/ABausG/home_widget/android-xml/detect-clicks

Add an intent filter to the Activity section to enable the home_widget launch action.

```xml
<intent-filter>
    <action android:name="es.antonborri.home_widget.action.LAUNCH" />
</intent-filter>
```

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

### Update Android Widget Imports

Source: https://docs.page/ABausG/home_widget/migrations/0.9.0

Replace short imports with fully qualified package names for HomeWidget classes in Android widget code.

```kotlin
import HomeWidgetGlanceState 
import HomeWidgetGlanceStateDefinition 
import HomeWidgetGlanceWidgetReceiver 
import es.antonborri.home_widget.HomeWidgetGlanceState 
import es.antonborri.home_widget.HomeWidgetGlanceStateDefinition 
import es.antonborri.home_widget.HomeWidgetGlanceWidgetReceiver 
```

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

### Add Widget URL in iOS

Source: https://docs.page/ABausG/home_widget/features/detect-clicks

Configure your iOS widget to use the `.widgetUrl` modifier. Append the `homeWidget` query parameter to URLs to specifically identify clicks originating from the home_widget.

```swift
Text(entry.message)
    .font(.body)
    .widgetURL(URL(string: "homeWidgetExample://message?message=\(entry.message)&homeWidget"))
```

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

### Define TimelineEntry

Source: https://docs.page/ABausG/home_widget/setup/ios

Create a custom struct conforming to TimelineEntry to represent the data structure used by the widget.

```swift
struct CounterEntry: TimelineEntry {
    let date: Date
    let counter: Int
}
```

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

### Add Jetpack Glance Dependency

Source: https://docs.page/ABausG/home_widget/setup/android

Add the Jetpack Glance library as a dependency in your app's Gradle file.

```gradle
implementation 'androidx.glance:glance-appwidget:LATEST-VERSION'
```

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

### Save arbitrary bytes as a file

Source: https://docs.page/ABausG/home_widget/features/save-files

Writes bytes to a shared file and registers the path under a specific key.

```dart
import 'dart:convert';
import 'dart:typed_data';

final json = jsonEncode({'count': 3});
final path = await HomeWidget.saveFile(
  'stats',
  Uint8List.fromList(utf8.encode(json)),
  extension: 'json',
);
```

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

### Render Flutter Widget to Image (Flutter)

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Use the `renderFlutterWidget` method to convert a Flutter widget into a PNG image. The `key` parameter stores the file path for native retrieval.

```dart
var path = await HomeWidget.renderFlutterWidget(
  const LineChart(),
  key: 'lineChart',
  logicalSize: const Size(400, 400),
);

```

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

### Update Home Screen Widget

Source: https://docs.page/ABausG/home_widget/usage/update-widget

Initiates a reload of the home screen widget. Arguments vary based on platform requirements for identifying the widget provider.

```dart
HomeWidget.updateWidget(
    name: 'HomeWidgetExampleProvider',
    androidName: 'HomeWidgetExampleProvider',
    iOSName: 'HomeWidgetExample',
    qualifiedAndroidName: 'com.example.app.HomeWidgetExampleProvider',
);
```

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

### Update Kotlin Code to Display Widget Image

Source: https://docs.page/ABausG/home_widget/android-xml/render-flutter-widget

Update your Kotlin AppWidgetProvider to retrieve widget data, locate an image file path, and set the image bitmap for the ImageView in your widget. Handles cases where the image file may not exist.

```kotlin
import es.antonborri.home_widget.HomeWidgetPlugin

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)
       }
   }
}

```

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

### Add ImageView to Android XML

Source: https://docs.page/ABausG/home_widget/android-xml/render-flutter-widget

Add an ImageView UI element to your XML layout file to display widget content. Ensure proper layout parameters and visibility are set.

```xml
<ImageView
       android:id="@+id/widget_image"
       android:layout_width="200dp"
       android:layout_height="200dp"
       android:layout_below="@+id/headline_description"
       android:layout_alignBottom="@+id/headline_title"
       android:layout_alignParentStart="true"
       android:layout_alignParentLeft="true"
       android:layout_marginStart="8dp"
       android:layout_marginLeft="8dp"
       android:layout_marginTop="6dp"
       android:layout_marginBottom="-134dp"
       android:layout_weight="1"
       android:adjustViewBounds="true"
       android:background="@android:color/white"
       android:scaleType="fitCenter"
       android:src="@android:drawable/star_big_on"
       android:visibility="visible"
       tools:visibility="visible" />

```

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

### Add Interactive Button to Widget

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Use the defined AppIntent within a SwiftUI Button to handle user interactions.

```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)
```

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

### Configure Android Glance State

Source: https://docs.page/ABausG/home_widget/usage/update-widget

Required override for Android Glance widgets to ensure proper state updates via HomeWidget.

```kotlin
override val stateDefinition: GlanceStateDefinition<*>?
  get() = HomeWidgetGlanceStateDefinition()
```

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

### Check if Pin Widget is Supported on Android

Source: https://docs.page/ABausG/home_widget/features/pin-widget

Checks if the current device supports the request to pin a widget to the HomeScreen. This is useful for conditional UI or feature availability.

```dart
HomeWidget.isRequestPinWidgetSupported();
```

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

### Register Interactivity Callback

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Register the background callback function to enable communication between the native widget and Flutter.

```dart
HomeWidget.registerInteractivityCallback(backgroundCallback);
```

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

### Adjust Widget Layout Based on Family

Source: https://docs.page/ABausG/home_widget/features/ios-lock-screen

Detect the current widget family to adjust the layout for different screen sizes, such as circular accessory widgets on iOS Lock Screens.

```swift
struct LockScreenWidgetView: View {
  var entry: Provider.Entry

  // Detect the current Family
  @Environment(\.widgetFamily) var family

  var body: some View {
    if family == .accessoryCircular {
      // Return Widget for Circular Lock Screen Widget
    } else {
     // Build Widget for other families
    }
  }
}


```

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

### Read Widget Data

Source: https://docs.page/ABausG/home_widget/usage/sync-data

Retrieve saved data using `getWidgetData`. Provide a default value to handle cases where no data is found.

```dart
HomeWidget.getWidgetData<String>('id', defaultValue: data);
```

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

### Add Clickable Modifier to View

Source: https://docs.page/ABausG/home_widget/features/interactive-widgets

Apply the action to a view using the GlanceModifier.clickable modifier.

```kotlin
Text(
     title,
     style = TextStyle(fontSize = 36.sp, fontWeight = FontWeight.Bold),
     modifier = GlanceModifier.clickable(onClick = actionRunCallback<InteractiveAction>()),
)
```

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

### Configure App Group ID

Source: https://docs.page/ABausG/home_widget/setup/ios

Initialize the App Group ID in the Flutter application to enable data sharing between the app and the widget extension.

```dart
HomeWidget.setAppGroupId('YOUR_GROUP_ID');
```

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

### Save Widget Data

Source: https://docs.page/ABausG/home_widget/usage/sync-data

Use `saveWidgetData` to store primitive data types. For binary payloads like JSON or images, use `saveFile` or `saveImage` and access the absolute file path.

```dart
HomeWidget.saveWidgetData<String>('id', data);
```

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

### Retrieve Image Path in iOS TimelineEntry

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Add a property to your `TimelineEntry` struct to store the file path of the rendered Flutter widget image.

```swift
struct MyEntry: TimelineEntry {
    …
    let lineChartPath: String
}

```

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

### Display Chart Image in iOS Widget Body

Source: https://docs.page/ABausG/home_widget/features/render-flutter-widgets

Include the `ChartImage` view within the body of your widget's `View` to display the rendered Flutter widget.

```swift
VStack {
        Text(entry.title)
        Text(entry.description)
        ChartImage
    }

```

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

### Register App Group in Flutter

Source: https://docs.page/ABausG/home_widget/features/configurable-widgets

Register the App Group ID in your Flutter application's main function using `HomeWidget.setAppGroupId`. This is required for data sharing between your Flutter app and the widget.

```dart
import 'package:home_widget/home_widget.dart';
void main() {
    WidgetFlutterBinding.ensureInitialized();
    HomeWidget.setAppGroupId('group.YOUR_APP_GROUP_ID');
    runApp(MyApp());
}
```
Tokens:
Raw