Quick Start

This guide takes you from a blank Flutter project to a working Android home screen widget. Estimated time: 5 minutes.

Step 1: Install

# pubspec.yaml
dependencies:
  flutter_android_widgets: ^0.0.1
dev_dependencies:
  build_runner: ^2.4.0

flutter pub get

Step 2: Add manifest markers

In android/app/src/main/AndroidManifest.xml, add inside <application>:

<!-- flutter_android_widgets:start -->
<!-- flutter_android_widgets:end -->

Create lib/my_widgets.dart:

import 'package:flutter_android_widgets/flutter_android_widgets.dart';

final myWidget = AndroidWidget(
  info: WidgetInfo(
    widgetClassName: 'MyWidgetProvider',
    widgetName: 'My Widget',
    minWidth: 250,
    minHeight: 100,
    updateInterval: Duration(hours: 1),
  ),
  layout: WColumn(
    backgroundColor: '#1A1A2E',
    padding: 16,
    children: [
      WText('\${score}', textSize: 32, bold: true, textColor: '#FFFFFF'),
      WText('\${label}', textSize: 14, textColor: '#AAAAAA'),
      WButton(label: 'Refresh', actionKey: 'refresh'),
    ],
  ),
  dataKeys: ['score', 'label'],
);

Step 4: Wire up live updates in `main()`

import 'package:flutter/material.dart';
import 'package:flutter_android_widgets/flutter_android_widgets.dart';
import 'my_widgets.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  WidgetUpdater.initialize(widgets: [myWidget]); // sync styles on hot restart
  HomeWidgetData.autoUpdate = true;              // auto-refresh after every save
  runApp(const MyApp());
}

Step 5: Push data from Flutter

await HomeWidgetData.saveAll({
  'score': '1,247',
  'label': 'Active users today',
});
// Widget refreshes automatically because autoUpdate = true

Step 6: Generate and run

dart run build_runner build
flutter run

Add the widget to your home screen: long-press → Widgets → My Widget.

What you just built

Flutter app  ──save('score', '1,247')──▶  SharedPreferences
                                                   │
                                      Android widget reads on update
                                                   │
                                          Shows "1,247" on screen

Every time your Flutter app calls HomeWidgetData.saveAll(), the widget refreshes with the new values.

Next steps

Live Updates — understand hot restart, app resume, and auto-refresh triggers
Layout Reference — explore all layout nodes (WColumn, WText, WImage, etc.)
Data Binding — advanced \${key} template patterns
API Reference — full API for AndroidWidget, HomeWidgetData, WidgetUpdater