home_widget

The home_widget_generator package allows you to define a HomeScreen widget once using a Dart schema and automatically generates the corresponding native code for both iOS and Android. This eliminates the need to manually write SwiftUI (iOS) or Jetpack Glance (Android) code.

Key Relationships:

• It builds on top of the home_widget runtime package, which handles the actual data transmission and widget refreshing.
• It uses the home_widget_cli tool to discover annotated Dart classes and write the generated files into your Flutter project.
• You primarily interact with a generated Dart helper class in your application code, while the native sources are automatically placed in your ios/ and android/ folders.

When you annotate a Dart class with the generator, it produces three main components:

1. Typed Dart Helper: A class (e.g., MyWidgetHomeWidget) that provides a type-safe API for managing your widget data. It includes methods like:
   • saveData(...)
   • getData()
   • deleteData(...)
   • updateWidget()
2. iOS Widget Extension: A SwiftUI and WidgetKit implementation including TimelineProvider, TimelineEntry, and View, all configured to work with your App Group.
3. Android Widget: A Jetpack Glance implementation including GlanceAppWidget, GlanceAppWidgetReceiver, and the required appwidget-provider XML.

The HWWidget is the base class for all layout primitives used inside the @HomeWidget(widget: ...) annotation. These widgets are used to compose the UI structure and are translated into SwiftUI (iOS) or Jetpack Glance (Android) during the code generation process.

Layout widgets define how children are positioned and sized:

• HWColumn: Creates a vertical stack of children.
• HWRow: Creates a horizontal stack of children.
• HWPadding: Insets a child using HWEdgeInsets.
• HWFill: Forces a child to expand and fill all available space.

The home_widget_generator package allows you to describe a HomeScreen widget once in Dart using the @HomeWidget annotation and a set of DSL widgets (like HWColumn, HWText, etc.).

Instead of manually writing SwiftUI (iOS) and Jetpack Glance (Android) code, the generator produces the matching native widget code for you. The workflow consists of three parts:

1. Definition: Author an annotated Dart class using home_widget_generator primitives.
2. Generation: Use the home_widget_cli tool to generate the iOS, Android, and Dart helper sources.
3. Runtime Control: Use the home_widget package to drive the generated widget (e.g., saving data and updating the widget) from your Flutter app.

The HWAlignment enums are translated to native platform primitives during widget generation:

• iOS: Maps to SwiftUI HorizontalAlignment or VerticalAlignment. For space-distribution values (spaceBetween, spaceEvenly), Spacers are inserted to achieve the effect.
• Android: Maps to Glance Alignment.Horizontal or Alignment.Vertical on the Column or Row. For space-distribution values, Spacers are used.

The home_widget plugin provides a unified interface for sending, retrieving, and updating data for HomeScreen widgets on Android and iOS.

Important Limitation: home_widget does not allow you to write the actual widget UI using Flutter code. To create a widget, you must use one of two approaches:

1. Native Code: Write the widget UI using native Android (e.g., RemoteViews) and iOS (e.g., WidgetKit) code.
2. Dart-to-Native Generation: Describe your widget once in Dart using home_widget_generator and then use home_widget_cli to generate the necessary native source files.

Regardless of the UI implementation method, you use the home_widget package within your Flutter app to manage the data flow between your Flutter code and the native widgets.

The implementation of HWDecoratedBox varies by platform:

• iOS: Uses SwiftUI .background(_:) for the color and .overlay(_:) for the border.
• Android: Uses Glance Box with background(...) and a nested Box to approximate the border.

Important: Because Glance does not expose stroke alignment, borders on Android are emitted as an inside-border approximation.

You can use branching widgets to handle different platforms or runtime states:

• HWAdaptive: Allows you to select a different child widget depending on the target platform (iOS vs Android).
• HWConditional: Allows you to select a child widget based on a runtime data check.

HWAdaptive is a generator-time switch used to provide different widget trees for iOS and Android. It selects the ios subtree when generating SwiftUI code and the android subtree when generating Glance code. This is the recommended approach whenever the two platforms require meaningfully different layouts or components.

HWAdaptive(
  ios: HWText.fixed('Hello iOS'),
  android: HWText.fixed('Hello Android'),
)

The HWColor abstractions are resolved to native platform types during generation:

• iOS: Resolves to SwiftUI Color values (e.g., Color.primary, Color.accentColor).
• Android: Resolves to Glance ColorProvider and GlanceTheme.colors.

When the widget generator processes HWEdgeInsets, it maps the values to the following native platform APIs:

• iOS: Emitted as SwiftUI .padding(_:) with explicit edge insets.
• Android: Emitted as Glance GlanceModifier.padding(...) using dp units.