More

The jump list is a configurable categorized list of actions that can be shown in the context menu when the user right-clicks on a Windows taskbar icon of an interop-enabled app or a group of such icons:

⚠️ Note that, currently, the jump list isn't available for web groups.

Configuration

The jump list can be enabled, disabled and configured globally and per app. The app definition will override the global system configuration.

⚠️ Note that the jump list configuration allows you to enable or disable the jump list and configure the predefined actions (e.g., change their names or icons), but in order to add custom jump list categories and actions for your apps, you must use the jump list API.

To configure the jump list system-wide, use the "jumpList" property of the "windows" top-level key in the system.json system configuration file of io.Connect Desktop. The following is the default system jump list configuration:

{
    "windows": {
        "jumpList": {
            "enabled": true,
            "categories": [
                {
                    "title": "Tasks",
                    "actions": [
                        {
                            "icon": "%IO_CD_ROOT_DIR%/assets/images/center.ico",
                            "type": "centerScreen",
                            "singleInstanceTitle": "Center on Primary Screen",
                            "multiInstanceTitle": "Center all on Primary Screen"
                        }
                    ]
                }
            ]
        }
    }
}

The "jumpList" object has the following properties:

Each object in the "categories" array has the following properties:

Each object in the "actions" array has the following properties:

To override the system configuration per app, use the "jumpList" property of the "details" top-level key in the app definition file. The following example demonstrates how to disable the jump list for an app:

{
    "title": "My App",
    "type": "window",
    "name": "my-app",
    "details": {
        "url": "https://downloadtestfiles.com/",
        "jumpList": {
            "enabled": false
        }
    }
}

Predefined Actions

To use a predefined action, set the "type" property of the action object to the respective value (see Jump List > Configuration). The following are the currently supported predefined actions:

• "centerScreen" - centers an app or a group of app instances on the primary screen. This action is extremely useful when you have many windows open on multiple displays and can't find the app you need. Use this action to find an app that: you may have moved to another screen or outside the screen bounds altogether; may be hidden behind other windows; may have been resized and become too small to notice; or may have simply blended visually with other apps:

• "newWorkspace" - opens a new Workspace. This action by default is part of the jump list for the Workspaces App. Clicking on the action opens a new empty Workspace in the last opened instance of the Workspaces App. If this action is part of the jump list for another app and the Workspaces App isn't currently open when the user clicks on the action, it will be started:

Jump List API

The jump list API is accessible via the IOConnectWindow object which describes an instance of an io.Connect Window:

const myWindow = io.windows.my();
// Check whether the jump list is enabled for the current window.
const isJumpListEnabled = await myWindow.jumpList.isEnabled();

Enable or Disable the Jump List

To enable or disable the jump list dynamically, use the setEnabled() method and pass a Boolean value as an argument:

const myWindow = io.windows.my();

// Checking whether the jump list is enabled for the current window.
const isJumpListEnabled = await myWindow.jumpList.isEnabled();

if (!isJumpListEnabled) {
    // Enabling the jump list.
    await myWindow.jumpList.setEnabled(true);
}

Categories

Jump list categories are used for grouping actions in a section under a common name. You can find a category by name, get a list of all available categories, create a new category or remove an existing one. The categories API is accessible via the jumpList.categories object.

To find a category by name, use the find() method:

const myCategory = await myWindow.jumpList.categories.find("My Category");

To get a list of all available categories, use the list() method:

const categoryList = await myWindow.jumpList.categories.list();

To create a category, use the create() method. Pass a title for the category and a list of JumpListActionSettings objects describing the actions in the category:

// Category settings.
const title = "My Category";
const actions = [
   {
        // Icon for the action. Must point to a local file.
        icon: "../images/action-one.ico",
        // Callback that will be executed when the user clicks on the action.
        callback: () => console.log("Action 1"),
        // Title of the action when there is a single instance with a single Windows taskbar icon.
        singleInstanceTitle: "Execute Action 1",
        // Title of the action when there are multiple instances with grouped Windows taskbar icons.
        multiInstanceTitle: "Execute Action 1 for All"
    },
    {
        icon: "../images/action-two.ico",
        callback: () => console.log("Action 2"),
        singleInstanceTitle: "Execute Action 2",
        multiInstanceTitle: "Execute Action 2 for All"
    }
];

// Creating a category.
await myWindow.jumpList.categories.create(title, actions);

To remove a category, use the remove() method and pass the category title as an argument:

await myWindow.jumpList.categories.remove("My Category");

Actions

Each JumpListCategory object has an actions property through which you can access the actions API. You can create, remove or list all available actions in the current category.

To get a list of all available actions in a category, use the list() method:

const myCategory = await myWindow.jumpList.categories.find("My Category");

const actions = await myCategory.actions.list();

To create an action in a category, use the create() method. Pass a list of JumpListActionSettings objects describing the actions.

The following example demonstrates creating an action in the "Tasks" category that will toggle the io.Connect theme:

// Finding a category.
const category = await myWindow.jumpList.categories.find("Tasks");
// Action settings.
const actions = [
    {
        icon: "../images/toggle-theme.ico",
        // This action will toggle the io.Connect theme.
        callback: async () => {
            const currentTheme = await io.themes.getCurrent();
            if (currentTheme.name === "dark") {
                io.themes.select("light");
            } else {
                io.themes.select("dark");
            }
        },
        singleInstanceTitle: "Toggle Theme",
        multiInstanceTitle: "Toggle Theme"
    }
];

// Creating actions for an existing category.
await category.actions.create(actions);

To remove one or more actions from a category, use the remove() method and pass a list of JumpListActionSettings objects to remove:

const actions = [
   {
        icon: "../images/action-one.ico",
        callback: () => console.log("Action 1"),
        singleInstanceTitle: "Execute Action 1",
        multiInstanceTitle: "Execute Action 1 for All"
    },
    {
        icon: "../images/action-two.ico",
        callback: () => console.log("Action 2"),
        singleInstanceTitle: "Execute Action 2",
        multiInstanceTitle: "Execute Action 2 for All"
    }
];

// Removing actions from a category.
await category.actions.remove(actions);

The Hotkeys API allows apps to register key combinations and receive notifications when a key combination is pressed by the user irrespective of whether the app is on focus or not. Hotkeys are useful for web apps that don't have access to system resources and can't register global shortcuts.

Configuration

To control the hotkeys behavior, use the "hotkeys" top-level key in the system.json system configuration file of io.Connect Desktop.

Example configuration:

{
    "hotkeys": {
        "enabled": true,
        "blacklist": ["appManager"],
        "reservedHotkeys": ["ctrl+c", "ctrl+p", "ctrl+s"]
    }
}

The "hotkeys" object has the following properties:

Hotkeys API

The Hotkeys API is accessible via the io.hotkeys object.

To register a hotkey, use the register() method:

// Define a hotkey.
const hotkeyDefinition = {
    hotkey: "shift+alt+c",
    description: "Open Client Details"
};

// This function will be invoked when the hotkey is pressed.
const hotkeyHandler = () => {
    io.appManager.application("Client Details").start();
};

// Register the hotkey.
await io.hotkeys.register(hotkeyDefinition, hotkeyHandler);

To remove a hotkey, use the unregister() and pass the value of the hotkey combination as an argument:

await io.hotkeys.unregister("shift+alt+c");

To remove all hotkeys registered by your app, use the unregisterAll() method:

await io.hotkeys.unregisterAll();

To check if your app has registered a specific hotkey, use the isRegistered() method:

// Returns a Boolean value.
const isRegistered = io.hotkeys.isRegistered("shift+alt+c");

Hotkeys View

There is a utility view that allows you to see all hotkeys registered by different apps. You can open it from the io.Connect Desktop tray icon menu - right-click on the tray icon to display the menu. When you click on the "Hotkeys" item you will see a list of the hotkeys registered by your app:

For a complete list of the available Hotkeys API methods and properties, see the Hotkeys API reference documentation.

io.Connect Desktop provides a way for apps to programmatically capture screenshots of the available monitors. Based on custom logic you can capture one or all monitors in order to save a snapshot of the visual state at a given moment.

Configuration

To enable display capturing you must add the "allowCapture" property to your app definition file and set it to true.

{
    "name": "MyApp",
    "type": "window",
    "allowCapture": true,
    "details": {
        "url": "http://localhost:3000"
    }
}

Displays API

The Displays API is accessible via the io.displays object.

All Displays

To get all displays, use the all() method. It returns an array of all available Display objects:

const allDsiplays = await io.displays.all();

Primary Display

You can get the primary display with the getPrimary() method:

// Returns the primary display.
const primaryDisplay =  await io.displays.getPrimary();

Example of finding and capturing the primary display:

const display = await io.displays.getPrimary();
const screenshot = await display.capture({ scale:0.5 });

Specific Display

To get a specific display, use the get() method. It accepts a display ID as an argument and resolves with a Display object:

const displayID = 2528732444;

// returns a display by ID
const display = await io.displays.get(displayID);

Capturing All Displays

To capture all displays, use the captureAll() method. It accepts a CaptureAllOptions object and returns a Base64 encoded string or an array of Base64 encoded strings depending on the specified combined option.

The following example demonstrates how to capture all available displays and combine the screenshots into a single image with width set to 2000 pixels. The aspect ratio of the combined images will be preserved (the omitted keepAspectRatio property in the size object defaults to true) and the images will be arranged the way you have arranged your displays from your operating system settings:

const screenshot = await io.displays.captureAll({ combined: true, size: { width: 2000 } });

The CaptureAllOptions object has the following properties:

Capturing Single Displays

To capture a single display, use the capture() method at top level of the API or on a Display instance.

When you use the capture() method at top level of the API, pass a CaptureOptions object. The following example demonstrates how to use the display ID to find and capture the desired display and also how to specify capturing options. The width and height of the output image will be half the width and height of the captured monitor. The captured image is returned as a Base64 encoded string:

const displayID = 2528732444;
const captureOptions = {
    id: displayID,
    size: { scale: 0.5 }
}

const screenshot = await io.displays.capture(captureOptions);

The CaptureOptions object has the following properties:

The ScaleOptions object has only one property - scale, which accepts a number. The value you pass to it specifies the size of the output image relative to the actual screen size. For instance, if you use scale: 0.5 the height and width of the output image will be half the height and width of the captured screen.

The AbsoluteSizeOptions object has the following properties:

When you use the capture() method of a Display instance, pass either a ScaleOptions or an AbsoluteSizeOptions object, specifying the size of the output image. The following example demonstrates how to find and capture all non-primary displays:

const screenshots = await Promise.all(
            // Get all displays.
            (await io.displays.all())
            // Filter out the primary display.
            .filter(display => !display.isPrimary)
            .map(display => display.capture({ scale: 0.5 })));

Capturing Windows & Window Groups

You can use the capture() method of an io.Connect Window instance or an io.Connect Window group to capture the respective window or window group. This method works also for minimized windows and window groups but doesn't work for hidden windows.

// Capture the current window.
const windowScreenshot = await io.windows.my().capture();

// Capture the current group.
const groupScreenshot = await io.windows.groups.my.capture();

Converting Display Bounds

Available since io.Connect Desktop 10.2

To convert bounds between the different coordinate systems, use the convertBounds() method of the Displays API. Pass a ConvertBoundsOptions object as a required argument. The method resolves with a ConvertBoundsResult object containing the converted bounds, the target coordinate system, and the target display:

const options = {
    bounds: { top: 100, left: 100, width: 400, height: 300 },
    // Coordinate system of the input bounds.
    type: "physical",
    // Coordinate system to which to convert the input bounds.
    targetType: "logical"
};

const { bounds, type, display } = await io.displays.convertBounds(options);

The following coordinate systems are supported, as described in theBoundsType enumeration:

Retrieving Displays by Bounds

Available since io.Connect Desktop 10.2

To retrieve a display by bounds, use the getByBounds() method of the Displays API. Pass a GetByBoundsOptions object as a required argument:

const options = {
    bounds: { top: 100, left: 100, width: 400, height: 300 },
    type: "logical"
};

const display = await io.displays.getByBounds(options);

Events

The onDisplayChanged() method allows you to handle the event that fires when a display has been modified - its resolution or position has changed, a display has been connected or disconnected, etc. Pass a handler that will be invoked each time a display changes and use the list of Display objects that it receives as an argument to react to the changes:

const handler = (displays) => {
    // React to DPI changes, display connected or disconnected, monitor position changed, etc.
    console.log(displays);
};

io.displays.onDisplayChanged(handler);

For a complete list of the available Displays API methods and properties, see the Displays API reference documentation.

Web apps can retrieve, filter, set and remove cookies programmatically by using the io.Connect Cookies API.

Configuration

By default, interop-enabled web apps aren't allowed to manipulate cookies. To allow an app to manipulate cookies, use the "allowCookiesManipulation" property of the "details" top-level key in the app definition file:

{
    "details": {
        "allowCookiesManipulation": true
    }
}

Cookies API

The Cookies API is accessible via the io.cookies object.

Get

To retrieve all cookies, use the get() method:

const allCookies = await io.cookies.get();

The get() method returns a list of Cookie objects.

To filter the cookies, pass a CookiesGetFilter object with the properties which you want to use as a filter.

The following example demonstrates filtering cookies by domain:

const filter = { domain: "interop.io" };

// Get a list of cookies for the same domain.
const filteredCookies = await io.cookies.get(filter);

The CookiesGetFilter object has the following optional properties, which you can use in any combination to filter the cookies:

Set

To create a cookie, use the set() method. It accepts as a required argument a CookiesSetDetails object with a required url property:

const cookie = {
    url: "https://example.com",
    name: "MyCookie",
    value: "42"
};

await io.cookies.set(cookie);

The CookiesSetDetails object has the following properties:

Remove

To remove a cookie, use the remove() method and pass the cookie URL and name:

const url = "https://example.com";
const name = "MyCookie";

await io.cookies.remove(url, name);

io.Connect apps can be allowed dynamic access to all available environment variables registered by the OS and the io.Connect framework via configuration.

ℹ️ For details on the environment variables registered by the io.Connect framework, see the Developers > Configuration > Overview > Environment Variables section.

Configuration

To allow an app to access all available environment variables, use the "allowEnvVars" property of the "details" top-level key in the app definition:

{
    "details": {
        "allowEnvVars": true
    }
}

Dynamic Access

To access all available environment variables registered by the OS and the io.Connect framework dynamically, use the env property of the iodesktop object injected in the global window object. The env property is an object containing all available environment variables as properties:

const envVars = iodesktop.env;

Object.entries(envVars).forEach((envVar) => {
    const [envVarName, envVarValue] = envVar;

    console.log(`${envVarName}: "${envVarValue}"`);
});

You can allow io.Connect web apps to manipulate the headers for web requests dynamically.

Configuration

To allow web apps to manipulate request headers dynamically, use the "allowHeadersManipulation" top-level key in the app definition:

{
    "allowHeadersManipulation": true
}

Dynamic Manipulation

To manipulate the request headers for web requests dynamically, use the customHeaders property of the iodesktop object injected in the global window object.

To set custom request headers, use the set() method. You can use the returned header ID later to retrieve or remove the header. The following example demonstrates how to set a custom header for all web requests originating from all apps and sent to any URL:

const header = { "My-Custom-Header": "custom-header-value" };

const headerId = await iodesktop.customHeaders.set(header);

You can also supply a web request filter as a second argument to set(), specifying which requests to target:

const header = { "My-Custom-Header": "custom-header-value" };
const filter = {
    urls: ["https://my-app.com/assets/*"],
    applications: ["my-app"],
    types: ["mainFrame", "image", "stylesheet"]
};

const headerId = await iodesktop.customHeaders.set(header, filter);

The filter object has the following properties:

You can use any combination of these properties to fine-tune the filter for matching web requests depending on your specific use case. The applications array enables you to filter the apps from which the web requests originate, while the urls array enables you to filter them based on their destination. The types array enables you to filter the web requests based on their type. Providing an empty array for any of the properties will prevent matching any web requests, effectively preventing all requests from being modified.

⚠️ Note that this feature is available only for apps of type "window". This means that using the applications array will work only for such apps. If you want to modify the request headers of other types of web apps (e.g., the Workspaces App or the Web Group App), use the urls array instead.

To retrieve all custom request headers, use the getAll() method:

const allCustomHeaders = await iodesktop.customHeaders.getAll();

To retrieve a specific header, use the get() method and pass its ID as an argument:

const header = await iodesktop.customHeaders.get(headerId);

To remove all custom request headers, use the removeAll() method:

await iodesktop.customHeaders.removeAll();

To remove a specific header, use the remove() method and pass its ID as an argument:

await iodesktop.customHeaders.remove(headerId);

You can configure the proxy settings on system level for all users, or allow io.Connect apps to manipulate them dynamically if different user groups must use different proxy settings.

Configuration

Available since io.Connect Desktop 9.3

⚠️ Note that the following proxy settings are fully aligned with the Electron proxy settings. For more details about the available settings and example usage, see the Electron documentation. If you are experiencing unresolvable problems with the Electron proxy settings, you can try using the settings described in the Legacy Settings section.

The proxy settings can be changed from the "proxy" top-level key in the system.json system configuration file of io.Connect Desktop:

{
    "proxy": {
        "mode": "pac_script",
        "pacScript": "https://my-pac-script.js"
    }
}

The "proxy" object has the following properties:

To allow an app to manipulate proxy settings dynamically, use the "allowProxySettingManipulation" property of the "details" top-level key in the app definition file:

{
    "details": {
        "allowProxySettingManipulation": true
    }
}

Dynamic Manipulation

To manipulate the proxy settings dynamically, use the iodesktop object injected in the global window object:

const settings = {
    mode: "pac_script",
    pacScript: "https://my-pac-script.js"
};

// Set proxy settings.
iodesktop.setProxySettings(settings);

// Get proxy settings.
const proxySettings = await iodesktop.getProxySettings();

The object passed as an argument to setProxySettings() has the same shape as the "proxy" object described in the Configuration section.

You can allow apps to access OS information (list of running processes, OS version, io.Connect start time) through their app definition. The information can then be retrieved through the iodesktop object injected in the global window object when the app is started.

Configuration

To allow an app to access OS information, set the "allowOSInfo" property to true in the "details" top-level key:

{
    "details": {
        "allowOSInfo": true
    }
}

Dynamic Access

To retrieve the necessary OS information, use the iodesktop object injected in the global window object:

// Returns a list of all running processes.
const processes = await iodesktop.os.getProcesses();

// Extracting the PID, name and start time of the first process from the list.
const { pid, name, startTime } = processes[0];

// Returns the OS version as a string.
const version = iodesktop.os.getVersion();

// Returns the io.Connect start time as a string - e.g., "2021-10-20T06:54:49.411Z".
const startTime = iodesktop.glue42StartTime;

To allow an app to clear the DNS or HTTP cache, use the "allowClearingCache" top-level key in the app definition file. Methods for clearing the cache are available on the iodesktop object injected in the global window object.

Allowing an app to clear cache:

{
    "allowClearingCache": true
}

Clearing HTTP and DNS cache:

// Clearing the HTTP cache.
await iodesktop.clearCache();

// Clearing the DNS cache.
await iodesktop.clearHostResolverCache();

Available since io.Connect Desktop 9.4

If you need to show or hide a window dynamically (e.g., an authentication app) but don't want to initialize the entire @interopio/desktop library, use the showWindow() and hideWindow() methods of the iodesktop object injected in the global window object:

// Hide a window.
await iodesktop.hideWindow();

// Show a hidden window.
await iodesktop.showWindow();

Available since io.Connect Desktop 9.7.1

To retrieve any of the system paths used by io.Connect Desktop, use the getPath() method of the iodesktop object injected in the global window object and pass as an argument one of the following string values:

The following example demonstrates retrieving the desktop directory for the current user:

const desktopDir = await iodesktop.getPath("desktop");

Available since io.Connect Desktop 10.0

To retrieve the platform version, use the uiVersion property of the iodesktop object injected in the global window object:

const platformVersion = iodesktop.uiVersion;

The uiVersion property will return the default platform version or the custom version specified in the "uiVersion" property of the system.json system configuration file of io.Connect Desktop.

ℹ️ For details on how to specify a custom platform version, see the Developers > Configuration > System > Platform Version section.