From 21fa395b610e4d9df3e6a35c651028f9c05ed676 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Mon, 17 Nov 2014 21:40:07 +0800 Subject: [PATCH] docs: Add "Desktop environment integration" --- docs/README.md | 1 + .../desktop-environment-integration.md | 135 ++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 docs/tutorial/desktop-environment-integration.md diff --git a/docs/README.md b/docs/README.md index ed7d803b72da..0d00200def5c 100644 --- a/docs/README.md +++ b/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) diff --git a/docs/tutorial/desktop-environment-integration.md b/docs/tutorial/desktop-environment-integration.md new file mode 100644 index 000000000000..dd450e7e7901 --- /dev/null +++ b/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:__ + + + +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:__ + + + +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