Electron desktop environment integration

Different operating systems offer different features on their desktop applications. For example, a file that the app once opened on windows appears in the jump list on the taskbar, and on a Mac, the app can place a custom menu on the fish-eye menu.

This chapter will show you how to use Electron APIs to integrate your app and desktop environment together.

Recent Documents (Windows and OS X)

Windows and OS X provide a convenient way to get a list of recent documents by opening a jump list or fish-eye menu.

Jump list:

Fish Eye Menu:

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

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

Or you can use the app.clearRecentDocuments API to empty the list of recent files.

app.clearRecentDocuments();

Windows needs to be aware

In order for this feature to behave properly on Windows, your app needs to be registered as a handle to a file type, otherwise the file will not appear on the jump list until you register. You can find any instructions on registration in Application Registration.

OS X needs to be aware

When a file is requested by the most recent file list, the open-file module is issued. app

Custom Fish Eye Menu (OS X)

OS X allows developers to customize their own menus, often with shortcuts to common features.

The terminal in the menu

Use app.dock.setMenu API to set up your menu, which is only possible on OS X:

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)

In Windows, you can specifically define the behavior of the Tasks jump list, referencing MSDN documents:

Applications define tasks based on both the program's features and the key things a user is expected to do with them. T asks should be context-free, in that the application does not need to be running for them to work. T hey 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 d ocument in a word processor, launch an application in a certain mode, or launch one of its subcommands. A n 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. I t 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.

IE's task

Unlike OS X's fish-eye menu, user tasks on Windows behave more like a shortcut, such as when a user clicks on a task, a program is passed in to a specific parameter and runs.

You can use the app.setUserTasks API to set user tasks in your app:

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

Call app.setUserTasks pass in an empty array to clear your task list:

app.setUserTasks([]);

When your app closes, the user task will still appear, and the path to the icon and program specified by the task must exist before your app can be unloaded.

Thumbnail toolbar

In Windows, you can add a button to the taskbar as a thumbnail toolbar for your app. It provides a way for users to access commonly used windows and does not require recovery or activation of windows.

In MSDN, it is said:

This toolbar is simply the familiar standard toolbar common control. I t has a maximum of seven buttons. E ach 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 for Windows Media Player

You can use BrowserWindow.setThumbarButtons to set up your app's thumbnail toolbar.

var BrowserWindow = require('browser-window');
var path = require('path');
var win = new BrowserWindow({
  width: 800,
  height: 600
});
win.setThumbarButtons([
  {
    tooltip: "button1",
    icon: path.join(__dirname, 'button1.png'),
    click: function() { console.log("button2 clicked"); }
  },
  {
    tooltip: "button2",
    icon: path.join(__dirname, 'button2.png'),
    flags:['enabled', 'dismissonclick'],
    click: function() { console.log("button2 clicked."); }
  }
]);

Call BrowserWindow.setThumbarButtons and pass in an empty array to empty the thumbnail toolbar:

win.setThumbarButtons([]);

Unity launcher shortcut (Linux)

At Unity, you can add a shortcut to the custom runr by changing the .desktop file, see Add to a launcher for details.

Shortcuts to the Audacious Runr:

Progress bar for the taskbar (Windows and Unity)

In Windows, the progress bar can appear on top of a taskbar button. This provides progress information to the user without requiring the user to switch the app window.

Unity DE has the same characteristics, displaying a progress bar on the runr.

Progress bar on the taskbar:

The progress bar on the Unity runr

To set a progress bar for a window, you can call the BrowserWindow.setProgressBar API:

var window = new BrowserWindow({...});
window.setProgressBar(0.5);

In OS X, a window can set the file it displays, the file icon can appear in the title bar, and when the user Command-Click or Control-Click title bar, the file path pop-up window appears.

Display file pop-up menu:

You can call BrowserWindow.setRepresented Filename and BrowserWindow.setDocumentEdITED APIs:

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