From 682433028c8ebb5360f3ac0551f57f314aeb99ec Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Tue, 10 Nov 2015 17:43:29 +0800 Subject: [PATCH] docs: Clean up the desktop-environment-integration.md --- .../desktop-environment-integration.md | 68 +++++++++++++------ 1 file changed, 47 insertions(+), 21 deletions(-) diff --git a/docs/tutorial/desktop-environment-integration.md b/docs/tutorial/desktop-environment-integration.md index 08758d67933f..39f74ff10771 100644 --- a/docs/tutorial/desktop-environment-integration.md +++ b/docs/tutorial/desktop-environment-integration.md @@ -9,7 +9,11 @@ This guide explains how to integrate your application into those desktop environments with Electron APIs. ## Notifications (Windows, Linux, OS X) -All three operating systems provide means for applications to send notifications to the user. Electron conveniently allows developers to send notifications using the [JavaScript Notification API](https://notifications.spec.whatwg.org/), using the currently running operating system's native notification APIs to display it. + +All three operating systems provide means for applications to send notifications +to the user. Electron conveniently allows developers to send notifications with +the [HTML5 Notification API](https://notifications.spec.whatwg.org/), using +the currently running operating system's native notification APIs to display it. ```javascript var myNotificiation = new Notification('Title', { @@ -20,31 +24,50 @@ myNotification.onclick = function () { console.log('Notification clicked') } ``` -While code and user experience across operating systems are similar, but there are fine differences. -#### Windows - * On Windows 10, notifications "just work". - * On Windows 8.1 and Windows 8, a shortcut to your app, with a [System.AppUserModel.ID](https://msdn.microsoft.com/en-us/library/windows/desktop/dd391569(v=vs.85).aspx), must be installed to the Start screen. Note, however, that it does not need to be pinned to the Start screen. - * On Windows 7 and below, notifications are not supported. You can however send "balloon notifications" using the [Tray API](trayballoon). +While code and user experience across operating systems are similar, but there +are fine differences. -To use an image in your notification, pass a local image file (preferably `png`) in the `icon` property of your notification's options. The notification will still display if you submit and incorrect or `http/https`-based URL, but the image will not be displayed. +### Windows -``` +* On Windows 10, notifications "just work". +* On Windows 8.1 and Windows 8, a shortcut to your app, with a [Application User +Model ID][app-user-model-id], must be installed to the Start screen. Note, +however, that it does not need to be pinned to the Start screen. +* On Windows 7 and below, notifications are not supported. You can however send +"balloon notifications" using the [Tray API](tray-balloon). + +To use an image in your notification, pass a local image file (preferably `png`) +in the `icon` property of your notification's options. The notification will +still display if you submit and incorrect or `http/https`-based URL, but the +image will not be displayed. + +```javascript new Notification('Title', { body: 'Notification with icon', icon: 'file:///C:/Users/feriese/Desktop/icon.png' }); ``` -Keep furthermore in mind that the maximum length for the body is 250 characters, with the Windows team recommending that notifications should be kept to 200 characters. +Keep furthermore in mind that the maximum length for the body is 250 characters, +with the Windows team recommending that notifications should be kept to 200 +characters. -#### Linux -Notifications are sent using Ubuntu's Unity (and will obviously not be displayed if Unity is not running). For more information about Unity's on screen notifications, [check out the project page](https://unity.ubuntu.com/projects/notifyosd/). +### Linux -#### OS X -Notifications are straight-forward on OS X, you should however be aware of [Apple's Human Interface guidelines regarding notifications](https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/NotificationCenter.html). +Notifications are sent using `libnotify`, it can show notifications on any +desktop environment that follows [Desktop Notifications +Specification][notification-spec], including Cinnamon, Enlightenment, Unity, +GNOME, KDE. -Note that notifications are limited to 256 bytes in size - and will be truncated if you exceed that limit. +### OS X + +Notifications are straight-forward on OS X, you should however be aware of +[Apple's Human Interface guidelines regarding +notifications](https://developer.apple.com/library/mac/documentation/UserExperience/Conceptual/OSXHIGuidelines/NotificationCenter.html). + +Note that notifications are limited to 256 bytes in size - and will be truncated +if you exceed that limit. ## Recent documents (Windows & OS X) @@ -81,7 +104,8 @@ registered as a handler of the file type of the document, otherwise the file won't appear in JumpList even after you have added it. You can find everything on registering your application in [Application Registration][app-registration]. -When a user clicks a file from the JumpList, a new instance of your application will be started with the path of the file added as a command line argument. +When a user clicks a file from the JumpList, a new instance of your application +will be started with the path of the file added as a command line argument. ### OS X Notes @@ -192,10 +216,10 @@ __Thumbnail toolbar of Windows Media Player:__ ![player](https://i-msdn.sec.s-msft.com/dynimg/IC420540.png) -You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set thumbnail -toolbar in your application: +You can use [BrowserWindow.setThumbarButtons][setthumbarbuttons] to set +thumbnail toolbar in your application: -``` +```javascript var BrowserWindow = require('browser-window'); var path = require('path'); var win = new BrowserWindow({ @@ -226,8 +250,8 @@ win.setThumbarButtons([]); ## Unity Launcher Shortcuts (Linux) -In Unity, you can add custom entries to its launcher via modifying the `.desktop` -file, see [Adding Shortcuts to a Launcher][unity-launcher]. +In Unity, you can add custom entries to its launcher via modifying the +`.desktop` file, see [Adding Shortcuts to a Launcher][unity-launcher]. __Launcher shortcuts of Audacious:__ @@ -290,4 +314,6 @@ window.setDocumentEdited(true); [app-registration]: http://msdn.microsoft.com/en-us/library/windows/desktop/ee872121(v=vs.85).aspx [unity-launcher]: https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles#Adding_shortcuts_to_a_launcher [setthumbarbuttons]: ../api/browser-window.md#browserwindowsetthumbarbuttonsbuttons -[trayballoon]: ../api/tray.md#traydisplayballoonoptions-windows \ No newline at end of file +[tray-balloon]: ../api/tray.md#traydisplayballoonoptions-windows +[app-user-model-id]: https://msdn.microsoft.com/en-us/library/windows/desktop/dd378459(v=vs.85).aspx +[notification-spec]: https://developer.gnome.org/notification-spec/