macOS Window Toolkit #

A Flutter plugin for macOS that provides comprehensive window management functionality. This plugin allows Flutter applications to retrieve detailed information about all open windows on the macOS system, including window properties like title, bounds, owner application, and process ID.

Features #

🪟 Window Enumeration: Get a list of all open windows on the system
📊 Window Properties: Access detailed window information including:
- Window ID and title
- Owner application name
- Window bounds (position and size)
- Window layer level
- Visibility status
- Process ID
👀 Real-time Permission Monitoring: Monitor macOS permissions with live updates
- Screen Recording permission tracking
- Accessibility permission tracking
- Configurable monitoring intervals
- Type-safe permission status updates
- Perfect integration with state management (Riverpod, Bloc, etc.)
🔐 Permission Management: Check and request macOS permissions
- Screen recording permission
- Accessibility permission
- Open system preference panes
🚀 High Performance: Efficient native implementation using Core Graphics APIs
🛡️ Privacy Compliant: Includes proper privacy manifest for App Store distribution
🔧 Easy Integration: Simple API with comprehensive error handling

Platform Support #

Platform	Support
macOS	✅
iOS	❌
Android	❌
Windows	❌
Linux	❌
Web	❌

Minimum Requirements:

macOS 10.11 or later
Flutter 3.3.0 or later
Dart 3.8.1 or later

Installation #

Add this package to your pubspec.yaml:

dependencies:
  macos_window_toolkit: ^1.1.3

Then run:

flutter pub get

Quick Start #

Basic Window Enumeration #

import 'package:macos_window_toolkit/macos_window_toolkit.dart';

void main() async {
  final toolkit = MacosWindowToolkit();
  
  // Get all open windows
  final windows = await toolkit.getAllWindows();
  
  for (final window in windows) {
    print('Window: ${window.name}');
    print('App: ${window.ownerName}');
    print('Bounds: ${window.bounds}');
    print('---');
  }
}

Real-time Permission Monitoring #

import 'package:macos_window_toolkit/macos_window_toolkit.dart';

void main() async {
  final toolkit = MacosWindowToolkit();
  
  // Start monitoring permissions every 2 seconds
  toolkit.startPermissionWatching();
  
  // Listen to permission changes
  toolkit.permissionStream.listen((status) {
    if (status.hasChanges) {
      print('Permission changed!');
      print('Screen Recording: ${status.screenRecording}');
      print('Accessibility: ${status.accessibility}');
      
      if (status.allPermissionsGranted) {
        print('All permissions granted! 🎉');
      } else {
        print('Missing: ${status.deniedPermissions.join(', ')}');
      }
    }
  });
}

Usage #

Permission Monitoring with Riverpod #

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'package:macos_window_toolkit/macos_window_toolkit.dart';

// Create a StreamProvider for permission monitoring
final permissionProvider = StreamProvider<PermissionStatus>((ref) {
  final toolkit = MacosWindowToolkit();
  toolkit.startPermissionWatching(
    interval: const Duration(seconds: 2),
    emitOnlyChanges: true, // Only emit when permissions change
  );
  return toolkit.permissionStream;
});

// Use in your widget
class MyApp extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final permissionAsync = ref.watch(permissionProvider);
    
    return permissionAsync.when(
      data: (status) {
        if (status.allPermissionsGranted) {
          return MainApp(); // Show main app
        } else {
          return PermissionSetupScreen(
            missingPermissions: status.deniedPermissions,
          );
        }
      },
      loading: () => const LoadingScreen(),
      error: (error, _) => ErrorScreen(error: error),
    );
  }
}

Basic Window Enumeration #

import 'package:macos_window_toolkit/macos_window_toolkit.dart';

class WindowManager {
  final _toolkit = MacosWindowToolkit();
  
  Future<List<MacosWindowInfo>> getVisibleWindows() async {
    try {
      final windows = await _toolkit.getAllWindows();
      return windows.where((window) => window.isOnScreen).toList();
    } catch (e) {
      print('Error getting windows: $e');
      return [];
    }
  }
}

Permission Management #

final toolkit = MacosWindowToolkit();

// Check current permissions
final hasScreenRecording = await toolkit.hasScreenRecordingPermission();
final hasAccessibility = await toolkit.hasAccessibilityPermission();

// Request permissions
await toolkit.requestScreenRecordingPermission();
await toolkit.requestAccessibilityPermission();

// Open system settings
await toolkit.openScreenRecordingSettings();
await toolkit.openAccessibilitySettings();

Window Information Structure #

Each window object contains the following properties:

class WindowInfo {
  final int windowId;        // Unique window identifier
  final String name;         // Window title
  final String ownerName;    // Application name that owns the window
  final List<double> bounds; // [x, y, width, height]
  final int layer;           // Window layer level
  final bool isOnScreen;     // Whether window is visible
  final int processId;       // Process ID of the owning application
}

Filtering Windows #

// Filter by application
final chromeWindows = windows
    .where((w) => w.ownerName.contains('Chrome'))
    .toList();

// Filter by visibility
final visibleWindows = windows
    .where((w) => w.isOnScreen)
    .toList();

// Filter by size (width > 500px)
final largeWindows = windows
    .where((w) => w.bounds[2] > 500)
    .toList();

Error Handling #

try {
  final windows = await MacosWindowToolkit.getAllWindows();
  // Process windows
} on PlatformException catch (e) {
  switch (e.code) {
    case 'PERMISSION_DENIED':
      print('Permission denied to access window information');
      break;
    case 'SYSTEM_ERROR':
      print('System error occurred: ${e.message}');
      break;
    default:
      print('Unknown error: ${e.message}');
  }
} catch (e) {
  print('Unexpected error: $e');
}

Example App #

The plugin includes a comprehensive example app that demonstrates all features:

cd example/
flutter run -d macos

The example app includes:

Real-time window list updates
Window search and filtering
Detailed window information display
Permission handling examples

Privacy and Permissions #

This plugin uses public macOS APIs that typically don't require explicit user permissions. However, some system configurations might require accessibility permissions for full functionality.

App Sandbox Requirements #

Important: Applications using this plugin must disable App Sandbox to function properly. This is because the plugin requires access to system-wide resources that are restricted in sandboxed environments.

Why Sandbox Must Be Disabled

The plugin uses the following APIs that require sandbox to be disabled:

Window Information Access
- CGWindowListCopyWindowInfo() - Accesses window data from other applications
- Sandboxed apps cannot read window information from other processes
Accessibility API Operations
- AXUIElementCreateApplication() - Creates accessibility elements for other apps
- AXUIElementCopyAttributeValue() - Reads window properties from other apps
- AXUIElementPerformAction() - Performs actions (like closing windows) on other apps
Process Control Operations
- kill() system calls - Terminates other processes
- sysctl() - Queries system process lists
- NSRunningApplication - Controls other applications
Screen Capture (Legacy Support)
- CGWindowListCreateImage() - Captures screenshots of other app windows
- Requires access to other applications' visual content
Apple Events Communication
- Requires com.apple.security.automation.apple-events entitlement
- Enables inter-app communication for window management

How to Disable Sandbox

To disable sandbox in your macOS app:

Open macos/Runner/Release.entitlements and macos/Runner/DebugProfile.entitlements
Set the sandbox key to false:

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

Add Apple Events entitlement:

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

App Store Distribution

Note: Apps distributed through the Mac App Store typically require sandboxing. If you need App Store distribution, you may need to:

Request special entitlements from Apple for system-level access
Consider alternative approaches that work within sandbox restrictions
Distribute outside the App Store

Privacy Manifest #

The plugin includes a privacy manifest (PrivacyInfo.xcprivacy) that declares:

No user data collection
No tracking functionality
No network requests

API Reference #