Windows

Using the Window Management API, your app can easily open and manipulate browser windows. This allows you to transform your traditional single-window web app into a multi-window native-like web app. The Window Management API enables apps to:

• open multiple windows;
• manipulate the position and size of opened windows;
• pass context data upon opening new windows;
• listen for and handle events related to opening and closing windows;

The Window Management API is accessible via the io.windows object.

The Live Examples section demonstrates using the Window Management API.

Use the windows property of the configuration object when initializing the @interopio/browser-platform library in the Main app to specify custom settings for the Window Management library:

import IOBrowserPlatform from "@interopio/browser-platform";

const config = {
    licenseKey: "my-license-key",
    windows: {
        windowResponseTimeoutMs: 10000,
        defaultWindowOpenBounds: {
            top: 0,
            left: 0,
            width: 600,
            height: 600
        }
    }
};

const { io } = await IOBrowserPlatform(config);

Configuring the Window Management library is optional. The configuration object for the windows property has the following properties:

To open a new io.Connect Window, use the open() method:

const name = "io-connect-docs";
const url = "https://docs.interop.io";
// Specify location for the new window.
const options = {
    top: 200,
    left: 200
};

const ioWindow = await io.windows.open(name, url, options);

The name and url parameters are required. The window name must be unique. The third parameter is an optional Settings object which specifies various settings for the new io.Connect Window - bounds, relative position and context.

For all available settings when opening a new io.Connect Window, see the Window Settings section.

Opening PDF Files

To open a PDF file in an io.Connect Window, use the open() method. Pass the URL to the PDF file and optionally specify parameters in the URL for opening the PDF file:

// This will open the PDF file with the PDF toolbar turned off.
const PDF_URL = "https://url-to-pdf.com/file-name.pdf#toolbar=0";

await io.windows.open("PDF File", PDF_URL);

To specify parameters in the URL, use the following template:

<URL to PDF file>#<parameter>=<value>

To specify multiple parameters in the URL, use & to separate them:

<URL to PDF file>#<parameter>=<value>&<parameter>=<value>&<parameter>=<value>

⚠️ Note that #, & and = are special characters which you must not use in parameter values because they can't be escaped.

The following example will display page 3 of the PDF file, hide the PDF toolbar, set the zoom factor to 150% and scroll the page vertically and horizontally by 100px (pixels are relative to the zoom factor):

const PDF_URL = "https://url-to-pdf.com/file-name.pdf#page=3&toolbar=0&zoom=150,100,100";

await io.windows.open("PDF File", PDF_URL);

The following table lists all supported URL parameters for opening PDF files:

The following table lists the possible values for the view parameter:

All functions for finding io.Connect Windows return a WebWindow object (or a collection of such objects).

Listing

To obtain a collection of all io.Connect Windows, use the list() method:

const allWindows = io.windows.list();

Current Window

To get a reference to the current window, use the my() method:

const currentWindow = io.windows.my();

By ID

To find a window by ID, use the findById() method:

const ID = "2506_04";
const ioWindow = io.windows.findById(ID);

Provide window settings per window by passing a Settings object to the open() method:

const name = "io-connect-docs";
const url = "https://docs.interop.io";
// Specify location for the new window.
const options = {
    height: 640,
    width: 560,
    left: 100,
    top: 100,
    context: { io: 42 }
};

const ioWindow = await io.windows.open(name, url, options);

The Settings object has the following properties:

Relative Position

Position a new io.Connect Window relatively to an already existing io.Connect Window by providing the ID of the existing window and the relative direction:

const clientsWindow = io.windows.findById("3HI0hHjdSq");

const name = "clientportfolio";
const url = "http://localhost:22080/clientportfolio/index.html";
// Provide the existing window ID and the relative direction.
const options = {
    relativeTo: clientsWindow.id,
    relativeDirection: "right"
};

await io.windows.open(name, url, options);

The Window Management API enables you to control a WebWindow instance programmatically. Access or change various window settings using the provided properties and methods.

Title

To get the title of an io.Connect Window, use the getTitle() method of a WebWindow instance:

const winTitle = await myWindow.getTitle();

To set the title of a window, use the setTitle() method:

await myWindow.setTitle("New Title");

URL

To get the URL of an io.Connect Window, use the getURL() method of a WebWindow instance:

const winURL = await myWindow.getURL();

Bounds

The bounds of a window describe its position (top and left coordinates) and size (width and height) on the screen.

To get the bounds of an io.Connect Window, use the getBounds() method of a WebWindow instance:

const winBounds = await myWindow.getBounds();

To move or resize an io.Connect Window, use the moveTo(), resizeTo() or moveResize() methods.

To move a window:

// Top and left coordinates (in pixels) for the top-left window corner.
await myWindow.moveTo(200, 300);

To resize a window:

// Width and height (in pixels) for the window.
await myWindow.resizeTo(300, 400);

To move and/or resize a window:

// New bounds for the window. All properties are optional.
const bounds = {
    top: 200,
    left: 300,
    width: 300,
    height: 400
};

await myWindow.moveResize(bounds);

⚠️ Note that programmatically moving and resizing the window of the Main app isn't possible.

Focus

To bring a window on focus, use the focus() method:

await myWindow.focus();

⚠️ Note that programmatically focusing the window of the Main app isn't possible.

Close

To close an io.Connect Window, use the close() method of a WebWindow instance:

await myWindow.close();

⚠️ Note that programmatically closing the window of the Main app isn't possible.

Each io.Connect Window has a dedicated context. The window context is a JavaScript object which may contain any information regarding the window instance in the form of key/value pairs.

Contexts can be set/passed initially on window creation and updated at runtime. Context changes can be tracked by subscribing to an event which fires when the window context has been updated (see Window Events).

⚠️ Note that saving large volumes of custom data as window context (e.g., thousands of lines of table data) can lead to significant delays. A user usually has several (in some cases - many) running apps and/or Workspaces (which can also contain many apps) and if one or more of the apps saves large amounts of context data, this will significantly slow down the saving process (e.g., on shutdown or when saving a layout). Saving custom context works best with smaller amounts of data. If your app needs to save large amounts of data, you have to think about how to design this process better - for instance, you may store IDs, indices, etc., as context data, save the actual data to a database and when you restore the app, fetch the data using the data IDs saved as window context.

Get

To get the context of an io.Connect Window, use the getContext() method of a WebWindow instance:

const winContext = await myWindow.getContext();

Update

To update the context of an io.Connect Window, use the updateContext() method of a WebWindow instance:

const newContext = { io: 42 };

await myWindow.udpateContext(newContext);

This method will update the current context object with the provided properties and values, adding any new properties and updating the values of existing ones.

Set

To open an io.Connect Window with initially set context, use the context property of the Settings object:

const name = "io-connect-docs";
const url = "https://docs.interop.io";
// Specify window context.
const options = {
    context: { io: 42 }
};

const ioWindow = await io.windows.open(name, url, options);

To replace the current window context, use the setContext() method of a WebWindow instance:

const newContext = { io: 42 };
const winContext = await myWindow.setContext(newContext);

This method will completely overwrite the existing context object, replacing its current value with the specified one.

Methods for tracking io.Connect Window events are available at top-level of the Window Management API and on the WebWindow instance. Below are described the available window events with examples of how to handle them.

The window event methods return an unsubscribe function which you can use to stop tracking the respective event.

Window Added or Removed

To track the opening and closing of io.Connect Windows, use the onWindowAdded() and onWindowRemoved() methods of the Window Management API and pass handlers for the respective events:

const handlers = {
    onAdded: (ioWindow) => {
        console.log(`Window added: ${ioWindow.name}`);
    },

    onRemoved: (ioWindow) => {
        console.log(`Window removed: ${ioWindow.name}`);
    }
};

io.windows.onWindowAdded(handlers.onAdded);
io.windows.onWindowRemoved(handlers.onRemoved);

Context Update

To track updates of the context of an io.Connect Window, use the onContextUpdated() method of a WebWindow instance and pass an event handler:

const contextUpdatedHandler = (context, ioWindow) => {
    console.log(`The context of "${ioWindow.name}" has been updated: ${JSON.stringify(context)}`);
};

myWindow.onContextUpdated(contextUpdatedHandler);

Opening Windows

The app below demonstrates opening a new window with basic configuration (context and size) by using the open() method of the Window Management API.

Use the input fields in App A to assign a name (required) to the new window and set the window context and size. Click the "Open Window" button to open a new window.

Window Events

The apps below demonstrate handling window events - opening and closing windows.

On load, App A and App B subscribe for the onWindowAdded() and the onWindowRemoved() events of the Window Management API and will print to the page every time a new window is opened or an existing window is closed.

Open several new windows by using the input fields in App A to assign a name (required) to the new window and set the window context and size. Click the "Open Window" button to open a new window.

For a complete list of the available Window Management API methods and properties, see the Window Management API Reference Documentation.