docs: Add "Desktop environment integration"
This commit is contained in:
Cheng Zhao
parent
afde383e28
commit
21fa395b61
2 changed files with 136 additions and 0 deletions
|
|
@ -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)
|
||||
|
|
|
|||
135
docs/tutorial/desktop-environment-integration.md
Normal file
135
docs/tutorial/desktop-environment-integration.md
Normal file
|
|
@ -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:__
|
||||
|
||||
|
||||
|
||||
__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:__
|
||||
|
||||
|
||||
|
||||
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
|
||||
Loading…
Reference in a new issue