From b1fc18f405a77aad212123888ed384f6583afe18 Mon Sep 17 00:00:00 2001 From: Jessica Lord Date: Fri, 28 Aug 2015 22:46:39 -0700 Subject: [PATCH] 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 a67772746128..c9ebf20543fe 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