macOS Window Toolkit #

A Flutter plugin for macOS window management, screen capture, and application discovery.

Features #

• 🪟 Window Management - Get, search, filter, close, and focus windows
• 📸 Screen Capture - Capture windows with ScreenCaptureKit or legacy methods
• 📱 App Discovery - Find and manage installed applications
• 🔐 Permission Management - Handle screen recording and accessibility permissions
• 🎯 Process Control - Terminate applications and manage process trees
• ⚡️ Real-time Monitoring - Monitor permission changes with streams

Installation #

dependencies:
  macos_window_toolkit: ^1.4.14

Setup (Required) #

1. Disable App Sandbox #

Edit macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements:

<key>com.apple.security.app-sandbox</key>
<false/>
<key>com.apple.security.automation.apple-events</key>
<true/>

2. Request Permissions at Runtime #

final toolkit = MacosWindowToolkit();

// Request screen recording permission (for window names and capture)
await toolkit.requestScreenRecordingPermission();

// Request accessibility permission (for window control and process management)
await toolkit.requestAccessibilityPermission();

Quick Start #

import 'package:macos_window_toolkit/macos_window_toolkit.dart';

final toolkit = MacosWindowToolkit();

// Get all windows
final windows = await toolkit.getAllWindows();
for (final window in windows) {
  print('${window.name} - ${window.ownerName}');
}

// Search windows
final chromeWindows = await toolkit.getWindowsByOwnerName('Chrome');

// Close a window
final result = await toolkit.closeWindow(windowId);

// Capture a window
final capture = await toolkit.captureWindow(windowId);
if (capture case CaptureSuccess(imageData: final data)) {
  // Save or display image data
}

// Find installed apps
final apps = await toolkit.getAllInstalledApplications();
if (apps case ApplicationSuccess(applications: final appList)) {
  print('Found ${appList.length} apps');
}

API Reference #

Window Management (9 methods) #

Screen Capture (7 methods) #

Permission Management (7 methods) #

Application Management (5 methods) #

System Info (2 methods) #

Permission Requirements #

Data Models #

MacosWindowInfo #

class MacosWindowInfo {
  final int windowId;
  final String name;           // Empty if no screen recording permission
  final String ownerName;
  final double x, y, width, height;
  final int layer;
  final bool isOnScreen;
  final int processId;
  final String? role;          // Requires accessibility permission
  final String? subrole;       // Requires accessibility permission
}

MacosApplicationInfo #

class MacosApplicationInfo {
  final String name;
  final String bundleId;
  final String version;
  final String path;
  final String iconPath;
}

Examples #

Permission Monitoring with Stream #

toolkit.startPermissionWatching(
  interval: Duration(seconds: 2),
  emitOnlyChanges: true,
);

toolkit.permissionStream.listen((status) {
  print('Screen Recording: ${status.screenRecording}');
  print('Accessibility: ${status.accessibility}');
  if (status.allPermissionsGranted) {
    print('All ready!');
  }
});

Advanced Window Filtering #

final windows = await toolkit.getWindowsAdvanced(
  ownerName: 'Chrome',
  ownerNameCaseSensitive: false,
  isOnScreen: true,
  width: 800,  // Exact width
);

Error Handling #

try {
  final windows = await toolkit.getAllWindows();
} on PlatformException catch (e) {
  switch (e.code) {
    case 'SCREEN_RECORDING_PERMISSION_DENIED':
      await toolkit.openScreenRecordingSettings();
    case 'ACCESSIBILITY_PERMISSION_DENIED':
      await toolkit.openAccessibilitySettings();
  }
}

Requirements #

• macOS 10.15+
• Flutter 3.10.0+
• Dart 3.0.0+
• App Sandbox must be disabled

App Store Distribution #

⚠️ Not recommended for App Store distribution due to sandbox requirements. This plugin requires system-level access that conflicts with App Store sandboxing policies. Consider:

• Distributing outside the App Store
• Requesting special entitlements from Apple (rarely approved)

Example App #

cd example/
flutter run -d macos

Documentation #

• Full API Reference
• Changelog
• Issue Tracker

License #

MIT License - see LICENSE file for details.

Made with ❤️ for the Flutter community