{"id":34780768,"url":"https://github.com/maojiu-bb/floating_window_android","last_synced_at":"2026-05-01T22:33:02.173Z","repository":{"id":288059321,"uuid":"966695959","full_name":"maojiu-bb/floating_window_android","owner":"maojiu-bb","description":"A Flutter plugin for Android floating windows, providing an easy-to-use and feature-rich floating window solution.","archived":false,"fork":false,"pushed_at":"2025-10-18T07:16:52.000Z","size":1972,"stargazers_count":1,"open_issues_count":2,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-19T04:46:29.508Z","etag":null,"topics":["android","dart","floating-window","flutter","kotlin","plugin"],"latest_commit_sha":null,"homepage":"https://pub.dev/packages/floating_window_android","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maojiu-bb.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-15T10:10:49.000Z","updated_at":"2025-10-18T07:16:56.000Z","dependencies_parsed_at":"2025-04-15T11:26:30.851Z","dependency_job_id":"2d6a342d-0c93-4859-af07-925ad839983a","html_url":"https://github.com/maojiu-bb/floating_window_android","commit_stats":null,"previous_names":["maojiu-bb/floating_window_android"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/maojiu-bb/floating_window_android","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maojiu-bb%2Ffloating_window_android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maojiu-bb%2Ffloating_window_android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maojiu-bb%2Ffloating_window_android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maojiu-bb%2Ffloating_window_android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maojiu-bb","download_url":"https://codeload.github.com/maojiu-bb/floating_window_android/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maojiu-bb%2Ffloating_window_android/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32515838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","dart","floating-window","flutter","kotlin","plugin"],"created_at":"2025-12-25T08:55:14.522Z","updated_at":"2026-05-01T22:33:02.153Z","avatar_url":"https://github.com/maojiu-bb.png","language":"Dart","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Floating Window Android\n\nA Flutter plugin for Android floating windows, providing an easy-to-use and feature-rich floating window solution.\n\n[![Pub](https://img.shields.io/pub/v/floating_window_android.svg)](https://pub.dev/packages/floating_window_android)\n[![Platform](https://img.shields.io/badge/Platform-Android-green.svg)](https://pub.dev/packages/floating_window_android)\n\n## Screenshots\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"screenshots/Screenshot1.png\" width=\"300\" alt=\"Main App Interface\"/\u003e\n  \u003cimg src=\"screenshots/Screenshot2.png\" width=\"300\" alt=\"Floating Window in Action\"/\u003e\n\u003c/p\u003e\n\n_Left: Main app interface with GitHub events selection. Right: Floating window displaying selected events with draggable functionality._\n\n## Features\n\n- 💪 Display independent Flutter UI in a floating window, running separately from the main app.\n- 🔄 Support bidirectional communication and data sharing between floating window and main app.\n- 🎯 Customize floating window size, position, and alignment.\n- 👆 Support dragging with edge snapping effects.\n- 🚥 Multiple interaction modes (click-through, default mode, focus pointer mode).\n- 🛎️ Fully customizable notification style and visibility.\n- 🔄 Dynamically adjust floating window properties at runtime.\n- ⚡ **Automatic engine caching for instant startup**. The engine is prepared when your app starts, ensuring the overlay appears instantly.\n\n## Installation\n\nAdd the dependency to your `pubspec.yaml` file:\n\n```yaml\ndependencies:\n  floating_window_android: ^1.1.2 # Or the latest version\n```\n\n## Required Permissions\n\nThis plugin requires the `SYSTEM_ALERT_WINDOW` permission to display floating windows. On Android 6.0 (API 23) and above, users need to manually grant this permission. The plugin provides APIs for permission requests and checks.\n\nEnsure you add the following permissions to your `AndroidManifest.xml` file:\n\n```xml\n\u003cuses-permission android:name=\"android.permission.SYSTEM_ALERT_WINDOW\" /\u003e\n\u003cuses-permission android:name=\"android.permission.FOREGROUND_SERVICE\"/\u003e\n```\n\n## Basic Usage\n\n### Initialization and Permission Check\n\nIt's crucial to check and request the overlay permission before showing the window.\n\n```dart\n// Check if floating window permission is granted\nbool granted = await FloatingWindowAndroid.isPermissionGranted();\nif (!granted) {\n  // Request permission if not granted\n  await FloatingWindowAndroid.requestPermission();\n}\n```\n\n### Display Floating Window\n\nThe plugin automatically handles engine preparation. You can show the overlay at any time.\n\n```dart\n// Show floating window\nawait FloatingWindowAndroid.showOverlay(\n  width: WindowSize.matchParent, // Or a custom width in pixels\n  height: 300, // Or a custom height in pixels\n  alignment: OverlayAlignment.top, // Floating window alignment\n  flag: OverlayFlag.defaultFlag, // Floating window interaction mode\n  enableDrag: true, // Enable dragging\n  positionGravity: PositionGravity.auto, // Snapping effect after dragging\n  overlayTitle: \"My App is Running\", // Notification title\n  overlayContent: \"Tap to open the app\", // Notification content\n);\n```\n\n### Close Floating Window\n\n```dart\n// Close floating window from the main app\nawait FloatingWindowAndroid.closeOverlay();\n\n// Close floating window from within the overlay widget itself\nawait FloatingWindowAndroid.closeOverlayFromOverlay();\n```\n\n### Adjust Floating Window at Runtime\n\n```dart\n// Change floating window size\nawait FloatingWindowAndroid.resizeOverlay(400, 600);\n\n// Move floating window to a new position\nawait FloatingWindowAndroid.moveOverlay(OverlayPosition(100, 200));\n\n// Update floating window interaction mode (e.g., make it click-through)\nawait FloatingWindowAndroid.updateFlag(OverlayFlag.clickThrough);\n```\n\n### Data Sharing\n\nThe plugin uses a reliable messaging channel to ensure data is not lost.\n\n```dart\n// Send data from main app to the floating window\nawait FloatingWindowAndroid.shareData({\n  'key': 'value',\n  'count': 10,\n});\n\n// In your overlay widget, listen for data from the main app\nFloatingWindowAndroid.overlayListener.listen((data) {\n  // Process received data\n  print('Received data in overlay: $data');\n});\n```\n\n### Open Main App from Floating Window\n\n```dart\n// Bring the main app to the foreground from the overlay\nawait FloatingWindowAndroid.openMainApp();\n```\n\n## Engine Management (Advanced)\n\nThe plugin automatically manages the Flutter engine for the overlay window. It's created and cached when your app starts, ensuring instant overlay startup. In most cases, you don't need to manage the engine manually.\n\nHowever, if your app allows users to disable the overlay feature (e.g., switching to a notification-only mode), you can manually dispose of the engine to free up memory.\n\n### Disposing the Engine\n\nCall `dispose()` when the overlay feature is no longer needed.\n\n```dart\n// Example: User disables the overlay feature in settings\nvoid onOverlayFeatureDisabled() {\n  FloatingWindowAndroid.dispose();\n  print('Overlay engine disposed to save memory.');\n}\n```\n**Warning**: After calling `dispose()`, the next call to `showOverlay()` will fail or be slow unless you re-initialize the engine.\n\n### Re-initializing the Engine\n\nIf the user re-enables the overlay feature after it has been disposed, you must call `initialize()` to prepare the engine again.\n\n```dart\n// Example: User re-enables the overlay feature\nvoid onOverlayFeatureEnabled() {\n  FloatingWindowAndroid.initialize();\n  print('Overlay engine is being re-initialized.');\n}\n```\n\n## Floating Window Entry Point\n\nThe floating window requires a separate Dart entry point. Define it in your `lib/main.dart` file or another file.\n\n```dart\nimport 'package:flutter/material.dart';\n\n// Your overlay widget\nclass MyOverlayWidget extends StatelessWidget {\n  const MyOverlayWidget({super.key});\n  @override\n  Widget build(BuildContext context) {\n    return const Center(child: Text(\"I am an overlay!\"));\n  }\n}\n\n// The entry point for the overlay\n@pragma(\"vm:entry-point\")\nvoid overlayMain() {\n  runApp(\n    const MaterialApp(\n      debugShowCheckedModeBanner: false,\n      home: MyOverlayWidget(),\n    ),\n  );\n}\n\n// The main app entry point\nvoid main() {\n  // It's recommended to initialize bindings here\n  WidgetsFlutterBinding.ensureInitialized();\n  \n  runApp(\n    const MaterialApp(\n      home: YourMainApp(),\n    ),\n  );\n}\n```\n\n## Interaction Modes\n\nConfigure the interaction mode via the `flag` parameter in `showOverlay()`:\n\n- `OverlayFlag.clickThrough`: The floating window will not receive any touch events. Clicks pass through to the content behind it.\n- `OverlayFlag.defaultFlag`: The floating window can be interacted with, but it won't receive keyboard focus. System gestures (like back) work as expected.\n- `OverlayFlag.focusPointer`: The floating window can receive keyboard focus, ideal for overlays with text input fields.\n\n## Position Control\n\nControl the snapping behavior after dragging using `positionGravity`:\n\n- `PositionGravity.none`: The window stays exactly where the drag gesture ends.\n- `PositionGravity.left`: The window snaps to the left edge of the screen.\n- `PositionGravity.right`: The window snaps to the right edge of the screen.\n- `PositionGravity.auto`: The window snaps to the nearest vertical edge (left or right).\n\n## Notes\n\n- This plugin only supports the **Android** platform.\n- Android 8.0 (API 26) and above require a foreground service, which displays a persistent notification. This is a system requirement.\n- Certain Android manufacturers may have additional restrictions on background processes or overlay windows.\n- Always handle permission requests gracefully to provide a good user experience.\n- The cached engine consumes additional memory (~20-30MB). Use the `dispose()` method if your app has a state where the overlay is guaranteed not to be used.\n\n## API Reference\n\nSee the code documentation for a complete API reference.\n\n## License\n\n```\nMIT License\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaojiu-bb%2Ffloating_window_android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaojiu-bb%2Ffloating_window_android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaojiu-bb%2Ffloating_window_android/lists"}