Windows

Overview

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 through the io.windows object.

The Live Examples section demonstrates using the Window Management API. To see the code and experiment with it, open the embedded examples directly in CodeSandbox.

Configuration

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:

Property Type Description
windowResponseTimeout number Sets the timeout in milliseconds that the io.Connect library will wait for a valid success response from the target window after the io.Connect library has been initialized and a window operation is being executed on the window object (e.g., myWindow.moveTo(200, 200)). If no response has been received within this period, the io.Connect library will assume that either the window isn't interop-enabled, or io.Connect hasn't been initialized yet. Note that this timeout is valid only for operations on the window object - it doesn't affect an io.windows.open() call, for example.
defaultWindowOpenBounds object Bounds object specifying default bounds for opening a new window or an app instance.

Opening Windows

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:

Parameter Description Examples
page Specifies which page to display. Accepts an integer as a value. The first page of the document has a value of 1. To open the PDF file to page 3, use page=3.
toolbar Whether to enable or disable the PDF toolbar. Accepts 0 or 1 as values. To hide the PDF toolbar, use toolbar=0.
zoom Specifies the zoom factor and also the vertical and horizontal scroll position of the page in regard to the top left corner of the window. Accepts integer or floating point values. To set the zoom factor to 150.5%, use zoom=150.5. To set the zoom factor to 120% and scroll the page 200px vertically and 100px horizontally, use zoom=120,200,100.
view Specifies the view mode of the page using values defined in the PDF language specification. See the possible values in the next table. Use the page parameter before view. To fit the page in the window, use view=Fit. To fit the page vertically, use view=FitV. To fit the page horizontally and scroll it 200px vertically, use view=FitH,200.

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

Value Description Example
Fit Fits the entire page horizontally and vertically in the window. If the vertical and horizontal magnification factors are different, the smaller one will be used for fitting the page. In the other dimension the page will be centered. view=Fit
FitV Fits the page vertically in the window. view=FitV
FitH Fits the page horizontally in the window. view=FitH
FitV,<left> Fits the page vertically and scrolls it horizontally from the left edge of the window with the specified integer or floating point value. view=FitV,200
FitH,<top> Fits the page horizontally and scrolls it vertically from the top edge of the window with the specified integer or floating point value. view=FitH,200

Finding Windows

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);

Window Settings

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:

Property Type Description
context object Context data for the new window.
height number Window height in pixels.
left number Distance of the top left window corner from the left edge of the screen in pixels.
relativeDirection "bottom" | "top" | "left" | "right" Direction for positioning the window relatively to the relativeTo window. Considered only if relativeTo is supplied.
relativeTo string The ID of the window that will be used to relatively position the new window. Can be combined with relativeDirection.
top number Distance of the top left window corner from the top edge of the screen in pixels.
width number Window width in pixels.

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);

Window Operations

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.

Context

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.

Window Events

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);

Live Examples

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.

Open in CodeSandbox

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.

Open in CodeSandbox

Reference

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