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

feat: add new nativeTheme API (#19656)

Browse source 
* feat: add new nativeTheme API

* chore: deprecate and clean up old systemPreferences theme APIs in favor of new nativeTheme module

* chore: clean up and deprecate things per feedback

* chore: add tests for deprecate and clean up invert impl

* build: when is a boolean not a boolean???
This commit is contained in:
Samuel Attard 2019-08-14 13:42:55 -07:00 • committed by GitHub
parent 246187a20f
commit efa1818cb4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
16 changed files with 343 additions and 29 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/api/native-theme.md Normal file
View file

@ -0,0 +1,35 @@
# nativeTheme
> Read and respond to changes in Chromium's native color theme.
Process: [Main](../glossary.md#main-process), [Renderer](../glossary.md#renderer-process)
## Events
The `nativeTheme` module emits the following events:
### Event: 'updated'
Emitted when something in the underlying NativeTheme has changed. This normally
means that either the value of `shouldUseDarkColors`,
`shouldUseHighContrastColors` or `shouldUseInvertedColorScheme` has changed.
You will have to check them to determine which one has changed.
## Properties
The `nativeTheme` module has the following properties:
### `nativeTheme.shouldUseDarkColors` _Readonly_
A `Boolean` for if the OS / Chromium currently has a dark mode enabled or is
being instructed to show a dark-style UI.
### `nativeTheme.shouldUseHighContrastColors` _macOS_ _Windows_ _Readonly_
A `Boolean` for if the OS / Chromium currently has high-contrast mode enabled
or is being instructed to show a high-constrast UI.
### `nativeTheme.shouldUseInvertedColorScheme` _macOS_ _Windows_ _Readonly_
A `Boolean` for if the OS / Chromium currently has an inverted color scheme
or is being instructed to use an inverted color scheme.

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

@ -27,28 +27,34 @@ Returns:
* `event` Event
### Event: 'inverted-color-scheme-changed' _Windows_
### Event: 'inverted-color-scheme-changed' _Windows_ _Deprecated_
Returns:
* `event` Event
* `invertedColorScheme` Boolean - `true` if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is being used, `false` otherwise.
### Event: 'high-contrast-color-scheme-changed' _Windows_
**Deprecated:** Should use the new [`updated`](native-theme.md#event-updated) event on the `nativeTheme` module.
### Event: 'high-contrast-color-scheme-changed' _Windows_ _Deprecated_
Returns:
* `event` Event
* `highContrastColorScheme` Boolean - `true` if a high contrast theme is being used, `false` otherwise.
**Deprecated:** Should use the new [`updated`](native-theme.md#event-updated) event on the `nativeTheme` module.
## Methods
### `systemPreferences.isDarkMode()` _macOS_ _Windows_
### `systemPreferences.isDarkMode()` _macOS_ _Windows_ _Deprecated_
Returns `Boolean` - Whether the system is in Dark Mode.
**Note:** On macOS 10.15 Catalina in order for this API to return the correct value when in the "automatic" dark mode setting you must either have `NSRequiresAquaSystemAppearance=false` in your `Info.plist` or be on Electron `>=7.0.0`. See the [dark mode guide](../tutorial/mojave-dark-mode-guide.md) for more information.
**Deprecated:** Should use the new [`nativeTheme.shouldUseDarkColors`](native-theme.md#nativethemeshouldusedarkcolors-readonly) API.
### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_
Returns `Boolean` - Whether the Swipe between pages setting is on.
@ -342,14 +348,18 @@ Returns `String` - The standard system color formatted as `#RRGGBBAA`.
Returns one of several standard system colors that automatically adapt to vibrancy and changes in accessibility settings like 'Increase contrast' and 'Reduce transparency'. See [Apple Documentation](https://developer.apple.com/design/human-interface-guidelines/macos/visual-design/color#system-colors) for more details.
### `systemPreferences.isInvertedColorScheme()` _Windows_
### `systemPreferences.isInvertedColorScheme()` _Windows_ _Deprecated_
Returns `Boolean` - `true` if an inverted color scheme (a high contrast color scheme with light text and dark backgrounds) is active, `false` otherwise.
### `systemPreferences.isHighContrastColorScheme()` _macOS_ _Windows_
**Deprecated:** Should use the new [`nativeTheme.shouldUseInvertedColorScheme`](native-theme.md#nativethemeshoulduseinvertedcolorscheme-macos-windows-readonly) API.
### `systemPreferences.isHighContrastColorScheme()` _macOS_ _Windows_ _Deprecated_
Returns `Boolean` - `true` if a high contrast theme is active, `false` otherwise.
**Depreacted:** Should use the new [`nativeTheme.shouldUseHighContrastColors`](native-theme.md#nativethemeshouldusehighcontrastcolors-macos-windows-readonly) API.
### `systemPreferences.getEffectiveAppearance()` _macOS_
Returns `String` - Can be `dark`, `light` or `unknown`.
@ -365,7 +375,9 @@ 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.
### `systemPreferences.getAppLevelAppearance()` _macOS_
**[Deprecated](modernization/property-updates.md)**
### `systemPreferences.getAppLevelAppearance()` _macOS_ _Deprecated_
Returns `String` | `null` - Can be `dark`, `light` or `unknown`.
@ -375,7 +387,7 @@ You can use the `setAppLevelAppearance` API to set this value.
**[Deprecated](modernization/property-updates.md)**
### `systemPreferences.setAppLevelAppearance(appearance)` _macOS_
### `systemPreferences.setAppLevelAppearance(appearance)` _macOS_ _Deprecated_
* `appearance` String | null - Can be `dark` or `light`
@ -450,10 +462,25 @@ Returns an object with system animation settings.
### `systemPreferences.appLevelAppearance` _macOS_
A `String` property that determines the macOS appearance setting for
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
system default as well as the value of `getEffectiveAppearance`.
Possible values that can be set are `dark` and `light`, and possible return values are `dark`, `light`, and `unknown`.
This property is only available on macOS 10.14 Mojave or newer.
### `systemPreferences.effectiveAppearance` _macOS_ _Readonly_
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.