chore: deprecate `systemPreferences.isAeroGlassEnabled()` (#45554)

Co-authored-by: trop[bot] <37223003+trop[bot]@users.noreply.github.com>
Co-authored-by: Milan Burda <[email protected]>

docs/api/system-preferences.md

@@ -6,7 +6,7 @@ Process: [Main](../glossary.md#main-process), [Utility](../glossary.md#utility-p
 
 ```js
 const { systemPreferences } = require('electron')
-console.log(systemPreferences.isAeroGlassEnabled())
+console.log(systemPreferences.getEffectiveAppearance())
 ```
 
 ## Events
@@ -181,35 +181,13 @@ Some popular `key` and `type`s are:
 Removes the `key` in `NSUserDefaults`. This can be used to restore the default
 or global value of a `key` previously set with `setUserDefault`.
 
-### `systemPreferences.isAeroGlassEnabled()` _Windows_
+### `systemPreferences.isAeroGlassEnabled()` _Windows_ _Deprecated_
 
 Returns `boolean` - `true` if [DWM composition][dwm-composition] (Aero Glass) is
 enabled, and `false` otherwise.
 
-An example of using it to determine if you should create a transparent window or
-not (transparent windows won't work correctly when DWM composition is disabled):
-
-```js
-const { BrowserWindow, systemPreferences } = require('electron')
-const browserOptions = { width: 1000, height: 800 }
-
-// Make the window transparent only if the platform supports it.
-if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
-  browserOptions.transparent = true
-  browserOptions.frame = false
-}
-
-// Create the window.
-const win = new BrowserWindow(browserOptions)
-
-// Navigate.
-if (browserOptions.transparent) {
-  win.loadFile('index.html')
-} else {
-  // No transparency, so we load a fallback that uses basic styles.
-  win.loadFile('fallback.html')
-}
-```
+**Deprecated:**
+This function has been always returning `true` since Electron 23, which only supports Windows 10+.
 
 [dwm-composition]: https://learn.microsoft.com/en-us/windows/win32/dwm/composition-ovw
 

docs/breaking-changes.md

@@ -63,6 +63,13 @@ webContents.on('console-message', ({ level, message, lineNumber, sourceId, frame
 
 Additionally, `level` is now a string with possible values of `info`, `warning`, `error`, and `debug`.
 
+### Deprecated: `systemPreferences.isAeroGlassEnabled()`
+
+The `systemPreferences.isAeroGlassEnabled()` function has been deprecated without replacement.
+It has been always returning `true` since Electron 23, which only supports Windows 10+, where DWM composition can no longer be disabled.
+
+https://learn.microsoft.com/en-us/windows/win32/dwm/composition-ovw#disabling-dwm-composition-windows7-and-earlier
+
 ## Planned Breaking API Changes (34.0)
 
 ### Behavior Changed: menu bar will be hidden during fullscreen on Windows

lib/browser/api/system-preferences.ts

@@ -20,4 +20,12 @@ if ('accessibilityDisplayShouldReduceTransparency' in systemPreferences) {
   });
 }
 
+if (process.platform === 'win32') {
+  const isAeroGlassEnabledDeprecated = deprecate.warnOnce('systemPreferences.isAeroGlassEnabled');
+  systemPreferences.isAeroGlassEnabled = () => {
+    isAeroGlassEnabledDeprecated();
+    return true;
+  };
+}
+
 export default systemPreferences;

shell/browser/api/electron_api_system_preferences.cc

@@ -60,9 +60,7 @@ gin::ObjectTemplateBuilder SystemPreferences::GetObjectTemplateBuilder(
                  &SystemPreferences::GetMediaAccessStatus)
 #endif
 
-#if BUILDFLAG(IS_WIN)
-      .SetMethod("isAeroGlassEnabled", &SystemPreferences::IsAeroGlassEnabled)
-#elif BUILDFLAG(IS_MAC)
+#if BUILDFLAG(IS_MAC)
       .SetMethod("postNotification", &SystemPreferences::PostNotification)
       .SetMethod("subscribeNotification",
                  &SystemPreferences::SubscribeNotification)

shell/browser/api/electron_api_system_preferences.h

@@ -63,8 +63,6 @@ class SystemPreferences final
                                    const std::string& media_type);
 #endif
 #if BUILDFLAG(IS_WIN)
-  bool IsAeroGlassEnabled();
-
   void InitializeWindow();
 
   // gfx::SysColorChangeListener:

shell/browser/api/electron_api_system_preferences_win.cc

@@ -76,10 +76,6 @@ std::string ConvertDeviceAccessStatus(DeviceAccessStatus value) {
 
 namespace api {
 
-bool SystemPreferences::IsAeroGlassEnabled() {
-  return true;
-}
-
 std::string hexColorDWORDToRGBA(DWORD color) {
   DWORD rgba = color << 8 | color >> 24;
   std::ostringstream stream;

spec/api-system-preferences-spec.ts

@@ -2,6 +2,7 @@ import { systemPreferences } from 'electron/main';
 
 import { expect } from 'chai';
 
+import { expectDeprecationMessages } from './lib/deprecate-helpers';
 import { ifdescribe } from './lib/spec-helpers';
 
 describe('systemPreferences module', () => {
@@ -59,6 +60,13 @@ describe('systemPreferences module', () => {
     });
   });
 
+  ifdescribe(process.platform === 'win32')('systemPreferences.isAeroGlassEnabled()', () => {
+    it('always returns true', () => {
+      expect(systemPreferences.isAeroGlassEnabled()).to.equal(true);
+      expectDeprecationMessages(() => systemPreferences.isAeroGlassEnabled(), '\'systemPreferences.isAeroGlassEnabled\' is deprecated and will be removed.');
+    });
+  });
+
   ifdescribe(process.platform === 'darwin')('systemPreferences.getUserDefault(key, type)', () => {
     it('returns values for known user defaults', () => {
       const locale = systemPreferences.getUserDefault('AppleLocale', 'string');

spec/ts-smoke/electron/main.ts

@@ -359,16 +359,10 @@ app.commandLine.appendSwitch('vmodule', 'console=0');
 const browserOptions = {
   width: 1000,
   height: 800,
-  transparent: false,
-  frame: true
+  transparent: true,
+  frame: false
 };
 
-// Make the window transparent only if the platform supports it.
-if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
-  browserOptions.transparent = true;
-  browserOptions.frame = false;
-}
-
 if (process.platform === 'win32') {
   systemPreferences.on('color-changed', () => { console.log('color changed'); });
   // @ts-expect-error Removed API