docs: Add "Desktop environment integration"

docs/README.md

@@ -4,6 +4,7 @@
 * [Application distribution](tutorial/application-distribution.md)
 * [Application packaging](tutorial/application-packaging.md)
 * [Using native node modules](tutorial/using-native-node-modules.md)
+* [Desktop environment integration](tutorial/desktop-environment-integration.md)
 * [Debugging browser process](tutorial/debugging-browser-process.md)
 * [Using Selenium and WebDriver](tutorial/using-selenium-and-webdriver.md)
 * [DevTools extension](tutorial/devtools-extension.md)

docs/tutorial/desktop-environment-integration.md

@@ -0,0 +1,135 @@
+# Desktop environment integration
+
+Different operating systems provide different features on integrating desktop
+applications into their desktop environments, for example, on Windows
+applications can put shortcuts in the JumpList of task bar, and on Mac
+applications can put a custom menu in the dock menu.
+
+This guide introduces how to integrate your application into those desktop
+environments with atom-shell APIs.
+
+## Recent documents
+
+Windows and Mac OS X have provided easy access to recent documents opened by the
+application via JumpList and dock menu.
+
+__JumpList:__
+
+![JumpList Recent Files](http://i.msdn.microsoft.com/dynimg/IC420538.png)
+
+__Application dock menu:__
+
+<img src="https://cloud.githubusercontent.com/assets/639601/5069610/2aa80758-6e97-11e4-8cfb-c1a414a10774.png" height="274" width="332" >
+
+To add a file to recent documents, you can use `app.addRecentDocument` API:
+
+```javascript
+var app = require('app');
+app.addRecentDocument('/Users/aryastark/github/atom-shell/README.md');
+```
+
+And you can use `app.clearRecentDocuments` API to empty the recent documents
+list:
+
+```javascript
+app.clearRecentDocuments();
+```
+
+### Windows notes
+
+In order to be able to use this feature on Windows, your application has to be
+registered as 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 JumpList, a new instance of your application will
+be started with the path of file appended in command line.
+
+### OS X notes
+
+When a file is requested from the recent documents menu, the `open-file` event
+of `app` module would be emitted for it.
+
+## Custom dock menu (OS X)
+
+OS X enables developers to specify a custom menu for dock, which usually
+contains some shortcuts for commonly used features of your application:
+
+__Dock menu of Terminal.app:__
+
+<img src="https://cloud.githubusercontent.com/assets/639601/5069962/6032658a-6e9c-11e4-9953-aa84006bdfff.png" height="354" width="341" >
+
+To set your custom dock menu, you can use the `app.dock.setMenu` API, which is
+only available on OS X:
+
+```javascript
+var app = require('app');
+var Menu = require('menu');
+var dockMenu = Menu.buildFromTemplate([
+  { label: 'New Window', click: function() { console.log('New Window'); } },
+  { label: 'New Window with Settings', submenu: [
+    { label: 'Basic' },
+    { label: 'Pro'},
+  ]},
+  { label: 'New Command...'},
+]);
+app.dock.setMenu(dockMenu);
+```
+
+## User tasks (Windows)
+
+On Windows you can specify custom actions in the `Tasks` category of JumpList,
+as quoted from MSDN:
+
+> Applications define tasks based on both the program's features and the key
+> things a user is expected to do with them. Tasks should be context-free, in
+> that the application does not need to be running for them to work. They
+> should also be the statistically most common actions that a normal user would
+> perform in an application, such as compose an email message or open the
+> calendar in a mail program, create a new document in a word processor, launch
+> an application in a certain mode, or launch one of its subcommands. An
+> application should not clutter the menu with advanced features that standard
+> users won't need or one-time actions such as registration. Do not use tasks
+> for promotional items such as upgrades or special offers.
+>
+> It is strongly recommended that the task list be static. It should remain the
+> same regardless of the state or status of the application. While it is
+> possible to vary the list dynamically, you should consider that this could
+> confuse the user who does not expect that portion of the destination list to
+> change.
+
+__Tasks of Internet Explorer:__
+
+![IE](http://i.msdn.microsoft.com/dynimg/IC420539.png)
+
+Unlike the dock menu in OS X which is a real menu, user tasks in Windows work
+like application shortcuts that when user clicks a task a program would be
+executed with specified arguments.
+
+To set user tasks for your application, you can use `app.setUserTasks` API:
+
+```javascript
+var app = require('app');
+app.setUserTasks([
+  {
+    program: process.execPath,
+    arguments: '--new-window',
+    iconPath: process.execPath,
+    iconIndex: 0,
+    title: 'New Window'
+    description: 'Create a new winodw',
+  }
+]);
+```
+
+To clean your tasks list, just call `app.setUserTasks` with empty array:
+
+```javascript
+app.setUserTasks([]);
+```
+
+The user tasks will still show even after your application closes, so the icon
+and program path specified for a task should exist until your application is
+uninstalled.
+
+[app-registration]:http://msdn.microsoft.com/en-us/library/windows/desktop/ee872121(v=vs.85).aspx