flutter_overlay_window_engine 0.1.0
This package aims to allow developers to create multiple overlay windows using dart code & without needing to write android code.
Flutter Overlay Window Engine
A Flutter package to create overlay windows at runtime on Android.
Table of Contents
Showcase
Warning
This package is still under development and might lead to crashes/memory leaks. Any kind of help is appreciated.
Installation
Requirements
Overlay Permission
Until API version 26
The engine doesn't require any additional permissions.
After API version 26
SYSTEM_ALERT_WINDOW permission required.
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>
Background service
For APPLICATION overlay windows
The engine requires a background service to create/manage views. Add
<service
android:name="me.orbitium.flutter_overlay_window_engine.service.application.ApplicationOverlayService">
</service>
to AndroidManifest.xml.
For ACCESSIBILITY overlay windows
The engine requires an accessibility service to create/manage views. Add
<service android:name="me.orbitium.flutter_overlay_window_engine.service.accessibility.AccessibilityOverlayService"
android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE"
android:exported="false">
<intent-filter>
<action android:name="android.accessibilityservice.AccessibilityService" />
</intent-filter>
</service>
to AndroidManifest.xml.
Usage
Create/Activate an overlay window
- Initialize the Overlay Engine by
FlutterOverlayWindowEngine.initialize();. - You need to create a dart entry point first. In main.dart, create a function with
@pragma("vm:entry-point"). - Create an
OverlayWindowentity, then useFlutterOverlayWindowEngine.instance.createAndCacheOverlayWindow(callerExample);. This will create and cache your overlay window entity. - Activate the cached overlay window by using
await FlutterOverlayWindowEngine.instance.activateOverlayWindow(...).
Caching overlay windows will allocate memory; caching multiple overlay windows is not recommended. Overlay windows can be created/activated at runtime.
Delete/Deactivate an overlay window
- Use
await FlutterOverlayWindowEngine.instance.deactivateOverlayWindow(...)if the window is activated and currently on display. - After deactivating the window, you can delete the window by
FlutterOverlayWindowEngine.instance.deleteCachedOverlayWindow(...).
Deleting overlay windows will free allocated memory.
Features
- Create/Cache/Activate/Deactivate/Delete multiple overlay windows at runtime.
- Draggable overlay windows.
- Optional transparent windows. Non-transparent windows are more efficient than transparent ones.
- Click through overlay windows, meaning the user can click a widget under overlay windows.
- Use Flutter code to create overlay windows without needing XML knowledge.
Planned
- Allow overlay windows to be resizable. Currently, overlay windows will keep their size after being created.
- Allow overlay windows to be re-positioned programmatically. Currently, it's not possible to re-position overlay windows.
- Overlay window events such as
onActivated(),onDeactivated(),onDragged()etc. - Current position variable in overlay windows; currently, it's not possible to know the overlay window's location if it's draggable. Note: it's possible to get the current position of overlay windows on the Android side.
- Service events such as
onServiceStarted(),onServiceStopped()etc. - Foreground/Stick/Non-sticky services.
- Notifications.
- Better stabilization; currently, the engine can't handle heavy loads or wrong use cases.
- Better error-handling. Currently, the engine does not respond as well as expected; you can't really know if the engine is doing its thing in the background.
Known issues
- Minor memory leaks. Due to some runtime exceptions thrown by the Dart VM, the engine can leak some memory over time.
- Ghost overlay windows that crash the app on touch.
- Crashes on wrong use cases such as trying to delete an overlay window without detaching it from the service.