[Question] When I tried to integrate flutter_overlay_window into Flet, I packaged the project into an APK and tested this piece of code, but the overlay window failed to pop up. What could be the reason?

[yst-one]

Question

code

import 'dart:developer';
import 'dart:isolate';
import 'dart:ui';

import 'package:flet/flet.dart';
import 'package:flutter/material.dart';
import 'package:flutter_overlay_window/flutter_overlay_window.dart';

@pragma("vm:entry-point")
void overlayMain() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Text("Overlay Window Test"),
    ),
  );
}

class FletOverlayWindowControl extends StatefulWidget {
  final Control control;

  const FletOverlayWindowControl({
    super.key,
    required this.control,
  });

  @override
  State<FletOverlayWindowControl> createState() =>
      _FletOverlayWindowControlState();
}

class _FletOverlayWindowControlState extends State<FletOverlayWindowControl> {
  static const String _kPortNameOverlay = 'OVERLAY';
  static const String _kPortNameHome = 'UI';
  final _receivePort = ReceivePort();
  SendPort? homePort;
  String? latestMessageFromOverlay;

  @override
  void initState() {
    // TODO: implement initState
    super.initState();
    if (homePort != null) return;
    final res = IsolateNameServer.registerPortWithName(
      _receivePort.sendPort,
      _kPortNameHome,
    );
    log("$res: OVERLAY");
    _receivePort.listen((message) {
      log("message from OVERLAY: $message");
    });
  }

// 1. 检查悬浮窗权限
  Future<bool> isPermissionGranted() async {
    return await FlutterOverlayWindow.isPermissionGranted();
  }

// 2. 请求悬浮窗权限
  Future<bool?> requestPermission() async {
    return await FlutterOverlayWindow.requestPermission();
  }

// 3. 显示悬浮窗
  Future<void> showOverlay({
    bool enableDrag = true,
    String overlayTitle = "",
    String overlayContent = "",
    OverlayFlag flag = OverlayFlag.defaultFlag,
    NotificationVisibility visibility = NotificationVisibility.visibilityPublic,
    PositionGravity positionGravity = PositionGravity.auto,
    int height = 0,
    int width = 0,
    OverlayPosition startPosition = const OverlayPosition(0, -259),
  }) async {
    await FlutterOverlayWindow.showOverlay(
      enableDrag: enableDrag,
      overlayTitle: overlayTitle,
      overlayContent: overlayContent,
      flag: flag,
      visibility: visibility,
      positionGravity: positionGravity,
      height: height,
      width: width,
      startPosition: startPosition,
    );
  }

// 4. 检查悬浮窗是否激活
  Future<bool> isActive() async {
    return await FlutterOverlayWindow.isActive();
  }

// 5. 调整悬浮窗大小
  Future<bool?> resizeOverlay(int width, int height, bool enableDrag) async {
    return await FlutterOverlayWindow.resizeOverlay(
      width,
      height,
      enableDrag,
    );
  }

// 6. 向悬浮窗发送消息
  void sendMessageToOverlay(String message) {
    homePort ??= IsolateNameServer.lookupPortByName(_kPortNameOverlay);
    homePort?.send('$message');
  }

// 2. 获取悬浮窗坐标
  Future<OverlayPosition> getOverlayPosition() {
    return FlutterOverlayWindow.getOverlayPosition();
  }

// 3. 移动悬浮窗到指定位置
  Future<bool?> moveOverlay(OverlayPosition position) async {
    return await FlutterOverlayWindow.moveOverlay(position);
  }

// 4. 关闭悬浮窗
  Future<bool?> closeOverlay() async {
    return await FlutterOverlayWindow.closeOverlay();
  }

  @override
  Widget build(BuildContext context) {
    overlayMain();
    requestPermission();
    showOverlay(
        width: 300,
        height: 200,
        overlayTitle: "Overlay Window",
        overlayContent: "This is an overlay window");

    String text = widget.control.getString("value", "")!;
    Widget myControl = Text(text);

    return LayoutControl(control: widget.control, child: myControl);
  }
}

Code sample

No response

Error message

No response

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

• I have searched for answers to my question both in the issues and in previous discussions.

[yst-one]

@pragma("vm:entry-point")
void overlayMain() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(
    MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Text("Overlay Window Test"),
    ),
  );
}

排查下来，这段代码必须放到 main.dart 中才能生效，那我要怎么做才能封装成这个扩展呢？

[RenSolvyn]

简短回答：你的排查是对的。overlayMain 必须在 main.dart 里，因为插件是按函数名在应用根库里查找入口点的。下面给出两种封装路线：本地模板目录（最简单、版本安全）或 fork 模板仓库，另外还有一个最小改动的变体。

Your diagnosis is correct, and here is the mechanism behind it. The overlay runs in a second FlutterEngine, and the plugin creates that engine with an entrypoint built like this (in onAttachedToActivity, source, with the same construction repeated as a fallback in OverlayService):

DartExecutor.DartEntrypoint(
    FlutterInjector.instance().flutterLoader().findAppBundlePath(),
    "overlayMain")

An entrypoint given only by function name is resolved in the root library of the app bundle, which is lib/main.dart. A @pragma("vm:entry-point") function inside an extension package library is invisible to that lookup, which is exactly why moving it into main.dart made it work. Note the engine is pre-created at activity attach, so with the entrypoint missing the failure happens silently at app launch (an error in logcat only), which is why you saw no crash, just no overlay.

Two bugs in the posted control worth fixing at the same time:

1. Never call overlayMain() yourself. The plugin invokes it inside the second engine. Calling it in build() runs runApp() a second time inside the main engine and replaces your Flet UI.
2. Do not fire requestPermission() and showOverlay() from build(). build runs many times, and showOverlay races the permission grant, which is a Settings round trip that cannot complete inside the same build pass. Expose them as methods on your control, trigger them from Python, and await the permission before showing.

To package it as a reusable extension when main.dart is generated, keep the real entrypoint in your extension and give the build template a three line trampoline. In your extension package (use your extension's actual package name throughout):

// lib/flet_overlay_window.dart
@pragma("vm:entry-point")
void overlayEntrypoint() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(MaterialApp(
    debugShowCheckedModeBanner: false,
    home: Text("Overlay Window Test"),
  ));
}

There are two routes to get the trampoline into the generated main.dart. Route 1 is simpler and version safe.

Route 1: local template directory. Without --template, the CLI does not read the template repo at all. It downloads a frozen snapshot from the Flet release matching your installed version. Start from that exact snapshot so nothing can mismatch:

pip show flet | grep Version
curl -LO https://github.com/flet-dev/flet/releases/download/v<your-version>/flet-build-template.zip
unzip flet-build-template.zip -d ~/flet-template

The zip unpacks to a build/ folder containing cookiecutter.json. Make the two edits below inside ~/flet-template/build/, then:

flet build apk --template ~/flet-template/build

Route 2: forked repo (better for a team or CI). Fork flet-build-template, make the two edits on a branch, and build with flet build apk --template https://github.com/<you>/flet-build-template.git --template-ref <your-branch> (or set the same under [tool.flet.template] in pyproject.toml). One caution: the repo layout on main can be ahead of your installed CLI (the release zip for a given version is the ground truth), so if the build fails on unexpected template variables, replace your branch contents with the build/ folder from your version's zip and reapply the edits.

The two edits, in whichever template copy you chose:

In {{cookiecutter.out_dir}}/lib/main.dart, near the other imports:

import 'package:flet_overlay_window/flet_overlay_window.dart' as fow;

@pragma("vm:entry-point")
void overlayMain() => fow.overlayEntrypoint();

In {{cookiecutter.out_dir}}/android/app/src/main/AndroidManifest.xml: the plugin's own manifest already merges SYSTEM_ALERT_WINDOW and FOREGROUND_SERVICE for you, but it does not declare the service, so add inside <application>:

<service
    android:name="flutter.overlay.window.flutter_overlay_window.OverlayService"
    android:exported="false"
    android:foregroundServiceType="specialUse">
    <property
        android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
        android:value="app overlay window" />
</service>

and next to the existing uses-permission entry:

<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />

Minimal variant while validating: instead of the trampoline, paste your exact proven overlayMain body directly into the template's main.dart. That is byte for byte the configuration you already showed working; the trampoline indirection only exists to keep overlay UI code inside your extension package.

Runtime order from Python: call your control's request permission method and await it (the user flips the "Display over other apps" toggle in Settings), then call show.

If it still does not appear, adb logcat | grep -iE "overlay|entrypoint" separates the remaining cases: a Dart entrypoint error at app launch mentioning overlayMain means the trampoline did not reach the built main.dart; no OverlayService lines at all when you call show means the service declaration did not reach the built manifest; the service starting cleanly with nothing visible means the permission was not actually granted before showOverlay ran.

[yst-one]

Hi there, I’ve hit another roadblock, haha. I’m trying to pass a Flet widget into a plugin so it can be rendered as a floating window. Do you have any ideas on how to approach this?

import 'dart:developer';
import 'dart:isolate';
import 'dart:ui';

import 'package:flet/flet.dart';
import 'package:flet_overlay_window/src/utils.dart';
import 'package:flutter/material.dart';
import 'package:flutter_overlay_window/flutter_overlay_window.dart';


class FletOverlayContainer extends StatelessWidget {
  Widget? content; 
  const FletOverlayContainer({super.key,});


  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        body: content,
      ),
    );
  }
}






@pragma("vm:entry-point")
void overlayEntrypoint() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(MaterialApp(
    debugShowCheckedModeBanner: false,
    home: FletOverlayContainer(),
  ));
}

class FletOverlayWindowControl extends StatefulWidget {
  final Control control;

  const FletOverlayWindowControl({
    super.key,
    required this.control,
  });

  @override
  State<FletOverlayWindowControl> createState() =>
      _FletOverlayWindowControlState();
}

class _FletOverlayWindowControlState extends State<FletOverlayWindowControl> {
  static const String _kPortNameOverlay = 'OVERLAY';
  static const String _kPortNameHome = 'UI';
  final _receivePort = ReceivePort();
  SendPort? homePort;
  String? latestMessageFromOverlay;

  @override
  void initState() {
    // TODO: implement initState
    super.initState();

    widget.control.addInvokeMethodListener(_invokeMethod);

    if (homePort != null) return;
    final res = IsolateNameServer.registerPortWithName(
      _receivePort.sendPort,
      _kPortNameHome,
    );
    log("$res: OVERLAY");
    _receivePort.listen((message) {
      log("message from OVERLAY: $message");
    });
  }

// 1. 检查悬浮窗权限
  Future<bool> isPermissionGranted() async {
    return await FlutterOverlayWindow.isPermissionGranted();
  }

// 2. 请求悬浮窗权限
  Future<bool?> requestPermission() async {
    return await FlutterOverlayWindow.requestPermission();
  }

// 3. 显示悬浮窗
  Future<void> showOverlay({
    bool enableDrag = true,
    String overlayTitle = "",
    String overlayContent = "",
    OverlayFlag flag = OverlayFlag.defaultFlag,
    NotificationVisibility visibility = NotificationVisibility.visibilityPublic,
    PositionGravity positionGravity = PositionGravity.auto,
    int height = 0,
    int width = 0,
    OverlayPosition startPosition = const OverlayPosition(0, -259),
  }) async {
    await FlutterOverlayWindow.showOverlay(
      enableDrag: enableDrag,
      overlayTitle: overlayTitle,
      overlayContent: overlayContent,
      flag: flag,
      visibility: visibility,
      positionGravity: positionGravity,
      height: height,
      width: width,
      startPosition: startPosition,
    );
  }

// 4. 检查悬浮窗是否激活
  Future<bool> isActive() async {
    return await FlutterOverlayWindow.isActive();
  }

// 5. 调整悬浮窗大小
  Future<bool?> resizeOverlay(int width, int height, bool enableDrag) async {
    return await FlutterOverlayWindow.resizeOverlay(
      width,
      height,
      enableDrag,
    );
  }

// 6. 向悬浮窗发送消息
  void sendMessageToOverlay(String message) {
    homePort ??= IsolateNameServer.lookupPortByName(_kPortNameOverlay);
    homePort?.send('$message');
  }

// 7. 获取悬浮窗坐标
  Future<OverlayPosition> getOverlayPosition() {
    return FlutterOverlayWindow.getOverlayPosition();
  }

// 8. 移动悬浮窗到指定位置
  Future<bool?> moveOverlay(OverlayPosition position) async {
    return await FlutterOverlayWindow.moveOverlay(position);
  }

// 9. 关闭悬浮窗
  Future<bool?> closeOverlay() async {
    return await FlutterOverlayWindow.closeOverlay();
  }

  Future<dynamic> _invokeMethod(String name, dynamic args) async {
    debugPrint("Camera.$name($args)");
    switch (name) {
      case "is_permission_granted":
        return await isPermissionGranted();
      case "request_permission":
        return await requestPermission();
      case "show_overlay":
        return await showOverlay(
            enableDrag: parseBool(args["enableDrag"]) ?? true,
            overlayTitle: args["overlayTitle"] as String,
            overlayContent: args["overlayContent"] as String,
            flag: parseOverlayFlag(args["flag"], OverlayFlag.defaultFlag) ??
                OverlayFlag.defaultFlag,
            visibility: parseNotificationVisibility(args["visibility"],
                    NotificationVisibility.visibilityPublic) ??
                NotificationVisibility.visibilityPublic,
            positionGravity: parsePositionGravity(
                    args["positionGravity"], PositionGravity.auto) ??
                PositionGravity.auto,
            height: parseInt(args["height"], 0) ?? 0,
            width: parseInt(args["width"], 0) ?? 0,
            startPosition: parseOverlayPosition(args["startPosition"]) ??
                const OverlayPosition(0, -259));
      case "is_active":
        return await isActive();
      case "resize_overlay":
        return await resizeOverlay(
            parseInt(args["width"], 0) ?? 0,
            parseInt(args["height"], 0) ?? 0,
            parseBool(args["enableDrag"], true) ?? true);
      case "send_message_to_overlay":
        sendMessageToOverlay(args["message"] ?? "");
        return null;
      case "get_overlay_position":
        return await getOverlayPosition();
      case "move_overlay":
        return await moveOverlay(parseOverlayPosition(args["position"]) ??
            const OverlayPosition(0, -259));
      case "close_overlay":
        return await closeOverlay();
      default:
        throw Exception("Method not found: $name");
    }
  }

  @override
  Widget build(BuildContext context) {
    String text = widget.control.getString("value", "")!;
    Widget myControl = Text(text);

    return LayoutControl(control: widget.control, child: myControl);
  }
}

[RenSolvyn]

Hey, this one is an architectural wall rather than a bug in your logic, so let me lay out what is blocking it and the pattern that does work.

Short version: you cannot pass a Widget into the overlay, and it is not an API gap. It is the isolate boundary.

flutter_overlay_window runs the overlay in a separate Dart isolate. That is what the @pragma("vm:entry-point") on overlayEntrypoint sets up. Separate isolate means separate heap, separate engine, separate widget tree, so it is effectively a second app. Isolates can only exchange serializable data: numbers, strings, lists, maps. A Widget holds references to elements, render objects, BuildContext, and closures bound to the originating isolate's heap, so there is no way to send one across. That is why the plugin ships with IsolateNameServer and SendPort in the first place.

The pattern that does work is the same one Flet itself uses across the Python and Dart boundary: do not send the widget, send a description of it and build the widget on the far side. Python does not hand Dart a widget, it hands over a serialized control tree that Dart materializes. Do the same thing one layer down. The main isolate sends JSON describing what to render, and the overlay isolate constructs real widgets from it.

That means overlayEntrypoint needs to run a stateful widget that registers a port, listens, and rebuilds from incoming descriptors:

@pragma("vm:entry-point")
void overlayEntrypoint() {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MaterialApp(
    debugShowCheckedModeBanner: false,
    home: FletOverlayContainer(),
  ));
}

class FletOverlayContainer extends StatefulWidget {
  const FletOverlayContainer({super.key});

  @override
  State<FletOverlayContainer> createState() => _FletOverlayContainerState();
}

class _FletOverlayContainerState extends State<FletOverlayContainer> {
  static const String _kPortNameOverlay = 'OVERLAY';
  final _receivePort = ReceivePort();
  Map<String, dynamic>? _descriptor;

  @override
  void initState() {
    super.initState();
    // register under 'OVERLAY' so the main isolate can find us
    IsolateNameServer.removePortNameMapping(_kPortNameOverlay);
    IsolateNameServer.registerPortWithName(
      _receivePort.sendPort,
      _kPortNameOverlay,
    );
    _receivePort.listen((message) {
      setState(() => _descriptor = jsonDecode(message as String));
    });
  }

  @override
  void dispose() {
    IsolateNameServer.removePortNameMapping(_kPortNameOverlay);
    _receivePort.close();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      debugShowCheckedModeBanner: false,
      home: Scaffold(
        backgroundColor: Colors.transparent,
        body: _buildFromDescriptor(_descriptor),
      ),
    );
  }

  Widget _buildFromDescriptor(Map<String, dynamic>? d) {
    if (d == null) return const SizedBox.shrink();
    switch (d["type"]) {
      case "text":
        return Center(child: Text(d["value"] ?? ""));
      // extend with the control types you want to support
      default:
        return const SizedBox.shrink();
    }
  }
}

There are also three concrete bugs in the current code, separate from the architecture:

1. content is never assigned. Widget? content; is declared but the const constructor does not accept it and nothing sets it, so Scaffold(body: content) is always body: null. Even if the overlay pops up, it is blank. Worth noting too that a mutable non-final field on a StatelessWidget with a const constructor is contradictory, which is a signal that the ownership of content has not been settled yet.

2. The 'OVERLAY' port is never registered. sendMessageToOverlay calls lookupPortByName(_kPortNameOverlay), but nothing registers a port under 'OVERLAY'. The main side registers 'UI' (_kPortNameHome). So homePort stays null and every message is silently dropped. Registration has to happen inside the overlay isolate, as in the snippet above.

3. height: 0, width: 0 may produce an invisible overlay. The plugin's "fill the parent" sentinel is WindowSize.matchParent (-1), not 0. A zero sized overlay can be created successfully and simply never be visible, which is indistinguishable from "it did not pop up." Worth passing explicit dimensions while debugging.

For the original symptom where nothing appeared in the packaged APK, two things are worth confirming on the release build:

• SYSTEM_ALERT_WINDOW is actually granted. It is a special settings screen permission, not a normal runtime one, and the manifest entries need to survive Flet's build.
• The vm:entry-point was not tree shaken in release mode. If the entry point gets stripped, the overlay has nothing to run.

adb logcat while calling showOverlay() will tell you which of these it is within seconds, and that is the fastest way to separate a permission problem from a missing entry point from a blank render.

Happy to dig in further once you have logcat output from the release APK, since that usually names the failure directly.

[RenSolvyn]

By the way, if you have further issues, if you can just open a separate discussion post that would be awesome so the answer and resolution get adjucated correctly.

[yst-one]

Okay, thank you so much! Your explanation is really thorough! To sum up, what you mean is that I can only send data describing the component structure in the form of text or dictionary, and then the Dart‑side receives it and renders the layout components internally in Dart, right?

[RenSolvyn]

Yes, that is it, with one qualification worth stating precisely.

What crosses the boundary is data only: numbers, strings, bools, lists, and maps of those. So the descriptor has to bottom out in those types, which in practice means JSON. Encode on the main isolate, decode in the overlay isolate.

What does not cross is the widget vocabulary. The overlay isolate can only build control types you have written a builder for, at compile time, inside _buildFromDescriptor. The descriptor selects among widgets that already exist in the overlay's code; it cannot introduce new ones. That is the same contract Flet has with Python: the control tree names controls that the Dart side already knows how to build. Adding a new control type to the overlay means adding a case, not sending a richer payload.

Minimal working loop:

Overlay isolate registers a ReceivePort under 'OVERLAY' in initState. Nothing registers it today, which is why every send is dropped.
Main isolate does lookupPortByName('OVERLAY') and sends a JSON string.
Overlay decodes it and calls setState.
_buildFromDescriptor switches on type and returns a real widget.

Three fixes independent of that:

Drop Widget? content entirely. It is never assigned, and a mutable field on a StatelessWidget with a const constructor cannot be.
Use WindowSize.matchParent (-1) rather than 0 for height and width, or explicit pixel values while debugging.
On the release APK, confirm SYSTEM_ALERT_WINDOW is granted and the vm:entry-point survived tree shaking.

If it still does not appear once the port is registered, adb logcat during showOverlay() will name which of those two release issues it is.