electron/docs/tutorial/desktop-environment-integration.md

Desktop Environment Integration

Different operating systems provide different features for 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 explains how to integrate your application into those desktop environments with Electron APIs.

Notifications (Windows, Linux, macOS)

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, using the currently running operating system's native notification APIs to display it.

Note: Since this is an HTML5 API it is only available in the renderer process.

let myNotification = new Notification('Title', {
  body: 'Lorem Ipsum Dolor Sit Amet'
});

myNotification.onclick = () => {
  console.log('Notification clicked');
};

While code and user experience across operating systems are similar, 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 Application 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.

Furthermore, the maximum length for the notification body is 250 characters, with the Windows team recommending that notifications should be kept to 200 characters.

Linux

Notifications are sent using libnotify, it can show notifications on any desktop environment that follows Desktop Notifications Specification, including Cinnamon, Enlightenment, Unity, GNOME, KDE.

macOS

Notifications are straight-forward on macOS, you should however be aware of Apple's Human Interface guidelines regarding notifications.

Note that notifications are limited to 256 bytes in size - and will be truncated if you exceed that limit.

Recent documents (Windows & macOS)

Windows and macOS provide easy access to a list of recent documents opened by the application via JumpList or dock menu, respectively.

JumpList:

Application dock menu:

To add a file to recent documents, you can use the app.addRecentDocument API:

app.addRecentDocument('/Users/USERNAME/Desktop/work.type');

And you can use app.clearRecentDocuments API to empty the recent documents list:

app.clearRecentDocuments();

Windows Notes

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 won't appear in JumpList even after you have added it. You can find everything on registering your application in Application 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.

macOS Notes

When a file is requested from the recent documents menu, the open-file event of app module will be emitted for it.

Custom Dock Menu (macOS)

macOS enables developers to specify a custom menu for the 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 macOS:

const electron = require('electron');
const app = electron.app;
const Menu = electron.Menu;

const dockMenu = Menu.buildFromTemplate([
  { label: 'New Window', click() { 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 macOS which is a real menu, user tasks in Windows work like application shortcuts such that when user clicks a task, a program will be executed with specified arguments.

To set user tasks for your application, you can use app.setUserTasks API:

app.setUserTasks([
  {
    program: process.execPath,
    arguments: '--new-window',
    iconPath: process.execPath,
    iconIndex: 0,
    title: 'New Window',
    description: 'Create a new window'
  }
]);

To clean your tasks list, just call app.setUserTasks with an empty array:

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.

Thumbnail Toolbars

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 particular window's command without restoring or activating the window.

From MSDN, it's illustrated:

This toolbar is simply the familiar standard toolbar common control. It has a maximum of seven buttons. Each button's ID, image, tooltip, and state are defined in a structure, which is then passed to the taskbar. The application can show, enable, disable, or hide buttons from the thumbnail toolbar as required by its current state.

For example, Windows Media Player might offer standard media transport controls such as play, pause, mute, and stop.

Thumbnail toolbar of Windows Media Player:

You can use BrowserWindow.setThumbarButtons to set thumbnail toolbar in your application:

const {BrowserWindow} = require('electron');
const path = require('path');

let win = new BrowserWindow({
  width: 800,
  height: 600
});

win.setThumbarButtons([
  {
    tooltip: 'button1',
    icon: path.join(__dirname, 'button1.png'),
    click() { console.log('button1 clicked'); }
  },
  {
    tooltip: 'button2',
    icon: path.join(__dirname, 'button2.png'),
    flags: ['enabled', 'dismissonclick'],
    click() { console.log('button2 clicked.'); }
  }
]);

To clean thumbnail toolbar buttons, just call BrowserWindow.setThumbarButtons with an empty array:

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.

Launcher shortcuts of Audacious:

Progress Bar in Taskbar (Windows, macOS, Unity)

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 switch to the window itself.

On macOS the progress bar will be displayed as a part of the dock icon.

The Unity DE also has a similar feature that allows you to specify the progress bar in the launcher.

Progress bar in taskbar button:

To set the progress bar for a Window, you can use the BrowserWindow.setProgressBar API:

let win = new BrowserWindow({...});
win.setProgressBar(0.5);

Icon Overlays in Taskbar (Windows)

On Windows a taskbar button can use a small overlay to display application status, as quoted from MSDN:

Icon overlays serve as a contextual notification of status, and are intended to negate the need for a separate notification area status icon to communicate that information to the user. For instance, the new mail status in Microsoft Outlook, currently shown in the notification area, can now be indicated through an overlay on the taskbar button. Again, you must decide during your development cycle which method is best for your application. Overlay icons are intended to supply important, long-standing status or notifications such as network status, messenger status, or new mail. The user should not be presented with constantly changing overlays or animations.

Overlay on taskbar button:

To set the overlay icon for a window, you can use the BrowserWindow.setOverlayIcon API:

let win = new BrowserWindow({...});
win.setOverlayIcon('path/to/overlay.png', 'Description for overlay');

Represented File of Window (macOS)

On macOS 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 title a path popup will show.

You can also set the edited state of a window so that the file icon can indicate whether the document in this window has been modified.

Represented file popup menu:

To set the represented file of window, you can use the BrowserWindow.setRepresentedFilename and BrowserWindow.setDocumentEdited APIs:

let win = new BrowserWindow({...});
win.setRepresentedFilename('/etc/passwd');
win.setDocumentEdited(true);

Dragging files out of the window

For certain kinds of apps that manipulate on files, it is important to be able to drag files from Electron to other apps. To implement this feature in your app, you need to call webContents.startDrag(item) API on ondragstart event.

In web page:

<a href="#" id="drag">item</a>
<script type="text/javascript" charset="utf-8">
  document.getElementById('drag').ondragstart = (event) => {
    event.preventDefault()
    ipcRenderer.send('ondragstart', '/path/to/item')
  }
</script>

In the main process:

ipcMain.on('ondragstart', (event, filePath) => {
  event.sender.startDrag({
    file: filePath,
    icon: '/path/to/icon.png'
  })
})