diff --git a/docs/api/system-preferences.md b/docs/api/system-preferences.md index 1110ff94f4..37a9154111 100644 --- a/docs/api/system-preferences.md +++ b/docs/api/system-preferences.md @@ -417,7 +417,7 @@ Returns an object with system animation settings. ## Properties -### `systemPreferences.appLevelAppearance` _macOS_ +### `systemPreferences.appLevelAppearance` _macOS_ _Deprecated_ A `string` property that can be `dark`, `light` or `unknown`. It determines the macOS appearance setting for your application. This maps to values in: [NSApplication.appearance](https://developer.apple.com/documentation/appkit/nsapplication/2967170-appearance?language=objc). Setting this will override the diff --git a/docs/breaking-changes.md b/docs/breaking-changes.md index 25833fb39f..e71bb5690d 100644 --- a/docs/breaking-changes.md +++ b/docs/breaking-changes.md @@ -63,6 +63,41 @@ w.webContents.getPrintersAsync().then((printers) => { }) ``` +### Deprecated: `systemPreferences.{get,set}AppLevelAppearance` and `systemPreferences.appLevelAppearance` + +The `systemPreferences.getAppLevelAppearance` and `systemPreferences.setAppLevelAppearance` +methods have been deprecated, as well as the `systemPreferences.appLevelAppearance` property. +Use the `nativeTheme` module instead. + +```js +// Deprecated +systemPreferences.getAppLevelAppearance() +// Replace with +nativeTheme.shouldUseDarkColors + +// Deprecated +systemPreferences.appLevelAppearance +// Replace with +nativeTheme.shouldUseDarkColors + +// Deprecated +systemPreferences.setAppLevelAppearance('dark') +// Replace with +nativeTheme.themeSource = 'dark' +``` + +### Deprecated: `alternate-selected-control-text` value for `systemPreferences.getColor` + +The `alternate-selected-control-text` value for `systemPreferences.getColor` +has been deprecated. Use `selected-content-background` instead. + +```js +// Deprecated +systemPreferences.getColor('alternate-selected-control-text') +// Replace with +systemPreferences.getColor('selected-content-background') +``` + ## Planned Breaking API Changes (25.0) ### Deprecated: `protocol.{register,intercept}{Buffer,String,Stream,File,Http}Protocol` diff --git a/lib/browser/api/system-preferences.ts b/lib/browser/api/system-preferences.ts index 424c276c63..52962e754c 100644 --- a/lib/browser/api/system-preferences.ts +++ b/lib/browser/api/system-preferences.ts @@ -1,12 +1,31 @@ +import * as deprecate from '@electron/internal/common/deprecate'; + const { systemPreferences } = process._linkedBinding('electron_browser_system_preferences'); if ('getAppLevelAppearance' in systemPreferences) { const nativeALAGetter = systemPreferences.getAppLevelAppearance; const nativeALASetter = systemPreferences.setAppLevelAppearance; + const warnALA = deprecate.warnOnce('appLevelAppearance'); + const warnALAGetter = deprecate.warnOnce('getAppLevelAppearance function'); + const warnALASetter = deprecate.warnOnce('setAppLevelAppearance function'); Object.defineProperty(systemPreferences, 'appLevelAppearance', { - get: () => nativeALAGetter.call(systemPreferences), - set: (appearance) => nativeALASetter.call(systemPreferences, appearance) + get: () => { + warnALA(); + return nativeALAGetter.call(systemPreferences); + }, + set: (appearance) => { + warnALA(); + nativeALASetter.call(systemPreferences, appearance); + } }); + systemPreferences.getAppLevelAppearance = () => { + warnALAGetter(); + return nativeALAGetter.call(systemPreferences); + }; + systemPreferences.setAppLevelAppearance = (appearance) => { + warnALASetter(); + nativeALASetter.call(systemPreferences, appearance); + }; } if ('getEffectiveAppearance' in systemPreferences) { diff --git a/spec/api-native-theme-spec.ts b/spec/api-native-theme-spec.ts index ec46383945..1f6fe2a236 100644 --- a/spec/api-native-theme-spec.ts +++ b/spec/api-native-theme-spec.ts @@ -4,6 +4,7 @@ import { once } from 'node:events'; import * as path from 'node:path'; import { setTimeout } from 'node:timers/promises'; +import { expectDeprecationMessages } from './lib/deprecate-helpers'; import { ifdescribe } from './lib/spec-helpers'; import { closeAllWindows } from './lib/window-helpers'; @@ -59,11 +60,16 @@ describe('nativeTheme module', () => { }); ifdescribe(process.platform === 'darwin')('on macOS', () => { - it('should update appLevelAppearance when set', () => { - nativeTheme.themeSource = 'dark'; - expect(systemPreferences.appLevelAppearance).to.equal('dark'); - nativeTheme.themeSource = 'light'; - expect(systemPreferences.appLevelAppearance).to.equal('light'); + it('should update appLevelAppearance when set', async () => { + await expectDeprecationMessages( + () => { + nativeTheme.themeSource = 'dark'; + expect(systemPreferences.appLevelAppearance).to.equal('dark'); + nativeTheme.themeSource = 'light'; + expect(systemPreferences.appLevelAppearance).to.equal('light'); + }, + "(electron) 'appLevelAppearance' is deprecated and will be removed." + ); }); }); diff --git a/spec/api-system-preferences-spec.ts b/spec/api-system-preferences-spec.ts index 7d12bdb4ed..6a9395f5e9 100644 --- a/spec/api-system-preferences-spec.ts +++ b/spec/api-system-preferences-spec.ts @@ -1,5 +1,6 @@ import { expect } from 'chai'; import { systemPreferences } from 'electron/main'; +import { expectDeprecationMessages } from './lib/deprecate-helpers'; import { ifdescribe } from './lib/spec-helpers'; describe('systemPreferences module', () => { @@ -174,9 +175,8 @@ describe('systemPreferences module', () => { }).to.throw(`Unknown color: ${color}`); }); - it('returns a valid color', () => { + it('returns a valid color', async () => { const colors = [ - 'alternate-selected-control-text', 'control-background', 'control', 'control-text', @@ -209,12 +209,20 @@ describe('systemPreferences module', () => { 'unemphasized-selected-text', 'window-background', 'window-frame-text' - ]; + ] as const; colors.forEach(color => { - const sysColor = systemPreferences.getColor(color as any); + const sysColor = systemPreferences.getColor(color); expect(sysColor).to.be.a('string'); }); + + await expectDeprecationMessages( + () => { + const sysColor = systemPreferences.getColor('alternate-selected-control-text'); + expect(sysColor).to.be.a('string'); + }, + "'alternate-selected-control-text' is deprecated as an input to getColor. Use 'selected-content-background' instead." + ); }); }); @@ -233,15 +241,25 @@ describe('systemPreferences module', () => { }); describe('with functions', () => { - it('returns a valid appearance', () => { - const appearance = systemPreferences.getAppLevelAppearance(); - expect(options).to.include(appearance); + it('returns a valid appearance', async () => { + await expectDeprecationMessages( + () => { + const appearance = systemPreferences.getAppLevelAppearance(); + expect(options).to.include(appearance); + }, + "(electron) 'getAppLevelAppearance function' is deprecated and will be removed." + ); }); - it('can be changed', () => { - systemPreferences.setAppLevelAppearance('dark'); - const appearance = systemPreferences.getAppLevelAppearance(); - expect(appearance).to.eql('dark'); + it('can be changed', async () => { + await expectDeprecationMessages( + () => { + systemPreferences.setAppLevelAppearance('dark'); + const appearance = systemPreferences.getAppLevelAppearance(); + expect(appearance).to.eql('dark'); + }, + "(electron) 'setAppLevelAppearance function' is deprecated and will be removed." + ); }); }); });