mirrors/electron
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages 1 Wiki Activity Actions 1

Standardize desktop env integration

Browse source
This commit is contained in:
Jessica Lord 2015-08-31 19:13:27 -07:00
parent 0e4ae6f864
commit c6269bf77a
1 changed files with 25 additions and 26 deletions
Download patch file Download diff file Expand all files Collapse all files

51
docs/tutorial/desktop-environment-integration.md
View file

@ -1,8 +1,8 @@
# Desktop environment integration # Desktop Environment Integration
Different operating systems provide different features on integrating desktop Different operating systems provide different features for integrating desktop
applications into their desktop environments. For example, on Windows 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 shortcuts in the JumpList of task bar, and on Mac,
applications can put a custom menu in the dock menu. applications can put a custom menu in the dock menu.
This guide explains how to integrate your application into those desktop This guide explains how to integrate your application into those desktop
@ -11,7 +11,7 @@ environments with Electron APIs.
## Recent documents (Windows & OS X) ## Recent documents (Windows & OS X)
Windows and OS X provide easy access to a list of recent documents opened by Windows and OS X provide easy access to a list of recent documents opened by
the application via JumpList and dock menu. the application via JumpList or dock menu, respectively.
__JumpList:__ __JumpList:__
@ -21,7 +21,7 @@ __Application dock menu:__
<img src="https://cloud.githubusercontent.com/assets/639601/5069610/2aa80758-6e97-11e4-8cfb-c1a414a10774.png" height="353" width="428" > <img src="https://cloud.githubusercontent.com/assets/639601/5069610/2aa80758-6e97-11e4-8cfb-c1a414a10774.png" height="353" width="428" >
To add a file to recent documents, you can use To add a file to recent documents, you can use the
[app.addRecentDocument][addrecentdocument] API: [app.addRecentDocument][addrecentdocument] API:
```javascript ```javascript
@ -29,29 +29,28 @@ var app = require('app');
app.addRecentDocument('/Users/USERNAME/Desktop/work.type'); app.addRecentDocument('/Users/USERNAME/Desktop/work.type');
``` ```
And you can use [app.clearRecentDocuments](clearrecentdocuments) API to empty You can use [app.clearRecentDocuments](clearrecentdocuments) API to empty
the recent documents list: the recent documents list:
```javascript ```javascript
app.clearRecentDocuments(); app.clearRecentDocuments();
``` ```
### Windows notes ### Windows Notes
In order to be able to use this feature on Windows, your application has to be In order to be able to use this feature on Windows, your application has to be
registered as a handler of the file type of the document, otherwise the file 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 won't appear in JumpList even after you have added it. You can find everything
on registering your application in [Application Registration][app-registration]. on registering your application in [Application Registration][app-registration].
When a user clicks a file from JumpList, a new instance of your application will 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.
be started with the path of the file added as a command line argument.
### OS X notes ### OS X Notes
When a file is requested from the recent documents menu, the `open-file` event When a file is requested from the recent documents menu, the `open-file` event
of `app` module would be emitted for it. of `app` module will be emitted for it.
## Custom dock menu (OS X) ## Custom Dock Menu (OS X)
OS X enables developers to specify a custom menu for the dock, which usually OS X enables developers to specify a custom menu for the dock, which usually
contains some shortcuts for commonly used features of your application: contains some shortcuts for commonly used features of your application:
@ -77,7 +76,7 @@ var dockMenu = Menu.buildFromTemplate([
app.dock.setMenu(dockMenu); app.dock.setMenu(dockMenu);
``` ```
## User tasks (Windows) ## User Tasks (Windows)
On Windows you can specify custom actions in the `Tasks` category of JumpList, On Windows you can specify custom actions in the `Tasks` category of JumpList,
as quoted from MSDN: as quoted from MSDN:
@ -104,7 +103,7 @@ __Tasks of Internet Explorer:__
![IE](http://i.msdn.microsoft.com/dynimg/IC420539.png) ![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 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 like application shortcuts such that when user clicks a task, a program will be
executed with specified arguments. executed with specified arguments.
To set user tasks for your application, you can use To set user tasks for your application, you can use
@ -124,7 +123,7 @@ app.setUserTasks([
]); ]);
``` ```
To clean your tasks list, just call `app.setUserTasks` with empty array: To clean your tasks list, just call `app.setUserTasks` with an empty array:
```javascript ```javascript
app.setUserTasks([]); app.setUserTasks([]);
@ -136,9 +135,9 @@ uninstalled.
## Thumbnail Toolbars ## Thumbnail Toolbars
On Windows, you can add a thumbnail toolbar with specified buttons in a taskbar On Windows you can add a thumbnail toolbar with specified buttons in a taskbar
layout of an application window. It provides users a way to access to a particualr layout of an application window. It provides users a way to access to a
window's command without restoring or activating the window. particular window's command without restoring or activating the window.
From MSDN, it's illustrated: From MSDN, it's illustrated:
@ -187,18 +186,18 @@ with an empty array:
win.setThumbarButtons([]); win.setThumbarButtons([]);
``` ```
## Unity launcher shortcuts (Linux) ## Unity Launcher Shortcuts (Linux)
In Unity, you can add custom entries to its launcher via modifying `.desktop` In Unity, you can add custom entries to its launcher via modifying the `.desktop`
file, see [Adding shortcuts to a launcher][unity-launcher]. file, see [Adding Shortcuts to a Launcher][unity-launcher].
__Launcher shortcuts of Audacious:__ __Launcher shortcuts of Audacious:__
![audacious](https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles?action=AttachFile&do=get&target=shortcuts.png) ![audacious](https://help.ubuntu.com/community/UnityLaunchersAndDesktopFiles?action=AttachFile&do=get&target=shortcuts.png)
## Progress bar in taskbar (Windows & Unity) ## Progress Bar in Taskbar (Windows & Unity)
On Windows, a taskbar button can be used to display a progress bar. This enables On Windows a taskbar button can be used to display a progress bar. This enables
a window to provide progress information to the user without the user having to a window to provide progress information to the user without the user having to
switch to the window itself. switch to the window itself.
@ -221,10 +220,10 @@ var window = new BrowserWindow({...});
window.setProgressBar(0.5); window.setProgressBar(0.5);
``` ```
## Represented file of window (OS X) ## Represented File of Window (OS X)
On OS X a window can set its represented file, so the file's icon can show in On OS X a window can set its represented file, so the file's icon can show in
the title bar, and when users Command-Click or Control-Click on the tile a path the title bar and when users Command-Click or Control-Click on the tile a path
popup will show. popup will show.
You can also set the edited state of a window so that the file icon can indicate You can also set the edited state of a window so that the file icon can indicate