From 1811751c6cd6410b1c451f2c57d4785cb649107c Mon Sep 17 00:00:00 2001 From: Samuel Attard Date: Thu, 5 Mar 2020 13:19:43 -0800 Subject: [PATCH] docs: clean up dark mode related docs (#22489) * docs: clean up systemPreferences.effectiveAppearance text * Grammar fixes * Add links for Electron Packager & Electron Forge * Update Packager API links, given https://github.com/electron/electron-packager/pull/1131 * docs: clean up Dark Mode guide * Grammar fixes * Add links for Electron Packager & Electron Forge * docs: adjust based on Electron 8 using 10.14 SDK --- docs/api/system-preferences.md | 16 ----------- docs/tutorial/mojave-dark-mode-guide.md | 37 ++++++++++++++++--------- 2 files changed, 24 insertions(+), 29 deletions(-) diff --git a/docs/api/system-preferences.md b/docs/api/system-preferences.md index 6975ef35fc..9816acdadc 100644 --- a/docs/api/system-preferences.md +++ b/docs/api/system-preferences.md @@ -369,14 +369,6 @@ Returns `String` - Can be `dark`, `light` or `unknown`. Gets the macOS appearance setting that is currently applied to your application, maps to [NSApplication.effectiveAppearance](https://developer.apple.com/documentation/appkit/nsapplication/2967171-effectiveappearance?language=objc) -Please note that until Electron is built targeting the 10.14 SDK, your application's -`effectiveAppearance` will default to 'light' and won't inherit the OS preference. In -the interim in order for your application to inherit the OS preference you must set the -`NSRequiresAquaSystemAppearance` key in your apps `Info.plist` to `false`. If you are -using `electron-packager` or `electron-forge` just set the `enableDarwinDarkMode` -packager option to `true`. See the [Electron Packager API](https://github.com/electron/electron-packager/blob/master/docs/api.md#darwindarkmodesupport) -for more details. - **[Deprecated](modernization/property-updates.md)** ### `systemPreferences.getAppLevelAppearance()` _macOS_ _Deprecated_ @@ -478,11 +470,3 @@ A `String` property that can be `dark`, `light` or `unknown`. Returns the macOS appearance setting that is currently applied to your application, maps to [NSApplication.effectiveAppearance](https://developer.apple.com/documentation/appkit/nsapplication/2967171-effectiveappearance?language=objc) - -Please note that until Electron is built targeting the 10.14 SDK, your application's -`effectiveAppearance` will default to 'light' and won't inherit the OS preference. In -the interim in order for your application to inherit the OS preference you must set the -`NSRequiresAquaSystemAppearance` key in your apps `Info.plist` to `false`. If you are -using `electron-packager` or `electron-forge` just set the `enableDarwinDarkMode` -packager option to `true`. See the [Electron Packager API](https://github.com/electron/electron-packager/blob/master/docs/api.md#darwindarkmodesupport) -for more details. diff --git a/docs/tutorial/mojave-dark-mode-guide.md b/docs/tutorial/mojave-dark-mode-guide.md index b39e85a7de..41646bfebf 100644 --- a/docs/tutorial/mojave-dark-mode-guide.md +++ b/docs/tutorial/mojave-dark-mode-guide.md @@ -1,29 +1,40 @@ -# Mojave Dark Mode +# Supporting macOS Dark Mode In macOS 10.14 Mojave, Apple introduced a new [system-wide dark mode](https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/dark-mode/) -for all macOS computers. If your app does have a dark mode, you can make your Electron app -follow the system-wide dark mode setting using [the nativeTheme api](../api/native-theme.md). +for all macOS computers. If your Electron app has a dark mode, you can make it follow the +system-wide dark mode setting using [the `nativeTheme` api](../api/native-theme.md). -In macOS 10.15 Catalina, Apple introduced a new "automatic" dark mode option for all macOS computers. In order -for the `nativeTheme.shouldUseDarkColors` and `Tray` APIs to work correctly in this mode on Catalina you need to either have `NSRequiresAquaSystemAppearance` set to `false` in your `Info.plist` file or be on Electron `>=7.0.0`. +In macOS 10.15 Catalina, Apple introduced a new "automatic" dark mode option for all macOS computers. +In order for the `nativeTheme.shouldUseDarkColors` and `Tray` APIs to work correctly in this mode on +Catalina, you need to either have `NSRequiresAquaSystemAppearance` set to `false` in your +`Info.plist` file, or be on Electron `>=7.0.0`. Both [Electron Packager][electron-packager] and +[Electron Forge][electron-forge] have a [`darwinDarkModeSupport` option][packager-darwindarkmode-api] +to automate the `Info.plist` changes during app build time. ## Automatically updating the native interfaces -"Native Interfaces" include the file picker, window border, dialogs, context menus and more; basically anything where -the UI comes from macOS and not your app. The default behavior as of Electron 7.0.0 is to opt in to this automatic -theming from the OS. If you wish to opt out you must set the `NSRequiresAquaSystemAppearance` key in the `Info.plist` file -to `true`. Please note that once Electron starts building against the 10.14 SDK it will not be possible for you to opt -out of this theming. +"Native Interfaces" include the file picker, window border, dialogs, context menus and more; basically, +anything where the UI comes from macOS and not your app. As of Electron 7.0.0, the default behavior +is to opt in to this automatic theming from the OS. If you wish to opt out and are using Electron +> 8.0.0, you must set the `NSRequiresAquaSystemAppearance` key in the `Info.plist` file to `true`. +Please note that Electron 8.0.0 and above will not let your opt out of this theming, due to the use +of the macOS 10.14 SDK. ## Automatically updating your own interfaces -If your app has its own dark mode you should toggle it on and off in sync with the system's dark mode setting. You can do -this by listening for the theme updated event on Electron's `nativeTheme` module. E.g. +If your app has its own dark mode, you should toggle it on and off in sync with the system's dark +mode setting. You can do this by listening for the theme updated event on Electron's `nativeTheme` module. -```js +For example: + +```javascript const { nativeTheme } = require('electron') nativeTheme.on('updated', function theThemeHasChanged () { updateMyAppTheme(nativeTheme.shouldUseDarkColors) }) ``` + +[electron-forge]: https://www.electronforge.io/ +[electron-packager]: https://github.com/electron/electron-packager +[packager-darwindarkmode-api]: https://electron.github.io/electron-packager/master/interfaces/electronpackager.options.html#darwindarkmodesupport