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
Show stats 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.
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.

20
docs/api/synopsis.md
View file

@ -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 in the renderer process (web page), and some can be used in
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 renderer process is no different than a normal web page, except for the extra
ability to use node modules:
```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.
```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 are
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