electron/docs/api/system-preferences.md

165 lines
4.7 KiB
Markdown
Raw Normal View History

2016-04-25 06:36:38 +00:00
# systemPreferences
> Get system preferences.
```javascript
const {systemPreferences} = require('electron')
console.log(systemPreferences.isDarkMode())
```
2016-09-16 16:08:41 +00:00
## Events
The `systemPreferences` object emits the following events:
### Event: 'accent-color-changed' _Windows_
Returns:
* `event` Event
* `newColor` String - The new RGBA color the user assigned to be there system
accent color.
2016-09-16 16:08:41 +00:00
### Event: 'inverted-color-scheme-changed' _Windows_
Returns:
* `event` Event
* `invertedColorScheme` Boolean - `true` if a inverted color scheme, such as
a high contrast theme, is being used, `false` otherwise.
2016-09-16 16:08:41 +00:00
2016-04-25 06:36:38 +00:00
## Methods
2016-06-18 13:26:26 +00:00
### `systemPreferences.isDarkMode()` _macOS_
2016-04-25 06:36:38 +00:00
2016-10-06 10:03:37 +00:00
Returns `Boolean` - Whether the system is in Dark Mode.
2016-04-25 06:36:38 +00:00
### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_
Returns `Boolean` - Whether the Swipe between pages setting is on.
### `systemPreferences.postNotification(event, userInfo)` _macOS_
* `event` String
2016-09-20 21:26:55 +00:00
* `userInfo` Object
Posts `event` as native notifications of macOS. The `userInfo` is an Object
that contains the user information dictionary sent along with the notification.
### `systemPreferences.postLocalNotification(event, userInfo)` _macOS_
* `event` String
2016-09-20 21:26:55 +00:00
* `userInfo` Object
Posts `event` as native notifications of macOS. The `userInfo` is an Object
that contains the user information dictionary sent along with the notification.
2016-06-18 13:26:26 +00:00
### `systemPreferences.subscribeNotification(event, callback)` _macOS_
2016-04-25 06:36:38 +00:00
* `event` String
* `callback` Function
2016-06-18 13:26:26 +00:00
Subscribes to native notifications of macOS, `callback` will be called with
2016-05-18 05:40:19 +00:00
`callback(event, userInfo)` when the corresponding `event` happens. The
`userInfo` is an Object that contains the user information dictionary sent
along with the notification.
The `id` of the subscriber is returned, which can be used to unsubscribe the
`event`.
2016-04-25 06:36:38 +00:00
Under the hood this API subscribes to `NSDistributedNotificationCenter`,
2016-05-18 05:40:19 +00:00
example values of `event` are:
2016-04-25 06:36:38 +00:00
* `AppleInterfaceThemeChangedNotification`
* `AppleAquaColorVariantChanged`
* `AppleColorPreferencesChangedNotification`
* `AppleShowScrollBarsSettingChanged`
2016-06-18 13:26:26 +00:00
### `systemPreferences.unsubscribeNotification(id)` _macOS_
2016-04-25 06:36:38 +00:00
* `id` Integer
Removes the subscriber with `id`.
### `systemPreferences.subscribeLocalNotification(event, callback)` _macOS_
2016-08-25 17:52:19 +00:00
* `event` String
* `callback` Function
Same as `subscribeNotification`, but uses `NSNotificationCenter` for local defaults.
2016-08-22 18:47:55 +00:00
This is necessary for events such as `NSUserDefaultsDidChangeNotification`
### `systemPreferences.unsubscribeLocalNotification(id)` _macOS_
2016-08-25 17:52:19 +00:00
* `id` Integer
Same as `unsubscribeNotification`, but removes the subscriber from `NSNotificationCenter`.
2016-06-18 13:26:26 +00:00
### `systemPreferences.getUserDefault(key, type)` _macOS_
2016-04-25 06:36:38 +00:00
* `key` String
* `type` String - Can be `string`, `boolean`, `integer`, `float`, `double`,
`url`, `array`, `dictionary`
2016-04-25 06:36:38 +00:00
Get the value of `key` in system preferences.
2016-06-18 13:26:26 +00:00
This API reads from `NSUserDefaults` on macOS, some popular `key` and `type`s
2016-04-25 06:36:38 +00:00
are:
* `AppleInterfaceStyle: string`
* `AppleAquaColorVariant: integer`
* `AppleHighlightColor: string`
* `AppleShowScrollBars: string`
* `NSNavRecentPlaces: array`
* `NSPreferredWebServices: dictionary`
* `NSUserDictionaryReplacementItems: array`
2016-04-25 06:36:38 +00:00
### `systemPreferences.isAeroGlassEnabled()` _Windows_
This method returns `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):
```javascript
const {BrowserWindow, systemPreferences} = require('electron')
let browserOptions = {width: 1000, height: 800}
2016-04-25 06:36:38 +00:00
// Make the window transparent only if the platform supports it.
2016-04-30 15:50:04 +00:00
if (process.platform !== 'win32' || systemPreferences.isAeroGlassEnabled()) {
browserOptions.transparent = true
browserOptions.frame = false
2016-04-25 06:36:38 +00:00
}
// Create the window.
let win = new BrowserWindow(browserOptions)
2016-04-25 06:36:38 +00:00
// Navigate.
if (browserOptions.transparent) {
win.loadURL(`file://${__dirname}/index.html`)
2016-04-25 06:36:38 +00:00
} else {
// No transparency, so we load a fallback that uses basic styles.
win.loadURL(`file://${__dirname}/fallback.html`)
2016-04-25 06:36:38 +00:00
}
```
[dwm-composition]:https://msdn.microsoft.com/en-us/library/windows/desktop/aa969540.aspx
2016-09-16 16:08:41 +00:00
### `systemPreferences.getAccentColor()` _Windows_
2016-09-16 16:08:41 +00:00
Returns the users current system wide color preference in the form of an RGBA
hexadecimal string.
```js
const color = systemPreferences.getAccentColor() // `"aabbccdd"`
2016-09-16 16:08:41 +00:00
const red = color.substr(0, 2) // "aa"
const green = color.substr(2, 2) // "bb"
const blue = color.substr(4, 2) // "cc"
const alpha = color.substr(6, 2) // "dd"
```
### `systemPreferences.isInvertedColorScheme()` _Windows_
Returns `Boolean` - `true` if an inverted color scheme, such as a high contrast
theme, is active, `false` otherwise.