feat: make window visual effect state customizable (#25106)

Co-authored-by: Shelley Vohr <[email protected]>

docs/api/browser-window.md

@@ -212,6 +212,10 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     Default is `false`. On Windows, does not work unless the window is frameless.
   * `type` String (optional) - The type of window, default is normal window. See more about
     this below.
+  * `visualEffectState` String (optional) - Specify how the material appearance should reflect window activity state on macOS. Must be used with the `vibrancy` property. Possible values are:
+    * `followWindow` - The backdrop should automatically appear active when the window is active, and inactive when it is not. This is the default.
+    * `active` - The backdrop should always appear active.
+    * `inactive` - The backdrop should always appear inactive.
   * `titleBarStyle` String (optional) - The style of window title bar.
     Default is `default`. Possible values are:
     * `default` - Results in the standard gray opaque Mac title

shell/browser/native_window_mac.h

@@ -157,6 +157,12 @@ class NativeWindowMac : public NativeWindow, public ui::NativeThemeObserver {
   gfx::Point GetTrafficLightPosition() const override;
   void OnNativeThemeUpdated(ui::NativeTheme* observed_theme) override;
 
+  enum class VisualEffectState {
+    FOLLOW_WINDOW,
+    ACTIVE,
+    INACTIVE,
+  };
+
   enum class TitleBarStyle {
     NORMAL,
     HIDDEN,
@@ -218,6 +224,9 @@ class NativeWindowMac : public NativeWindow, public ui::NativeThemeObserver {
   // The "titleBarStyle" option.
   TitleBarStyle title_bar_style_ = TitleBarStyle::NORMAL;
 
+  // The "visualEffectState" option.
+  VisualEffectState visual_effect_state_ = VisualEffectState::FOLLOW_WINDOW;
+
   // The visibility mode of window button controls when explicitly set through
   // setWindowButtonVisibility().
   base::Optional<bool> window_button_visibility_;

shell/browser/native_window_mac.mm

@@ -274,6 +274,28 @@ struct Converter<electron::NativeWindowMac::TitleBarStyle> {
   }
 };
 
+template <>
+struct Converter<electron::NativeWindowMac::VisualEffectState> {
+  static bool FromV8(v8::Isolate* isolate,
+                     v8::Handle<v8::Value> val,
+                     electron::NativeWindowMac::VisualEffectState* out) {
+    using VisualEffectState = electron::NativeWindowMac::VisualEffectState;
+    std::string visual_effect_state;
+    if (!ConvertFromV8(isolate, val, &visual_effect_state))
+      return false;
+    if (visual_effect_state == "followWindow") {
+      *out = VisualEffectState::FOLLOW_WINDOW;
+    } else if (visual_effect_state == "active") {
+      *out = VisualEffectState::ACTIVE;
+    } else if (visual_effect_state == "inactive") {
+      *out = VisualEffectState::INACTIVE;
+    } else {
+      return false;
+    }
+    return true;
+  }
+};
+
 }  // namespace gin
 
 namespace electron {
@@ -344,6 +366,7 @@ NativeWindowMac::NativeWindowMac(const gin_helper::Dictionary& options,
   options.Get(options::kFullscreenWindowTitle, &fullscreen_window_title_);
   options.Get(options::kSimpleFullScreen, &always_simple_fullscreen_);
   options.Get(options::kTrafficLightPosition, &traffic_light_position_);
+  options.Get(options::kVisualEffectState, &visual_effect_state_);
 
   bool minimizable = true;
   options.Get(options::kMinimizable, &minimizable);
@@ -1451,7 +1474,14 @@ void NativeWindowMac::SetVibrancy(const std::string& type) {
 
     [effect_view setAutoresizingMask:NSViewWidthSizable | NSViewHeightSizable];
     [effect_view setBlendingMode:NSVisualEffectBlendingModeBehindWindow];
-    [effect_view setState:NSVisualEffectStateFollowsWindowActiveState];
+
+    if (visual_effect_state_ == VisualEffectState::ACTIVE) {
+      [effect_view setState:NSVisualEffectStateActive];
+    } else if (visual_effect_state_ == VisualEffectState::INACTIVE) {
+      [effect_view setState:NSVisualEffectStateInactive];
+    } else {
+      [effect_view setState:NSVisualEffectStateFollowsWindowActiveState];
+    }
 
     // Make frameless Vibrant windows have rounded corners.
     if (!has_frame() && !is_modal()) {

shell/common/options_switches.cc

@@ -99,6 +99,10 @@ const char kWebPreferences[] = "webPreferences";
 // Add a vibrancy effect to the browser window
 const char kVibrancyType[] = "vibrancy";
 
+// Specify how the material appearance should reflect window activity state on
+// macOS.
+const char kVisualEffectState[] = "visualEffectState";
+
 // The factor of which page should be zoomed.
 const char kZoomFactor[] = "zoomFactor";
 

shell/common/options_switches.h

@@ -54,6 +54,7 @@ extern const char kOpacity[];
 extern const char kFocusable[];
 extern const char kWebPreferences[];
 extern const char kVibrancyType[];
+extern const char kVisualEffectState[];
 extern const char kTrafficLightPosition[];
 
 // WebPreferences.