Workspaces

The returned JSON will contain information for the main window of every application that is currently open and hasn't explicitly de-registered itself from the service. It will also contain positioning, tabbing and grouping information for each application. This data will be passed to restore, which will create the applications and position them appropriately.

If an application wishes to restore its child windows and store custom data, it must properly integrate with the layouts service by both registering generate and restore callbacks, and calling the ready function. If this is not done properly, workspace restoration may be disrupted.

import {workspaces} from 'openfin-layouts';
import {Workspace} from 'openfin-layouts/dist/client/workspaces';

async function saveCurrentWorkspace() {
   const workspaceObject: Workspace = await workspaces.generate();
   // Persist the workspaceObject in a location of your choosing
   saveWorkspace(workspaceObject);
   return workspaceObject;
}

When restoring a workspace, the service will refrain from passing the saved workspace to the application (via the setRestoreHandler callback) until after the application has used this function to signal that it is ready.

Note that by not calling this function, and workspace restore operation will hang indefinitely.

import {workspaces} from 'openfin-layouts';

workspaces.setRestoreHandler(someRestoreFunction);
workspaces.setGenerateHandler(someGenerateFunction);
workspaces.ready();

Restoration begins by reading the Workspace object, and determining what applications and windows are running or not.

If an application or child window is not up and running, the layouts service will create a transparent placeholder window for it, as an indication to the user that a window is in the process of loading. The placeholder window will listen for its corresponding window to come up, and subsequently close itself.

Once all placeholder windows are up, the layouts service will ungroup and un-tab any windows participating in restoration. This is done to prevent a window from dragging its group around the desktop, into a location that wasn't originally intended. Restore does not touch any windows that were not declared in the Workspace object.

Once all windows are ungrouped, the layouts service will then tab together all windows involved in a tabgroup. Placeholder windows are included in this tabbing step. Once a placeholder window's corresponding restored window comes up, that restored window takes the place of the placeholder window in the tabset.

Once all groups have been set up, the layouts service will then begin opening and positioning the applications and windows.

If an application is up and running, the layouts service will position it in its proper place. If the application isn't running, the layouts service will attempt to launch it after it has been launched. It is then positioned.

If the application has registered generate and restore callbacks, and called the ready function, the layouts service will send it its Workspace data. If an application has saved its child windows, it MUST create those child windows with the same names defined in its Workspace. If it does not do so, restore will fail.

Once all applications and child windows have been spun up and positioned, and all placeholder windows have been closed, the layouts service will then group all windows that were formerly snapped together.

Finally, the layouts service will send a 'workspace-restored' event to all windows, and complete restoration.

import {workspaces} from 'openfin-layouts';

workspaces.restore(workspaceObject).then(result => {
   // Promise resolves with result once the layout has been restored
   handleResult(result);
});

The callback will be invoked on each call to generate, and the return value (if anything is returned) will be saved as the workspace's customData property for this app within the generated Workspace.

import {workspaces} from 'openfin-layouts';

workspaces.setGenerateHandler(() => {
    // Return custom data
    return {currentStockSymbol: this._currentStockSymbol};
});

If an application has set a setRestoreHandler callback, and called the ready function, the layouts service will send it its Workspace data when the restore function is called, and wait for this function to return. If an application has saved its child windows, it MUST create those child windows with the same names defined in its Workspace. If those child windows are already up, position them in their proper location using the bounds given.

If this function does not return, or this function does not create the app's child windows appropriately, restore will hang indefinitely.

If the callback does not return a WorkspaceApp object, window grouping will be affected. The restore function reads the return value and uses it to continue restoration.

It is recommended that you restore/position the child windows defined in workspaceApp, and after those windows have been created, return that same workspaceApp object.

import {workspaces} from 'openfin-layouts';
import {WorkspaceApp, WorkspaceWindow} from 'openfin-layouts/dist/client/workspaces';

async function appRestoreHandler(workspaceApp: Workspace) {
    const ofApp = await fin.Application.getCurrent();
    const openWindows = await ofApp.getChildWindows();
    // Iterate through the child windows of the workspaceApp data
    const opened = workspaceApp.childWindows.map(async (childWinInfo: WorkspaceWindow, index: number) => {
        // Check for existence of the window
        let openChildWin = openWindows.find(w => w.identity.name === childWinInfo.name);
        if (!openChildWin) {
            openChildWin = await openChild(childWinInfo.name, childWinInfo.url);
        }
        // Create the OpenFin window with the same name
        // Position the window based on the data in the workspaceApp
        // The user provides this positioning function
        await positionWindow(childWinInfo, openChildWin);
    });

    // Wait for all windows to open and be positioned before returning
    await Promise.all(opened);
    return layoutApp;
}

workspaces.setRestoreHandler(appRestoreHandler);