Flutter Overlay Window Plus #

A Flutter plugin for displaying a single, robust overlay window over other apps with enhanced features and better API.

Features #

• ✅ Display a single instance of an overlay window over other apps (prevents multiple overlays)
• ✅ Draggable overlays with position gravity
• ✅ Customizable size and position
• ✅ Live data streaming to the overlay from your main app
• ✅ Minimize app to background and re-launch on overlay close
• ✅ Permission management
• ✅ Event streaming for overlay state changes
• ✅ Better error handling and API design

Installation #

Add the package to your pubspec.yaml:

dependencies:
  flutter_overlay_window_plus: ^1.0.0

Android Setup #

1. Add Permissions #

Add the following permissions to your android/app/src/main/AndroidManifest.xml:

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

2. Add Service #

Add the overlay service to your android/app/src/main/AndroidManifest.xml inside the <application> tag:

<service 
  android:name="com.example.flutter_overlay_window_plus.OverlayService" 
  android:exported="false"
  android:foregroundServiceType="specialUse">
  <property 
    android:name="android.app.PROPERTY_SPECIAL_USE_FGS_SUBTYPE"
    android:value="overlay_window_service" />
</service>

3. Entry Point #

Create an entry point for your overlay widget in your main.dart:

// overlay entry point
@pragma("vm:entry-point")
void overlayMain() {
  runApp(const MaterialApp(
    debugShowCheckedModeBanner: false,
    home: Material(child: Text("My overlay"))
  ));
}

Usage #

Basic Usage #

import 'package:flutter_overlay_window_plus/flutter_overlay_window_plus.dart';

// Check permission
final bool hasPermission = await FlutterOverlayWindowPlus.isPermissionGranted();

// Request permission
final bool granted = await FlutterOverlayWindowPlus.requestPermission();

// Show overlay
final bool success = await FlutterOverlayWindowPlus.showOverlay(
  height: 200,
  width: 300,
  alignment: OverlayAlignment.center,
  overlayTitle: "My Overlay",
  overlayContent: "This is my overlay content",
  enableDrag: true,
);

Advanced Usage #

// Show small draggable overlay
await FlutterOverlayWindowPlus.showOverlay(
  height: 100,
  width: 150,
  alignment: OverlayAlignment.topRight,
  flag: OverlayFlag.defaultFlag,
  overlayTitle: "Small Overlay",
  enableDrag: true,
  positionGravity: PositionGravity.right,
);

// Close overlay
await FlutterOverlayWindowPlus.closeOverlay();

// Share data with overlay (can be used for live streaming)
// In the overlay service, the text will be updated dynamically
await FlutterOverlayWindowPlus.shareData("Live update text: ${DateTime.now()}");

// Minimize the app to the background
await FlutterOverlayWindowPlus.minimizeApp();

// Get overlay position
final position = await FlutterOverlayWindowPlus.getOverlayPosition();

Listening to Events #

// Listen to overlay events
FlutterOverlayWindowPlus.overlayListener.listen((event) {
  print('Event: ${event['event']}');
  
  switch (event['event']) {
    case 'overlay_shown':
      print('Overlay is now visible');
      break;
    case 'overlay_moved':
      print('Overlay moved to: ${event['x']}, ${event['y']}');
      break;
    case 'overlay_closed':
      print('Overlay was closed');
      break;
  }
});

API Reference #

Window Size Constants #

class WindowSize {
  static const int matchParent = -1;    // Match parent width/height
  static const int wrapContent = -2;    // Wrap content
  static const int fullCover = -3;      // Full screen cover
}

Overlay Alignment #

enum OverlayAlignment {
  center,      // Center of screen
  top,         // Top of screen
  bottom,      // Bottom of screen
  left,        // Left of screen
  right,       // Right of screen
  topLeft,     // Top left corner
  topRight,    // Top right corner
  bottomLeft,  // Bottom left corner
  bottomRight, // Bottom right corner
}

Overlay Flags #

enum OverlayFlag {
  defaultFlag,   // Default window flag (won't get key input focus)
  focusPointer,  // Allow pointer events outside window
}

Position Gravity #

enum PositionGravity {
  none,  // Allow overlay to be positioned anywhere
  right, // Stick to right side of screen
  left,  // Stick to left side of screen
  auto,  // Auto-stick to left or right side
}

Notification Visibility #

enum NotificationVisibility {
  visibilityPublic,   // Show notification on lock screen
  visibilitySecret,   // Hide notification on lock screen
  visibilityPrivate,  // Show notification but hide sensitive content
}

Methods #

Permission Management #

• isPermissionGranted() - Check if overlay permission is granted
• requestPermission() - Request overlay permission

Overlay Control #

• showOverlay() - Show overlay window with various options
• closeOverlay() - Close overlay if open
• resizeOverlay(width, height) - Resize overlay
• moveOverlay(position) - Move overlay to new position
• getOverlayPosition() - Get current overlay position

Communication #

• shareData(data) - Share data between overlay and main app
• updateFlag(flag) - Update overlay flag while active
• overlayListener - Stream for listening to overlay events

App Control #

• minimizeApp() - Minimize the host application to the background.

Example #

See the example/ directory for a complete working example demonstrating all features, including live text streaming.

Limitations #

• Only supports Android (iOS has strict limitations on overlay windows)
• Requires SYSTEM_ALERT_WINDOW permission
• Overlay content is currently rendered as a native Android view (TextView). Custom Flutter widgets in the overlay are not directly supported by this architecture, but the displayed text can be updated live from Flutter.

Contributing #

Contributions are welcome! Please feel free to submit a Pull Request.

License #

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments #

This package is inspired by flutter_overlay_window but with improved API design and additional features.