From c0e728ab6ae82468c36ae527c7381079b8d038ae Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Thu, 7 Jan 2016 14:23:21 +0800 Subject: [PATCH] docs: Orgnize the options of BrowserWindow --- docs/api/browser-window.md | 218 ++++++++++++++++++++++++--------------------- 1 file changed, 114 insertions(+), 104 deletions(-) diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md index 8511ca7..8fb64b5 100644 --- a/docs/api/browser-window.md +++ b/docs/api/browser-window.md @@ -31,117 +31,127 @@ It creates a new `BrowserWindow` with native properties as set by the `options`. ### `new BrowserWindow([options])` -`options` Object (optional), properties: - -* `width` Integer - Window's width in pixels. Default is `800`. -* `height` Integer - Window's height in pixels. Default is `600`. -* `x` Integer - Window's left offset from screen. Default is to center the - window. -* `y` Integer - Window's top offset from screen. Default is to center the - window. -* `useContentSize` Boolean - The `width` and `height` would be used as web - page's size, which means the actual window's size will include window - frame's size and be slightly larger. Default is `false`. -* `center` Boolean - Show window in the center of the screen. -* `minWidth` Integer - Window's minimum width. Default is `0`. -* `minHeight` Integer - Window's minimum height. Default is `0`. -* `maxWidth` Integer - Window's maximum width. Default is no limit. -* `maxHeight` Integer - Window's maximum height. Default is no limit. -* `resizable` Boolean - Whether window is resizable. Default is `true`. -* `alwaysOnTop` Boolean - Whether the window should always stay on top of - other windows. Default is `false`. -* `fullscreen` Boolean - Whether the window should show in fullscreen. When - set to `false` the fullscreen button will be hidden or disabled on OS X. - Default is `false`. -* `skipTaskbar` Boolean - Whether to show the window in taskbar. Default is - `false`. -* `kiosk` Boolean - The kiosk mode. Default is `false`. -* `title` String - Default window title. Default is `"Electron"`. -* `icon` [NativeImage](native-image.md) - The window icon, when omitted on - Windows the executable's icon would be used as window icon. -* `show` Boolean - Whether window should be shown when created. Default is - `true`. -* `frame` Boolean - Specify `false` to create a - [Frameless Window](frameless-window.md). Default is `true`. -* `acceptFirstMouse` Boolean - Whether the web view accepts a single - mouse-down event that simultaneously activates the window. Default is `false`. -* `disableAutoHideCursor` Boolean - Whether to hide cursor when typing. Default - is `false`. -* `autoHideMenuBar` Boolean - Auto hide the menu bar unless the `Alt` - key is pressed. Default is `false`. -* `enableLargerThanScreen` Boolean - Enable the window to be resized larger - than screen. Default is `false`. -* `backgroundColor` String - Window's background color as Hexadecimal value, - like `#66CD00` or `#FFF`. This is only implemented on Linux and Windows. - Default is `#000` (black). -* `darkTheme` Boolean - Forces using dark theme for the window, only works on - some GTK+3 desktop environments. Default is `false`. -* `transparent` Boolean - Makes the window [transparent](frameless-window.md). - Default is `false`. -* `type` String - Specifies the type of the window, which applies - additional platform-specific properties. By default it's undefined and you'll - get a regular app window. Supported values: - * On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`, - `notification`. - * On OS X, possible types are `desktop`, `textured`. The `textured` type adds - metal gradient appearance (`NSTexturedBackgroundWindowMask`). The `desktop` - type places the window at the desktop background window level +* `options` Object + * `width` Integer - Window's width in pixels. Default is `800`. + * `height` Integer - Window's height in pixels. Default is `600`. + * `x` Integer - Window's left offset from screen. Default is to center the + window. + * `y` Integer - Window's top offset from screen. Default is to center the + window. + * `useContentSize` Boolean - The `width` and `height` would be used as web + page's size, which means the actual window's size will include window + frame's size and be slightly larger. Default is `false`. + * `center` Boolean - Show window in the center of the screen. + * `minWidth` Integer - Window's minimum width. Default is `0`. + * `minHeight` Integer - Window's minimum height. Default is `0`. + * `maxWidth` Integer - Window's maximum width. Default is no limit. + * `maxHeight` Integer - Window's maximum height. Default is no limit. + * `resizable` Boolean - Whether window is resizable. Default is `true`. + * `alwaysOnTop` Boolean - Whether the window should always stay on top of + other windows. Default is `false`. + * `fullscreen` Boolean - Whether the window should show in fullscreen. When + set to `false` the fullscreen button will be hidden or disabled on OS X. + Default is `false`. + * `skipTaskbar` Boolean - Whether to show the window in taskbar. Default is + `false`. + * `kiosk` Boolean - The kiosk mode. Default is `false`. + * `title` String - Default window title. Default is `"Electron"`. + * `icon` [NativeImage](native-image.md) - The window icon, when omitted on + Windows the executable's icon would be used as window icon. + * `show` Boolean - Whether window should be shown when created. Default is + `true`. + * `frame` Boolean - Specify `false` to create a + [Frameless Window](frameless-window.md). Default is `true`. + * `acceptFirstMouse` Boolean - Whether the web view accepts a single + mouse-down event that simultaneously activates the window. Default is `false`. + * `disableAutoHideCursor` Boolean - Whether to hide cursor when typing. Default + is `false`. + * `autoHideMenuBar` Boolean - Auto hide the menu bar unless the `Alt` + key is pressed. Default is `false`. + * `enableLargerThanScreen` Boolean - Enable the window to be resized larger + than screen. Default is `false`. + * `backgroundColor` String - Window's background color as Hexadecimal value, + like `#66CD00` or `#FFF`. This is only implemented on Linux and Windows. + Default is `#000` (black). + * `darkTheme` Boolean - Forces using dark theme for the window, only works on + some GTK+3 desktop environments. Default is `false`. + * `transparent` Boolean - Makes the window [transparent](frameless-window.md). + Default is `false`. + * `type` String - The type of window, default is normal window. See more about + this bellow. + * `titleBarStyle` String - The style of window title bar. See more about this + bellow. + * `webPreferences` Object - Settings of web page's features. See more about + this bellow. + +The possible values and behaviors of `type` option are platform dependent, +supported values are: + +* On Linux, possible types are `desktop`, `dock`, `toolbar`, `splash`, + `notification`. +* On OS X, possible types are `desktop`, `textured`. + * The `textured` type adds metal gradient appearance + (`NSTexturedBackgroundWindowMask`). + * The `desktop` type places the window at the desktop background window level (`kCGDesktopWindowLevel - 1`). Note that desktop window will not receive focus, keyboard or mouse events, but you can use `globalShortcut` to receive input sparingly. -* `titleBarStyle` String, OS X - specifies the style of window title bar. - This option is supported on OS X 10.10 Yosemite and newer. There are three - possible values: - * `default` or not specified, results in the standard gray opaque Mac title + +The `titleBarStyle` option is only supported on OS X 10.10 Yosemite and newer. +Possible values are: + +* `default` or not specified, results in the standard gray opaque Mac title bar. - * `hidden` results in a hidden title bar and a full size content window, yet +* `hidden` results in a hidden title bar and a full size content window, yet the title bar still has the standard window controls ("traffic lights") in the top left. - * `hidden-inset` results in a hidden title bar with an alternative look +* `hidden-inset` results in a hidden title bar with an alternative look where the traffic light buttons are slightly more inset from the window edge. -* `webPreferences` Object - Settings of web page's features, properties: - * `nodeIntegration` Boolean - Whether node integration is enabled. Default - is `true`. - * `preload` String - Specifies a script that will be loaded before other - scripts run in the page. This script will always have access to node APIs - no matter whether node integration is turned on or off. The value should - be the absolute file path to the script. - When node integration is turned off, the preload script can reintroduce - Node global symbols back to the global scope. See example - [here](process.md#event-loaded). - * `partition` String - Sets the session used by the page. If `partition` - starts with `persist:`, the page will use a persistent session available to - all pages in the app with the same `partition`. if there is no `persist:` - prefix, the page will use an in-memory session. By assigning the same - `partition`, multiple pages can share the same session. If the `partition` - is unset then default session of the app will be used. - * `zoomFactor` Number - The default zoom factor of the page, `3.0` represents - `300%`. Default is `1.0`. - * `javascript` Boolean - Enables JavaScript support. Default is `true`. - * `webSecurity` Boolean - When setting `false`, it will disable the - same-origin policy (Usually using testing websites by people), and set - `allowDisplayingInsecureContent` and `allowRunningInsecureContent` to - `true` if these two options are not set by user. Default is `true`. - * `allowDisplayingInsecureContent` Boolean - Allow an https page to display - content like images from http URLs. Default is `false`. - * `allowRunningInsecureContent` Boolean - Allow a https page to run - JavaScript, CSS or plugins from http URLs. Default is `false`. - * `images` Boolean - Enables image support. Default is `true`. - * `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default - is `true`. - * `webgl` Boolean - Enables WebGL support. Default is `true`. - * `webaudio` Boolean - Enables WebAudio support. Default is `true`. - * `plugins` Boolean - Whether plugins should be enabled. Default is `false`. - * `experimentalFeatures` Boolean - Enables Chromium's experimental features. - Default is `false`. - * `experimentalCanvasFeatures` Boolean - Enables Chromium's experimental - canvas features. Default is `false`. - * `directWrite` Boolean - Enables DirectWrite font rendering system on - Windows. Default is `true`. - * `blinkFeatures` String - A list of feature strings separated by `,`, like - `CSSVariables,KeyboardEventKey`. The full list of supported feature strings - can be found in the [setFeatureEnabledFromString][blink-feature-string] - function. + +The `webPreferences` option is an object that can have following properties: + +* `nodeIntegration` Boolean - Whether node integration is enabled. Default + is `true`. +* `preload` String - Specifies a script that will be loaded before other + scripts run in the page. This script will always have access to node APIs + no matter whether node integration is turned on or off. The value should + be the absolute file path to the script. + When node integration is turned off, the preload script can reintroduce + Node global symbols back to the global scope. See example + [here](process.md#event-loaded). +* `partition` String - Sets the session used by the page. If `partition` + starts with `persist:`, the page will use a persistent session available to + all pages in the app with the same `partition`. if there is no `persist:` + prefix, the page will use an in-memory session. By assigning the same + `partition`, multiple pages can share the same session. If the `partition` + is unset then default session of the app will be used. +* `zoomFactor` Number - The default zoom factor of the page, `3.0` represents + `300%`. Default is `1.0`. +* `javascript` Boolean - Enables JavaScript support. Default is `true`. +* `webSecurity` Boolean - When setting `false`, it will disable the + same-origin policy (Usually using testing websites by people), and set + `allowDisplayingInsecureContent` and `allowRunningInsecureContent` to + `true` if these two options are not set by user. Default is `true`. +* `allowDisplayingInsecureContent` Boolean - Allow an https page to display + content like images from http URLs. Default is `false`. +* `allowRunningInsecureContent` Boolean - Allow a https page to run + JavaScript, CSS or plugins from http URLs. Default is `false`. +* `images` Boolean - Enables image support. Default is `true`. +* `textAreasAreResizable` Boolean - Make TextArea elements resizable. Default + is `true`. +* `webgl` Boolean - Enables WebGL support. Default is `true`. +* `webaudio` Boolean - Enables WebAudio support. Default is `true`. +* `plugins` Boolean - Whether plugins should be enabled. Default is `false`. +* `experimentalFeatures` Boolean - Enables Chromium's experimental features. + Default is `false`. +* `experimentalCanvasFeatures` Boolean - Enables Chromium's experimental + canvas features. Default is `false`. +* `directWrite` Boolean - Enables DirectWrite font rendering system on + Windows. Default is `true`. +* `blinkFeatures` String - A list of feature strings separated by `,`, like + `CSSVariables,KeyboardEventKey`. The full list of supported feature strings + can be found in the [setFeatureEnabledFromString][blink-feature-string] + function. ## Events -- 2.7.4