Migrate to macos_window_utils (#377)

* chore: bump Dart SDK version

* add `.vscode/settings.json` to .gitignore

* feat: add macos_window_utils

* feat: wrap side in example with `TransparentMacOSSidebar`

* feat: enable wallpaper tinting on content area

* feat: adjust macOS window brightness depending on theme

* feat: add a way to disable wallpaper tinting

Wallpaper tinting is now also disabled whenever an overlay filter is
used.

* refactor: refactor wallpaper tinted area

* fix: fix wallpaper tinting override being applied on overlay filter rebuild

* fix: do not override wallpaper tinting if no `WallpaperTintingSettingsCubit` is found

* refactor: stop relying on exceptions to check if `WallpaperTintingSettingsCubit` exists in widget tree

* change: switch from BLoC to global wallpaper tinting settings

* chore: remove unused imports

* change: make canvas color mimic `NSWindow.windowBackgroundColor`

* change: make wallpaper tinted area rebuild on layout change

* feat: make toolbar wallpaper-tinted

* doc: document `disableWallpaperTinting`

* doc: improve documentation of `disableWallpaperTinting`

Add link to #16296 and clarify that disabling wallpaper tinting is meant
to be a temporary solution.

* doc: document wallpaper tinted area

* doc: document wallpaper tinting override

* doc: document wallpaper tinting settings builder

* doc: document wallpaper tinting settings data

* change: make `numberOfWallpaperTintingOverrides` private

* doc: document global wallpaper tinting settings

* doc: fix typo

* refactor: refactor wallpaper tinted area

* feat: add `insertRepaintBoundary` property

* change: enable `insertRepaintBoundary` in toolbar

* change: enable `insertRepaintBoundary` in scaffold

* change: export wallpaper tinted area

* feat: enable wallpaper tinting on end sidebar

* feat: add `sidebarState` property to window

* fix: fix background color of end sidebar not matching canvas color when theme brightness does not match platform brightness

* fix: fix wallpaper tinting override using `deactivate` instead of `dispose`

* merge

* change: comment out swift code that hides the toolbar in fullscreen mode

* change: upgrade to macos_window_utils ^1.1.1

* feat: migrate window delegate to macos_window_utils

* change: remove commented-out and unused Swift code

* fix: fix sliver toolbar not having a backdrop filter

* docs: document toolbar's `isVisible` property

* docs: document sliver toolbar's `isVisible` property

* docs: document sliver toolbar page's `isVisible` property

* docs: document `_WallpaperTintedAreaOrBlurFilter`

* refactor: remove unused `key` parameter

* refactor: remove unused import

* readme: update “Modern window look”

* change: bump version

* changelog: add entry for version 2.0.0

* changelog: add migration hint

* merge: toolbar

* fix: remove duplicate `debugFillProperties`

* refactor: rename `pages` to `pageBuilders`

* fix: remove unused import

* fix: remove unused imports

* change: remove unnecessary `NSWindowDelegate` from `MainFlutterWindow`

* change: rename `isVisible` property to `allowWallpaperTintingOverrides` for toolbar

* change: rename `isVisible` property to `allowWallpaperTintingOverrides` for sliver toolbar

* fix: fix typo in comment

* fix: fix `disableWallpaperTinting` having no effect

* change: disable `VisualEffectSubviewContainer` when disabling wallpaper tinting in window

* fix: fix some unit tests not passing

Some unit tests were failing with the following message:
“A Timer is still pending even after the widget tree was disposed.”

The cause of that was that `VisualEffectSubviewContainer`, or more
precisely `VisualEffectSubviewContainerWithGlobalKey` is using a timer
to update its visual effect subview outside of the widget's `build`
method.

The issue is fixed by either disabling wallpaper tinting in the window
(and therefore eliminating the use of `VisualEffectSubviewContainer`)
or, in cases where that was impossible (such as the sidebar) running
`await tester.pump(Duration.zero);` to allow the timer to complete.

* remove unused import

* change default canvas color

`NSColor.windowBackgroundColor` was found to be inaccurate.
The color has instead been changed to a color that was captured using
the Digital Color Meter.

* upgrade to macos_window_utils 1.1.2

* update  “Modern window look” in readme for use with macos_window_utils 1.1.2

* change version to 2.0.0-beta.1

Co-authored-by: Reuben Turner <groovinchip@gmail.com>

* add code formatting to documentation

Highlighted `macos_ui` as a code element.

Co-authored-by: Reuben Turner <groovinchip@gmail.com>

* add missing comma to documentation

Co-authored-by: Reuben Turner <groovinchip@gmail.com>

* change version in changelog entry to 2.0.0-beta.1

Co-authored-by: Reuben Turner <groovinchip@gmail.com>

* change version in pubspec.lock

* format `window.dart`

* replace `Colors.transparent` with `MacosColors.transparent`

* document `WallpaperTintingSettingsBuilder`

* document `WallpaperTintedArea`

* implement `MacosWindowUtilsConfig`

* export `src/macos_window_utils_config.dart`

* use `MacosWindowUtilsConfig` in example

* document `MacosWindowUtilsConfig` constructor

* rename `_initMacosWindowUtils` to `_configureMacosWindowUtils` in example

* document `MacosWindowUtilsConfig` usage in readme

* replace opacity widget with repaint boundary

* improve documentation for `sidebarState`

* improve `MacosWindowUtilsConfig` documentation

* fix inconsistencies introduced by merging

* Update example/lib/main.dart

* remove ”do” prefix from field names in `MacosWindowUtilsConfig`

---------

Co-authored-by: Reuben Turner <groovinchip@gmail.com>

Author: Adrian-Samoticha

CHANGELOG.md

@@ -1,3 +1,13 @@
+## [2.0.0-beta.1]
+🚨 Breaking Changes 🚨
+* Migrate macos_ui to [macos_window_utils](https://pub.dev/packages/macos_window_utils), which provides the following benefits:
+  * Window animation smoothness is drastically improved, particularly when miniaturizing and deminiaturizing the application window.
+  * Some visual artifacts that occurred while the window was being (de)miniaturized (such as the application's shadow going missing) no longer occur.
+  * The sidebar remains transparent when the app's brightness setting mismatches the OS setting.
+  * Wallpaper tinting is now supported.
+
+To migrate an existing application, please refer to the “Modern window look” section in the README.
+
 ## [1.12.5]
 * Fixed a bug where the `Sidebar.key` parameter wasn't used, which caused certain layouts to be unachievable.
 

README.md

@@ -226,96 +226,42 @@ See the documentation for customizations and `ToolBar` examples.
 ## Modern window look
 
 A new look for macOS apps was introduced in Big Sur (macOS 11). To match that look 
-in your Flutter app, like our screenshots, your `macos/Runner/MainFlutterWindow.swift` 
-file should look like this:
+in your Flutter app, macos_ui relies on [macos_window_utils](https://pub.dev/packages/macos_window_utils), which requires a minimum macOS deployment target of 10.14.6. Therefore, make sure to open the `macos/Runner.xcworkspace` folder of your project using Xcode and search for `Runner.xcodeproj`. Go to `Info` > `Deployment Target` and set the `macOS Deployment Target` to `10.14.6` or above. Then, open your project's `Podfile` (if it doesn't show up in Xcode, you can find it in your project's `macos` directory via VS Code) and set the minimum deployment version in the first line to `10.14.6` or above:
 
-```swift
-import Cocoa
-import FlutterMacOS
-
-class BlurryContainerViewController: NSViewController {
-  let flutterViewController = FlutterViewController()
-
-  init() {
-    super.init(nibName: nil, bundle: nil)
-  }
-
-  required init?(coder: NSCoder) {
-    fatalError()
-  }
+```podspec
+platform :osx, '10.14.6'
+```
 
-  override func loadView() {
-    let blurView = NSVisualEffectView()
-    blurView.autoresizingMask = [.width, .height]
-    blurView.blendingMode = .behindWindow
-    blurView.state = .active
-    if #available(macOS 10.14, *) {
-        blurView.material = .sidebar
-    }
-    self.view = blurView
-  }
+Now, configure your window inside your `main()` as follows:
 
-  override func viewDidLoad() {
-    super.viewDidLoad()
+```dart
+/// This method initializes macos_window_utils and styles the window.
+Future<void> _configureMacosWindowUtils() async {
+  const config = MacosWindowUtilsConfig(
+    toolbarStyle: NSWindowToolbarStyle.unified,
+  );
+  await config.apply();
+}
 
-    self.addChild(flutterViewController)
+void main() async {
+  await _configureMacosWindowUtils();
 
-    flutterViewController.view.frame = self.view.bounds
-    flutterViewController.backgroundColor = .clear // **Required post-Flutter 3.7.0**
-    flutterViewController.view.autoresizingMask = [.width, .height]
-    self.view.addSubview(flutterViewController.view)
-  }
+  runApp(const MacosUIGalleryApp());
 }
+```
 
-class MainFlutterWindow: NSWindow, NSWindowDelegate {
-  override func awakeFromNib() {
-    delegate = self
-    let blurryContainerViewController = BlurryContainerViewController()
-    let windowFrame = self.frame
-    self.contentViewController = blurryContainerViewController
-    self.setFrame(windowFrame, display: true)
-
-    if #available(macOS 10.13, *) {
-      let customToolbar = NSToolbar()
-      customToolbar.showsBaselineSeparator = false
-      self.toolbar = customToolbar
-    }
-    self.titleVisibility = .hidden
-    self.titlebarAppearsTransparent = true
-    if #available(macOS 11.0, *) {
-      // Use .expanded if the app will have a title bar, else use .unified
-      self.toolbarStyle = .unified
-    }
-
-    self.isMovableByWindowBackground = true
-    self.styleMask.insert(NSWindow.StyleMask.fullSizeContentView)
-
-    self.isOpaque = false
-    self.backgroundColor = .clear
-
-    RegisterGeneratedPlugins(registry: blurryContainerViewController.flutterViewController)
-
-    super.awakeFromNib()
-  }
+Please note that if you are using a title bar (`TitleBar`) in your `MacosWindow`, you should set the `toolbarStyle` of your window to `NSWindowToolbarStyle.expanded`, in order to properly align the close, minimize, zoom window buttons:
 
-  func window(_ window: NSWindow, willUseFullScreenPresentationOptions proposedOptions: NSApplication.PresentationOptions = []) -> NSApplication.PresentationOptions {
-    return [.autoHideToolbar, .autoHideMenuBar, .fullScreen]
-  }
-
-  func windowWillEnterFullScreen(_ notification: Notification) {
-      self.toolbar?.isVisible = false
-  }
-  
-  func windowDidExitFullScreen(_ notification: Notification) {
-      self.toolbar?.isVisible = true
-  }
+```dart
+Future<void> _configureMacosWindowUtils() async {
+  const config = MacosWindowUtilsConfig(
+    toolbarStyle: NSWindowToolbarStyle.expanded,
+  );
+  await config.apply();
 }
-
 ```
 
-See [this issue comment](https://github.com/flutter/flutter/issues/59969#issuecomment-916682559) for more details on the new look and explanations for how it works.
-
-Please note that if you are using a title bar (`TitleBar`) in your `MacosWindow`, you should set the `toolbarStyle` of NSWindow to `.expanded`, in order to properly align the close, minimize, zoom window buttons. In any other case, you should keep it as `.unified`. This must be set beforehand, i.e. it cannot be switched in runtime.
+In any other case, you should keep it as `NSWindowToolbarStyle.unified`.
 
 ## ToolBar
 

example/lib/main.dart

@@ -13,7 +13,15 @@ import 'package:provider/provider.dart';
 
 import 'theme.dart';
 
-void main() {
+/// This method initializes macos_window_utils and styles the window.
+Future<void> _configureMacosWindowUtils() async {
+  const config = MacosWindowUtilsConfig();
+  await config.apply();
+}
+
+Future<void> main() async {
+  await _configureMacosWindowUtils();
+
   runApp(const MacosUIGalleryApp());
 }
 
@@ -55,23 +63,25 @@ class _WidgetGalleryState extends State<WidgetGallery> {
 
   late final searchFieldController = TextEditingController();
 
-  final List<Widget> pages = [
-    CupertinoTabView(
-      builder: (_) => const ButtonsPage(),
-    ),
-    const IndicatorsPage(),
-    const FieldsPage(),
-    const ColorsPage(),
-    const Center(
-      child: MacosIcon(
-        CupertinoIcons.add,
-      ),
-    ),
-    const DialogsPage(),
-    const ToolbarPage(),
-    const SliverToolbarPage(),
-    const TabViewPage(),
-    const SelectorsPage(),
+  final List<Widget Function(bool)> pageBuilders = [
+    (bool isVisible) => CupertinoTabView(
+          builder: (_) => const ButtonsPage(),
+        ),
+    (bool isVisible) => const IndicatorsPage(),
+    (bool isVisible) => const FieldsPage(),
+    (bool isVisible) => const ColorsPage(),
+    (bool isVisible) => const Center(
+          child: MacosIcon(
+            CupertinoIcons.add,
+          ),
+        ),
+    (bool isVisible) => const DialogsPage(),
+    (bool isVisible) => const ToolbarPage(),
+    (bool isVisible) => SliverToolbarPage(
+          isVisible: isVisible,
+        ),
+    (bool isVisible) => const TabViewPage(),
+    (bool isVisible) => const SelectorsPage(),
   ];
 
   @override
@@ -291,7 +301,14 @@ class _WidgetGalleryState extends State<WidgetGallery> {
         ),
         child: IndexedStack(
           index: pageIndex,
-          children: pages,
+          children: pageBuilders
+              .asMap()
+              .map((index, builder) {
+                final widget = builder(index == pageIndex);
+                return MapEntry(index, widget);
+              })
+              .values
+              .toList(),
         ),
       ),
     );

example/lib/pages/sliver_toolbar_page.dart

@@ -3,7 +3,27 @@ import 'package:flutter/material.dart';
 import 'package:macos_ui/macos_ui.dart';
 
 class SliverToolbarPage extends StatefulWidget {
-  const SliverToolbarPage({super.key});
+  const SliverToolbarPage({super.key, required this.isVisible});
+
+  /// Whether this [SliverToolbarPage] is currently visible on the screen
+  /// (that is, not e.g. hidden by an [IndexedStack]).
+  ///
+  /// By default, macos_ui applies wallpaper tinting to the application's
+  /// window to match macOS' native appearance:
+  ///
+  /// <img src="https://user-images.githubusercontent.com/86920182/220182724-d78319d7-5c41-4e8c-b785-a73a6ea24927.jpg" width=640/>
+  ///
+  /// However, this effect is realized by inserting `NSVisualEffectView`s behind
+  /// Flutter's canvas and turning the background of areas that are meant to be
+  /// affected by wallpaper tinting transparent. Since Flutter's
+  /// [`ImageFilter.blur`](https://api.flutter.dev/flutter/dart-ui/ImageFilter/ImageFilter.blur.html)
+  /// does not support transparency, wallpaper tinting is disabled automatically
+  /// when this widget's [isVisible] is true.
+  ///
+  /// This is meant to be a temporary solution until
+  /// [#16296](https://github.com/flutter/flutter/issues/16296) is resolved in
+  /// the Flutter project.
+  final bool isVisible;
 
   @override
   State<SliverToolbarPage> createState() => _SliverToolbarPageState();
@@ -27,6 +47,7 @@ class _SliverToolbarPageState extends State<SliverToolbarPage> {
                   floating: floating,
                   pinned: pinned,
                   toolbarOpacity: opacity,
+                  allowWallpaperTintingOverrides: widget.isVisible,
                   actions: [
                     ToolBarIconButton(
                       label: 'Pinned',

example/macos/Flutter/GeneratedPluginRegistrant.swift

@@ -6,7 +6,9 @@ import FlutterMacOS
 import Foundation
 
 import macos_ui
+import macos_window_utils
 
 func RegisterGeneratedPlugins(registry: FlutterPluginRegistry) {
   MacOSUiPlugin.register(with: registry.registrar(forPlugin: "MacOSUiPlugin"))
+  MacOSWindowUtilsPlugin.register(with: registry.registrar(forPlugin: "MacOSWindowUtilsPlugin"))
 }

example/macos/Podfile

@@ -1,4 +1,4 @@
-platform :osx, '10.14'
+platform :osx, '10.14.6'
 
 # CocoaPods analytics sends network stats synchronously affecting flutter build latency.
 ENV['COCOAPODS_DISABLE_STATS'] = 'true'

example/macos/Podfile.lock

@@ -2,21 +2,27 @@ PODS:
   - FlutterMacOS (1.0.0)
   - macos_ui (0.1.0):
     - FlutterMacOS
+  - macos_window_utils (1.0.0):
+    - FlutterMacOS
 
 DEPENDENCIES:
   - FlutterMacOS (from `Flutter/ephemeral`)
   - macos_ui (from `Flutter/ephemeral/.symlinks/plugins/macos_ui/macos`)
+  - macos_window_utils (from `Flutter/ephemeral/.symlinks/plugins/macos_window_utils/macos`)
 
 EXTERNAL SOURCES:
   FlutterMacOS:
     :path: Flutter/ephemeral
   macos_ui:
     :path: Flutter/ephemeral/.symlinks/plugins/macos_ui/macos
+  macos_window_utils:
+    :path: Flutter/ephemeral/.symlinks/plugins/macos_window_utils/macos
 
 SPEC CHECKSUMS:
   FlutterMacOS: 8f6f14fa908a6fb3fba0cd85dbd81ec4b251fb24
   macos_ui: 6229a8922cd97bafb7d9636c8eb8dfb0744183ca
+  macos_window_utils: 933f91f64805e2eb91a5bd057cf97cd097276663
 
-PODFILE CHECKSUM: 353c8bcc5d5b0994e508d035b5431cfe18c1dea7
+PODFILE CHECKSUM: ff0a9a3ce75ee73f200ca7e2f47745698c917ef9
 
 COCOAPODS: 1.11.3

example/macos/Runner.xcodeproj/project.pbxproj

@@ -61,7 +61,7 @@
 		33CC10F22044A3C60003C045 /* Assets.xcassets */ = {isa = PBXFileReference; lastKnownFileType = folder.assetcatalog; name = Assets.xcassets; path = Runner/Assets.xcassets; sourceTree = "<group>"; };
 		33CC10F52044A3C60003C045 /* Base */ = {isa = PBXFileReference; lastKnownFileType = file.xib; name = Base; path = Base.lproj/MainMenu.xib; sourceTree = "<group>"; };
 		33CC10F72044A3C60003C045 /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; name = Info.plist; path = Runner/Info.plist; sourceTree = "<group>"; };
-		33CC11122044BFA00003C045 /* MainFlutterWindow.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MainFlutterWindow.swift; sourceTree = "<group>"; };
+		33CC11122044BFA00003C045 /* MainFlutterWindow.swift */ = {isa = PBXFileReference; indentWidth = 2; lastKnownFileType = sourcecode.swift; path = MainFlutterWindow.swift; sourceTree = "<group>"; tabWidth = 2; };
 		33CEB47222A05771004F2AC0 /* Flutter-Debug.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = "Flutter-Debug.xcconfig"; sourceTree = "<group>"; };
 		33CEB47422A05771004F2AC0 /* Flutter-Release.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; path = "Flutter-Release.xcconfig"; sourceTree = "<group>"; };
 		33CEB47722A0578A004F2AC0 /* Flutter-Generated.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = "Flutter-Generated.xcconfig"; path = "ephemeral/Flutter-Generated.xcconfig"; sourceTree = "<group>"; };
@@ -94,7 +94,6 @@
 				94ECD9F878BC8EB5F0E7094E /* Pods-Runner.release.xcconfig */,
 				AFB798A3289226D0E5AB9985 /* Pods-Runner.profile.xcconfig */,
 			);
-			name = Pods;
 			path = Pods;
 			sourceTree = "<group>";
 		};
@@ -405,7 +404,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 10.14;
+				MACOSX_DEPLOYMENT_TARGET = 10.14.6;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = macosx;
 				SWIFT_COMPILATION_MODE = wholemodule;
@@ -484,7 +483,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 10.14;
+				MACOSX_DEPLOYMENT_TARGET = 10.14.6;
 				MTL_ENABLE_DEBUG_INFO = YES;
 				ONLY_ACTIVE_ARCH = YES;
 				SDKROOT = macosx;
@@ -531,7 +530,7 @@
 				GCC_WARN_UNINITIALIZED_AUTOS = YES_AGGRESSIVE;
 				GCC_WARN_UNUSED_FUNCTION = YES;
 				GCC_WARN_UNUSED_VARIABLE = YES;
-				MACOSX_DEPLOYMENT_TARGET = 10.14;
+				MACOSX_DEPLOYMENT_TARGET = 10.14.6;
 				MTL_ENABLE_DEBUG_INFO = NO;
 				SDKROOT = macosx;
 				SWIFT_COMPILATION_MODE = wholemodule;