mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

docs: clean up dark mode related docs (#22489)

Browse source 
* 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
This commit is contained in:
Samuel Attard 2020-03-05 13:19:43 -08:00 • committed by GitHub
parent 3c19aee73c
commit 1811751c6c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 24 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/api/system-preferences.md
View file

@ -369,14 +369,6 @@ Returns `String` - Can be `dark`, `light` or `unknown`.
Gets the macOS appearance setting that is currently applied to your application, 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) 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)** **[Deprecated](modernization/property-updates.md)**
### `systemPreferences.getAppLevelAppearance()` _macOS_ _Deprecated_ ### `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, 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) 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.

37
docs/tutorial/mojave-dark-mode-guide.md
View file

@ -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/) 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 for all macOS computers. If your Electron app has a dark mode, you can make it follow the
follow the system-wide dark mode setting using [the nativeTheme api](../api/native-theme.md). 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 In macOS 10.15 Catalina, Apple introduced a new "automatic" dark mode option for all macOS computers.
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 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 ## Automatically updating the native interfaces
"Native Interfaces" include the file picker, window border, dialogs, context menus and more; basically anything where "Native Interfaces" include the file picker, window border, dialogs, context menus and more; basically,
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 anything where the UI comes from macOS and not your app. As of Electron 7.0.0, the default behavior
theming from the OS. If you wish to opt out you must set the `NSRequiresAquaSystemAppearance` key in the `Info.plist` file is to opt in to this automatic theming from the OS. If you wish to opt out and are using Electron
to `true`. Please note that once Electron starts building against the 10.14 SDK it will not be possible for you to opt > 8.0.0, you must set the `NSRequiresAquaSystemAppearance` key in the `Info.plist` file to `true`.
out of this theming. 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 ## 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 If your app has its own dark mode, you should toggle it on and off in sync with the system's dark
this by listening for the theme updated event on Electron's `nativeTheme` module. E.g. 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') const { nativeTheme } = require('electron')
nativeTheme.on('updated', function theThemeHasChanged () { nativeTheme.on('updated', function theThemeHasChanged () {
updateMyAppTheme(nativeTheme.shouldUseDarkColors) 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