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

Standardize tray

Browse source
This commit is contained in:
Jessica Lord 2015-08-28 22:46:39 -07:00
parent e8a04981bb
commit b1fc18f405
1 changed files with 40 additions and 46 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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 area
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