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

Merge pull request #2656 from atom/jl-std-docs-8

Browse source 
Standardize Docs: shell, synopsis, tray
This commit is contained in:
Jessica Lord 2015-09-01 19:10:10 -07:00
commit ae3ff4e1e3
3 changed files with 65 additions and 62 deletions
Download patch file Download diff file Expand all files Collapse all files

21
docs/api/shell.md
View file

@ -2,38 +2,43 @@
The `shell` module provides functions related to desktop integration. 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 ```javascript
var shell = require('shell'); var shell = require('shell');
shell.openExternal('https://github.com'); shell.openExternal('https://github.com');
``` ```
## shell.showItemInFolder(fullPath) ## Methods
The `shell` module has the following methods:
### `shell.showItemInFolder(fullPath)`
* `fullPath` String * `fullPath` String
Show the given file in a file manager. If possible, select the file. Show the given file in a file manager. If possible, select the file.
## shell.openItem(fullPath) ### `shell.openItem(fullPath)`
* `fullPath` String * `fullPath` String
Open the given file in the desktop's default manner. Open the given file in the desktop's default manner.
## shell.openExternal(url) ### `shell.openExternal(url)`
* `url` String * `url` String
Open the given external protocol URL in the desktop's default manner. (For 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 * `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. Play the beep sound.

20
docs/api/synopsis.md
View file

@ -1,18 +1,22 @@
# Synopsis # Synopsis
All of [node.js's built-in modules](http://nodejs.org/api/) are available in 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 Electron and third-party node modules also fully supported as well (including
[native modules](../tutorial/using-native-node-modules.md)). the [native modules](../tutorial/using-native-node-modules.md)).
Electron also provides some extra built-in modules for developing native Electron also provides some extra built-in modules for developing native
desktop applications. Some modules are only available on the main process, some 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. are only available in the renderer process (web page), and some can be used in
The basic rule is: if a module is GUI or low-level system related, then it should both processes.
be only available on the main process. You need to be familiar with the concept of
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) [main process vs. renderer process](../tutorial/quick-start.md#the-main-process)
scripts to be able to use those modules. 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 ```javascript
var app = require('app'); 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 renderer process is no different than a normal web page, except for the extra
ability to use node modules: ability to use node modules:
```html ```html

86
docs/api/tray.md
View file

@ -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. usually attached with a context menu.
```javascript ```javascript
@ -25,26 +25,33 @@ app.on('ready', function(){
__Platform limitations:__ __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. `GtkStatusIcon` will be used instead.
* On Linux distributions that only have app indicator support, you have to * On Linux distributions that only have app indicator support, you have to
install `libappindicator1` to make tray icon work. install `libappindicator1` to make the tray icon work.
* App indicator will only be showed when it has context menu. * App indicator will only be shown when it has a context menu.
* When app indicator is used on Linux, `clicked` event is ignored. * 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 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. rely on the `clicked` event and always attach a context menu to the tray icon.
## Class: Tray ## Class: Tray
`Tray` is an [EventEmitter][event-emitter]. `Tray` is an [EventEmitter][event-emitter].
### new Tray(image) ### `new Tray(image)`
* `image` [NativeImage](native-image.md) * `image` [NativeImage](native-image.md)
Creates a new tray icon associated with the `image`. 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: 'clicked'
* `event` Event * `event` Event
@ -52,7 +59,7 @@ Creates a new tray icon associated with the `image`.
* `shiftKey` Boolean * `shiftKey` Boolean
* `ctrlKey` Boolean * `ctrlKey` Boolean
* `metaKey` Boolean * `metaKey` Boolean
* `bounds` Object - the bounds of tray icon * `bounds` Object - the bounds of tray icon.
* `x` Integer * `x` Integer
* `y` Integer * `y` Integer
* `width` 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. __Note:__ The `bounds` payload is only implemented on OS X and Windows.
### Event: 'right-clicked' ### Event: 'right-clicked' _OS X_ _Windows_
* `event` Event * `event` Event
* `altKey` Boolean * `altKey` Boolean
* `shiftKey` Boolean * `shiftKey` Boolean
* `ctrlKey` Boolean * `ctrlKey` Boolean
* `metaKey` Boolean * `metaKey` Boolean
* `bounds` Object - the bounds of tray icon * `bounds` Object - the bounds of tray icon.
* `x` Integer * `x` Integer
* `y` Integer * `y` Integer
* `width` 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. Emitted when the tray icon is right clicked.
__Note:__ This is only implemented on OS X and Windows. ### Event: 'double-clicked' _OS X_ _Windows_
### Event: 'double-clicked'
* `event` Event * `event` Event
* `altKey` Boolean * `altKey` Boolean
@ -94,75 +99,68 @@ __Note:__ This is only implemented on OS X and Windows.
Emitted when the tray icon is double clicked. Emitted when the tray icon is double clicked.
__Note:__ This is only implemented on OS X and Windows. ### Event: 'balloon-show' _Windows_
### Event: 'balloon-show'
Emitted when the tray balloon shows. Emitted when the tray balloon shows.
__Note:__ This is only implemented on Windows. ### Event: 'balloon-clicked' _Windows_
### Event: 'balloon-clicked'
Emitted when the tray balloon is clicked. Emitted when the tray balloon is clicked.
__Note:__ This is only implemented on Windows. ### Event: 'balloon-closed' _Windows_
### Event: 'balloon-closed'
Emitted when the tray balloon is closed because of timeout or user manually Emitted when the tray balloon is closed because of timeout or user manually
closes it. closes it.
__Note:__ This is only implemented on Windows. ### Event: 'drop-files' _OS X_
### Event: 'drop-files'
* `event` * `event`
* `files` Array - the file path of dropped files. * `files` Array - the file path of dropped files.
Emitted when dragged files are dropped in the tray icon. 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 are
labeled as such.
### `Tray.destroy()`
Destroys the tray icon immediately. Destroys the tray icon immediately.
### Tray.setImage(image) ### `Tray.setImage(image)`
* `image` [NativeImage](native-image.md) * `image` [NativeImage](native-image.md)
Sets the `image` associated with this tray icon. Sets the `image` associated with this tray icon.
### Tray.setPressedImage(image) ### `Tray.setPressedImage(image)` _OS X_
* `image` [NativeImage](native-image.md) * `image` [NativeImage](native-image.md)
Sets the `image` associated with this tray icon when pressed on OS X. Sets the `image` associated with this tray icon when pressed on OS X.
### Tray.setToolTip(toolTip) ### `Tray.setToolTip(toolTip)`
* `toolTip` String * `toolTip` String
Sets the hover text for this tray icon. Sets the hover text for this tray icon.
### Tray.setTitle(title) ### `Tray.setTitle(title)` _OS X_
* `title` String * `title` String
Sets the title displayed aside of the tray icon in the status bar. Sets the title displayed aside of the tray icon in the status bar.
__Note:__ This is only implemented on OS X. ### `Tray.setHighlightMode(highlight)` _OS X_
### Tray.setHighlightMode(highlight)
* `highlight` Boolean * `highlight` Boolean
Sets whether the tray icon is highlighted when it is clicked. Sets whether the tray icon is highlighted when it is clicked.
__Note:__ This is only implemented on OS X. ### `Tray.displayBalloon(options)` _Windows_
### Tray.displayBalloon(options)
* `options` Object * `options` Object
* `icon` [NativeImage](native-image.md) * `icon` [NativeImage](native-image.md)
@ -171,19 +169,15 @@ __Note:__ This is only implemented on OS X.
Displays a tray balloon. Displays a tray balloon.
__Note:__ This is only implemented on Windows. ### `Tray.popUpContextMenu([position])` _OS X_ _Windows_
### Tray.popUpContextMenu([position]) * `position` Object (optional)- The pop up position.
* `position` Object - The pop position
* `x` Integer * `x` Integer
* `y` Integer * `y` Integer
The `position` is only available on Windows, and it is (0, 0) by default. 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 * `menu` Menu