Flutter Floatwing은 순수한 Flutter를 사용하여 Android에서 플로팅 또는 오버레이 창을 생성하는 것을 간소화하도록 설계된 Flutter 플러그인입니다. 개발자들이 UI 요소를 다른 앱 위에 항상 보이도록 할 수 있는 플로팅 패널로 표시할 수 있게 해주며, 피처 인 피처 기능이나 지속적인 컨트롤에 적합합니다. 이 플러그인은 Flutter의 위젯 시스템과 원활하게 통합되며, 네이티브 Java/Kotlin 코드가 필요하지 않습니다. 음악 플레이어, 채팅 헤드, 생산성 도구와 같이 항상 보이는 인터페이스가 필요한 앱에 특히 유용합니다.
사용 사례
피처인피처 비디오 재생
지속적인 채팅 헤드
미디어 플레이어용 오버레이 컨트롤
항상 위에 표시되는 위젯
실시간 모니터링 대시보드
빠른 액세스 플로팅 도구
주요 기능
순수한 플러터 구현
기존 Flutter 앱과의 간편한 통합
Android 오버레이 권한 지원
최소한의 보일러플레이트 설정
사용자 정의 가능한 부유 창 크기 및 위치
내장형 라이프사이클 관리
적합한 대상
Android 오버레이 기능을 개발하는 개발자
지속적인 UI 요소가 필요한 앱
미디어 및 통신 앱
생산성 및 유틸리티 도구
Android 전용 오버레이가 있는 크로스플랫폼 앱
고려 사항
Android 오버레이 권한이 필요합니다(시스템 설정)
안드로이드 플랫폼에 제한됨
오버레이를 위해 사용자 권한 부여가 필요할 수 있습니다
복잡한 UI의 성능 영향
iOS와 호환되지 않습니다
권한 요청을 올바르게 처리해야 합니다
원본 README
연결된 소스 저장소의 README 원문 스냅샷입니다. 최신 내용은 저장소에서 확인하세요.
flutter_floatwing
A Flutter plugin that makes it easier to create floating/overlay windows for Android with pure Flutter. Android only
✨ Features
Feature
Description
🎨 Pure Flutter
Write your entire overlay window in pure Flutter
🚀 Simple
Start your overlay window with as little as 1 line of code
📐 Auto Resize
Just focus on your Flutter widget size — the Android view resizes automatically
🪟 Multi-window
Create multiple overlay windows with parent-child relationships
💬 Communicable
Main app and overlay windows can communicate seamlessly with each other
📡 Event Mechanism
Subscribe to window lifecycle events and drag actions for flexible control
More features are coming...
📸 Previews
Night Mode
Simple Example
Assistive Touch
📦 Installation
Add flutter_floatwing to your pubspec.yaml file:
dependencies:flutter_floatwing:^0.2.1
Then install it:
Terminal: Run flutter pub get
Android Studio/IntelliJ: Click "Packages get" in the action ribbon at the top of pubspec.yaml
VS Code: Click "Get Packages" on the right side of the action ribbon at the top of pubspec.yaml
Or simply run:
flutter pub add flutter_floatwing
🚀 Quick Start
Since we use Android's system alert window for display, you need to add the permission to AndroidManifest.xml first:
Add a route for the widget that will be displayed in the overlay window:
@overrideWidgetbuild(BuildContext context) {
returnMaterialApp(
debugShowCheckedModeBanner: false,
initialRoute: "/",
routes: {
"/": (_) => HomePage(),
// Add a route as the entry point for your overlay window"/my-overlay-window": (_) => MyOverlayWindow(),
},
);
}
Before starting the floating window, check and request permission, then initialize the flutter_floatwing plugin in initState or a button callback:
// Check and request the system alert window permissionFloatwingPlugin().checkPermission().then((granted) {
if (!granted) FloatwingPlugin().openPermissionSetting();
});
// Initialize the plugin firstFloatwingPlugin().initialize();
Now create and start your overlay window:
// Define window config and start the windowWindowConfig(route: "/my-overlay-window")
.to() // Create a window object
.create(start: true); // Create and start the overlay window
Notes:
route is one of 3 ways to define an entry point for the overlay window. See the Entry Point section for more details.
Before diving into how flutter_floatwing manages windows, here are some key concepts:
id is the unique identifier for each window. All operations on a window are based on this id — you must provide one before creating a window.
The first engine created when opening the main application is called the main engine (or plugin engine). Engines created by the service are called window engines.
Different engines run in different threads and cannot communicate directly.
You can subscribe to events from all windows in the main engine. In a window engine, you can subscribe to events from itself and its child windows, but not from sibling or parent windows.
share data is the only way to communicate between engines. The only restriction is that the data must be serializable — you can share data from anywhere to anywhere.
A floatwing window object consists of a Flutter engine that runs a widget via runApp and a view that is added to the Android window manager.
The overall view hierarchy looks like this:
📖 Usage
Here's how flutter_floatwing creates a new overlay window:
Start a background service as the window manager from the main app.
Send a create window request to the service.
In the service, start a Flutter engine with the specified entry point.
Create a new Flutter view and attach it to the Flutter engine.
Add the view to the Android window manager.
Window & Config
WindowConfig contains all configuration options for a window. You can create a window using configuration like this:
void_createWindow() {
var config = WindowConfig();
var w = Window(config, id: "my-window");
w.create();
}
If you don't need to register event or data handlers, you can create a window directly from the config:
The entry point determines where the engine starts execution. We support 3 configuration modes:
Name
Config
How to Use
route
WindowConfig(route: "/my-overlay")
Add a route for the overlay window in your main routes, then start with: WindowConfig(route: "/my-overlay")
static function
WindowConfig(callback: myOverlayMain)
Define a static void Function() that calls runApp to start a widget, then start with: WindowConfig(callback: myOverlayMain)
entry-point
WindowConfig(entry: "myOverlayMain")
Same as static function, but add @pragma("vm:entry-point") above the function and use the function name as a string: WindowConfig(entry: "myOverlayMain")
Example: Using route
Add a route for your overlay widget in the main application:
@overrideWidgetbuild(BuildContext context) {
returnMaterialApp(
debugShowCheckedModeBanner: false,
initialRoute: "/",
routes: {
"/": (_) => HomePage(),
// Add a route as the entry point for your overlay window"/my-overlay-window": (_) => MyOverlayWindow(),
},
);
}
voidmyOverlayMain() {
runApp(MaterialApp(
home: AssistivePanel(),
));
// Or use the floatwing helper to inject MaterialApp// runApp(AssistivePanel().floatwing(app: true));
}
Define a static function that calls runApp and add the pragma annotation:
@pragma("vm:entry-point")
voidmyOverlayMain() {
runApp(MaterialApp(
home: AssistivePanel(),
));
// Or use the floatwing helper to inject MaterialApp// runApp(AssistivePanel().floatwing(app: true));
}
You can wrap both Widget and WidgetBuilder. When wrapping a WidgetBuilder, you can access the window instance using Window.of(context). For wrapped Widget, use FloatwingPlugin().currentWindow instead.
To access the window via Window.of(context), use this pattern:
In your window engine, you can access the window object in two ways:
Directly access the plugin's cached field: FloatwingPlugin().currentWindow
If the widget is wrapped with .floatwing(), use Window.of(context)
FloatwingPlugin().currentWindow returns null until initialization is complete.
If you inject a WidgetBuilder with .floatwing(), you can access the current window. It will always return a non-null value, unless you enable debug mode with .floatwing(debug: true).
For example, to get the id of the current window:
import'package:flutter_floatwing/flutter_floatwing.dart';
class_ExampleViewStateextendsState<ExampleView> {
Window? w;
@overridevoidinitState() {
super.initState();
SchedulerBinding.instance?.addPostFrameCallback((_) {
w = Window.of(context);
print("My window ID is ${w?.id}");
});
}
}
Subscribing to Events
You can subscribe to window events and trigger actions when they fire. Window events are sent to the main engine, the window's own engine, and the parent window engine. This means you can subscribe to window events from the main application, the overlay window itself, or the parent overlay window.
Currently supported events include window lifecycle and drag actions:
More event types are coming — contributions are welcome!
For example, to perform an action when a window starts:
@overridevoidinitState() {
super.initState();
SchedulerBinding.instance?.addPostFrameCallback((_) {
w = Window.of(context);
w?.on(EventType.WindowStarted, (window, _) {
print("$w has started.");
}).on(EventType.WindowDestroy, (window, data) {
// data is a boolean indicating whether the window was force-closedprint("$w has been destroyed, force: $data");
});
});
}
Sharing Data with Windows
Sharing data is the only way to communicate with windows. Use window.share(data) for this purpose.
For example, to share data from the main application to an overlay window:
First, get the target window in the main application (either the one you created or from the windows cache by ID):
Window w;
void_startWindow() {
w = WindowConfig(route: "/my-overlay-window").to();
}
void_shareData(dynamic data) {
w.share(data).then((value) {
// The window can return a value
});
// Or get the window from cache// FloatwingPlugin().windows["default"]?.share(data);
}
To share data with a specific name, add the name parameter: w.share(data, name: "name-1").
Then register a data handler in the window to receive the data:
@overridevoidinitState() {
super.initState();
SchedulerBinding.instance?.addPostFrameCallback((_) {
w = Window.of(context);
w?.onData((source, name, data) async {
print("Received $name data from $source: $data");
});
});
}
The handler function signature is Future<dynamic> Function(String? source, String? name, dynamic data):
source: Where the data comes from. null if from the main application; otherwise, the id of the source window.
name: The data name, useful for sharing data for different purposes.
data: The actual data received.
Return a value if you want to respond.
You can send data to any window as long as you know its ID — the only restriction is that you cannot send data to yourself. Note: Sharing data to the main application is not yet implemented.
Important: The data you share must be serializable.
📚 API Reference
FloatwingPlugin
FloatwingPlugin()
// Permission
..checkPermission() // Check overlay permission → Future<bool>
..openPermissionSetting() // Open system settings → Future<bool>// Initialization
..initialize() // Initialize the plugin → Future<bool>// Service Management
..isServiceRunning() // Check if background service is running → Future<bool>
..startService() // Start the background service → Future<bool>
..syncWindows() // Sync windows from service → Future<bool>
..cleanCache() // Clean cached data → Future<bool>// Window Access
..currentWindow // Get current window (in overlay) → Window?
..windows // Map of all windows by ID → Map<String, Window>
..isWindow // Check if running in window engine → bool
FloatwingPlugin is a singleton class that returns the same instance every time you call the FloatwingPlugin() factory method.
WindowConfig
Complete configuration options for overlay windows:
Parameter
Type
Default
Description
id
String
"default"
Unique window identifier
entry
String
"main"
Entry point function name
route
String?
null
Flutter route for the window
callback
Function?
null
Static function to run (must be static)
width
int?
null
Window width in pixels
height
int?
null
Window height in pixels
x
int?
null
X position on screen
y
int?
null
Y position on screen
autosize
bool?
null
Auto-resize to fit content
gravity
GravityType?
null
Window position alignment
clickable
bool?
null
Allow click-through when false
draggable
bool?
null
Enable drag to move
focusable
bool?
null
Allow window to receive focus
immersion
bool?
null
Immersive status bar mode
visible
bool?
null
Initial visibility state
WindowSize Constants
WindowSize.MatchParent// -1: Fill entire screenWindowSize.WrapContent// -2: Fit to content size
GravityType Enum
GravityType.Center// Center of screenGravityType.CenterTop// Top centerGravityType.CenterBottom// Bottom centerGravityType.LeftTop// Top left cornerGravityType.LeftCenter// Left centerGravityType.LeftBottom// Bottom left cornerGravityType.RightTop// Top right cornerGravityType.RightCenter// Right centerGravityType.RightBottom// Bottom right corner
Example — Full-screen non-clickable overlay (night mode):
Did you find this plugin useful? Please consider making a donation to help improve it!
🔧 Troubleshooting
Release Mode Error: "No top-level getter declared"
If you see this error in release mode when using entry-point:
NoSuchMethodError: No top-level getter 'xxx' declared.
Could not resolve main entrypoint function.
Solution: Make sure your entry point function is:
Defined in main.dart or imported into main.dart
Marked with @pragma("vm:entry-point") to prevent tree-shaking
// In main.dart@pragma("vm:entry-point")
voidmyOverlayMain() {
runApp(MyOverlayWidget().floatwing(app: true));
}
If defined in another file, import it in main.dart:
// main.dartimport'package:myapp/overlay_entry.dart'; // Contains myOverlayMainvoidmain() {
runApp(MyApp());
}
// Re-export to ensure it's included in the buildexport'package:myapp/overlay_entry.dart';
Buttons Get Stuck Pressed When Dragging
If buttons inside a draggable overlay widget get stuck in pressed state when pressing and dragging simultaneously:
Workaround: Disable dragging while the button is pressed: