From a2cc936a3b01f23b6f9c632307eda95f4bcf620f Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 22:28:30 -0700 Subject: [PATCH 1/4] Standardize shell --- docs/api/shell.md | 21 +++++++++++++-------- 1 file changed, 13 insertions(+), 8 deletions(-) diff --git a/docs/api/shell.md b/docs/api/shell.md index f0848875a9..662fa588f3 100644 --- a/docs/api/shell.md +++ b/docs/api/shell.md @@ -2,38 +2,43 @@ The `shell` module provides functions related to desktop integration. -An example of opening a URL in default browser: +An example of opening a URL in the user's default browser: ```javascript var shell = require('shell'); + shell.openExternal('https://github.com'); ``` -## shell.showItemInFolder(fullPath) +## Methods + +The `shell` module has the following methods: + +### `shell.showItemInFolder(fullPath)` * `fullPath` String Show the given file in a file manager. If possible, select the file. -## shell.openItem(fullPath) +### `shell.openItem(fullPath)` * `fullPath` String Open the given file in the desktop's default manner. -## shell.openExternal(url) +### `shell.openExternal(url)` * `url` String Open the given external protocol URL in the desktop's default manner. (For -example, mailto: URLs in the default mail user agent.) +example, mailto: URLs in the user's default mail agent.) -## shell.moveItemToTrash(fullPath) +### `shell.moveItemToTrash(fullPath)` * `fullPath` String -Move the given file to trash and returns boolean status for the operation. +Move the given file to trash and returns a boolean status for the operation. -## shell.beep() +### `shell.beep()` Play the beep sound. From e8a04981bbafd2ed707b1cc3be168d1f9762d128 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 22:46:31 -0700 Subject: [PATCH 2/4] Standardize synopsis --- docs/api/synopsis.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md index 10daf2b68e..4634151bfb 100644 --- a/docs/api/synopsis.md +++ b/docs/api/synopsis.md @@ -1,18 +1,22 @@ # Synopsis -All of [node.js's built-in modules](http://nodejs.org/api/) are available in -Electron, and third-party node modules are fully supported too (including the -[native modules](../tutorial/using-native-node-modules.md)). +All of [Node.js's built-in modules](http://nodejs.org/api/) are available in +Electron and third-party node modules also fully supported as well (including +the [native modules](../tutorial/using-native-node-modules.md)). Electron also provides some extra built-in modules for developing native desktop applications. Some modules are only available on the main process, some -are only available on the renderer process, and some can be used on both processes. -The basic rule is: if a module is GUI or low-level system related, then it should -be only available on the main process. You need to be familiar with the concept of +are only available on the renderer process (web page), and some can be used on +both processes. + +The basic rule is: if a module is +[GUI](https://en.wikipedia.org/wiki/Graphical_user_interface) or low-level +system related, then it should be only available on the main process. You need +to be familiar with the concept of [main process vs. renderer process](../tutorial/quick-start.md#the-main-process) scripts to be able to use those modules. -The main process script is just like a normal `node.js` script: +The main process script is just like a normal Node.js script: ```javascript var app = require('app'); @@ -26,7 +30,7 @@ app.on('ready', function() { }); ``` -The web page is no different than a normal web page, except for the extra +The render process is no different than a normal web page, except for the extra ability to use node modules: ```html From b1fc18f405a77aad212123888ed384f6583afe18 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 22:46:39 -0700 Subject: [PATCH 3/4] Standardize tray --- docs/api/tray.md | 86 ++++++++++++++++++++++-------------------------- 1 file changed, 40 insertions(+), 46 deletions(-) diff --git a/docs/api/tray.md b/docs/api/tray.md index a677727461..c9ebf20543 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -1,6 +1,6 @@ -# tray +# Tray -A `Tray` represents an icon in operating system's notification area, it is +A `Tray` represents an icon in an operating system's notification area, it is usually attached with a context menu. ```javascript @@ -25,26 +25,33 @@ app.on('ready', function(){ __Platform limitations:__ -* On Linux app indicator will be used if it is supported, otherwise +* On Linux the app indicator will be used if it is supported, otherwise `GtkStatusIcon` will be used instead. * On Linux distributions that only have app indicator support, you have to - install `libappindicator1` to make tray icon work. -* App indicator will only be showed when it has context menu. -* When app indicator is used on Linux, `clicked` event is ignored. + install `libappindicator1` to make the tray icon work. +* App indicator will only be shown when it has a context menu. +* When app indicator is used on Linux, the `clicked` event is ignored. -So if you want to keep exact same behaviors on all platforms, you should not -rely on `clicked` event and always attach a context menu to the tray icon. +If you want to keep exact same behaviors on all platforms, you should not +rely on the `clicked` event and always attach a context menu to the tray icon. ## Class: Tray `Tray` is an [EventEmitter][event-emitter]. -### new Tray(image) +### `new Tray(image)` * `image` [NativeImage](native-image.md) Creates a new tray icon associated with the `image`. +## Events + +The `Tray` module emits the following events: + +**Note:** Some events are only available on specific operating systems and are +labeled as such. + ### Event: 'clicked' * `event` Event @@ -52,7 +59,7 @@ Creates a new tray icon associated with the `image`. * `shiftKey` Boolean * `ctrlKey` Boolean * `metaKey` Boolean -* `bounds` Object - the bounds of tray icon +* `bounds` Object - the bounds of tray icon. * `x` Integer * `y` Integer * `width` Integer @@ -62,14 +69,14 @@ Emitted when the tray icon is clicked. __Note:__ The `bounds` payload is only implemented on OS X and Windows. -### Event: 'right-clicked' +### Event: 'right-clicked' _OS X_ _Windows_ * `event` Event * `altKey` Boolean * `shiftKey` Boolean * `ctrlKey` Boolean * `metaKey` Boolean -* `bounds` Object - the bounds of tray icon +* `bounds` Object - the bounds of tray icon. * `x` Integer * `y` Integer * `width` Integer @@ -77,9 +84,7 @@ __Note:__ The `bounds` payload is only implemented on OS X and Windows. Emitted when the tray icon is right clicked. -__Note:__ This is only implemented on OS X and Windows. - -### Event: 'double-clicked' +### Event: 'double-clicked' _OS X_ _Windows_ * `event` Event * `altKey` Boolean @@ -94,75 +99,68 @@ __Note:__ This is only implemented on OS X and Windows. Emitted when the tray icon is double clicked. -__Note:__ This is only implemented on OS X and Windows. - -### Event: 'balloon-show' +### Event: 'balloon-show' _Windows_ Emitted when the tray balloon shows. -__Note:__ This is only implemented on Windows. - -### Event: 'balloon-clicked' +### Event: 'balloon-clicked' _Windows_ Emitted when the tray balloon is clicked. -__Note:__ This is only implemented on Windows. - -### Event: 'balloon-closed' +### Event: 'balloon-closed' _Windows_ Emitted when the tray balloon is closed because of timeout or user manually closes it. -__Note:__ This is only implemented on Windows. - -### Event: 'drop-files' +### Event: 'drop-files' _OS X_ * `event` * `files` Array - the file path of dropped files. Emitted when dragged files are dropped in the tray icon. -__Note:__ This is only implemented on OS X. +## Methods -### Tray.destroy() +The `Tray` module has the following methods: + +**Note**: Some methods are only available on specific operating systems and area +labeled as such. + +### `Tray.destroy()` Destroys the tray icon immediately. -### Tray.setImage(image) +### `Tray.setImage(image)` * `image` [NativeImage](native-image.md) Sets the `image` associated with this tray icon. -### Tray.setPressedImage(image) +### `Tray.setPressedImage(image)` _OS X_ * `image` [NativeImage](native-image.md) Sets the `image` associated with this tray icon when pressed on OS X. -### Tray.setToolTip(toolTip) +### `Tray.setToolTip(toolTip)` * `toolTip` String Sets the hover text for this tray icon. -### Tray.setTitle(title) +### `Tray.setTitle(title)` _OS X_ * `title` String Sets the title displayed aside of the tray icon in the status bar. -__Note:__ This is only implemented on OS X. - -### Tray.setHighlightMode(highlight) +### `Tray.setHighlightMode(highlight)` _OS X_ * `highlight` Boolean Sets whether the tray icon is highlighted when it is clicked. -__Note:__ This is only implemented on OS X. - -### Tray.displayBalloon(options) +### `Tray.displayBalloon(options)` _Windows_ * `options` Object * `icon` [NativeImage](native-image.md) @@ -171,19 +169,15 @@ __Note:__ This is only implemented on OS X. Displays a tray balloon. -__Note:__ This is only implemented on Windows. +### `Tray.popUpContextMenu([position])` _OS X_ _Windows_ -### Tray.popUpContextMenu([position]) - -* `position` Object - The pop position +* `position` Object (optional)- The pop up position. * `x` Integer * `y` Integer The `position` is only available on Windows, and it is (0, 0) by default. -__Note:__ This is only implemented on OS X and Windows. - -### Tray.setContextMenu(menu) +### `Tray.setContextMenu(menu)` * `menu` Menu From 91c75d73dd2fbcdac7547d1a8bfa817047c0122e Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Tue, 1 Sep 2015 15:42:10 -0700 Subject: [PATCH 4/4] Text edits --- docs/api/synopsis.md | 4 ++-- docs/api/tray.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/api/synopsis.md b/docs/api/synopsis.md index 4634151bfb..21f4ff2aa4 100644 --- a/docs/api/synopsis.md +++ b/docs/api/synopsis.md @@ -6,7 +6,7 @@ the [native modules](../tutorial/using-native-node-modules.md)). Electron also provides some extra built-in modules for developing native desktop applications. Some modules are only available on the main process, some -are only available on the renderer process (web page), and some can be used on +are only available in the renderer process (web page), and some can be used in both processes. The basic rule is: if a module is @@ -30,7 +30,7 @@ app.on('ready', function() { }); ``` -The render process is no different than a normal web page, except for the extra +The renderer process is no different than a normal web page, except for the extra ability to use node modules: ```html diff --git a/docs/api/tray.md b/docs/api/tray.md index c9ebf20543..a673307804 100644 --- a/docs/api/tray.md +++ b/docs/api/tray.md @@ -123,7 +123,7 @@ Emitted when dragged files are dropped in the tray icon. The `Tray` module has the following methods: -**Note**: Some methods are only available on specific operating systems and area +**Note**: Some methods are only available on specific operating systems and are labeled as such. ### `Tray.destroy()`