Windows

Window Management

JavaScript

Opening Windows

The Window Management API can be accessed through glue.windows.

To open a new Glue42 Window, use the open() method:

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

const g42Window = await glue.windows.open(name, url, options);

The name and url parameters are required. The window name must be unique. The third parameter is an optional WindowCreateOptions object which specifies various settings for the new Glue42 Window - bounds, styles, mode, button settings and more. This method also accepts optional success and error callbacks as fourth and fifth parameters.

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

Handling the Browser window.open()

A system configuration option is available for handling popup windows created with the native browser window.open() call. Use the nativeWindowOpen property of the windows top-level key in the system.json file to control popup window behavior:

"windows": {
    ...
    "nativeWindowOpen": "browser"
}

The possible values for the nativeWindowOpen property are:

  • "off" - opening windows with window.open() is disabled;
  • "browser" - windows created with window.open() will be opened in the default browser;
  • "window" - (default) windows created with window.open() will be opened as Glue42 Windows;

When popup windows are opened as Glue42 Windows on the same domain as the parent window, you can control them with the Window Web API:

const newWindow = window.open("http://localhost:4242/clientlist/index.html");

newWindow.close();

Opening PDF Files

To open a PDF file in a Glue42 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 glue.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 cannot 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 glue.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 Glue42 Windows return a GDWindow object (or a collection of such objects).

Listing

To obtain a collection of all Glue42 Windows, use the list() method:

const allG42Windows = glue.windows.list();

Current Window

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

const currentWindow = glue.windows.my();

By Name

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

const name = "glue42-docs";
const g42Window = glue.windows.find(name);

By ID

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

const ID = "2506_04";
const g42Window = glue.windows.findById(ID);

Window Settings

Provide window settings per window by:

  • using the application configuration settings:
{
    "type": "window",
    "name": "glue42-docs",
    "details": {
        "url": "https://docs.glue42.com",
        "height": 640,
        "width": 560,
        "left": 100,
        "top": 100,
        "mode": "flat",
        "title": "Glue42 Documentation",
        "backgroundColor": "#1a2b30",
        "focus": false
    }
}
const name = "glue42-docs";
const url = "https://docs.glue42.com";
// Specify location for the new window.
const options = {
    height: 640,
    width: 560,
    left: 100,
    top: 100,
    mode: "flat",
    title: "Glue42 Documentation",
    backgroundColor: "#1a2b30",
    focus: false
};

const g42Window = await glue.windows.open(name, url, options);

The table below shows all available window settings:

Name Type Description Default Supported By Runtime Update Support
allowClose boolean If false, the window will not contain a "Close" button. true All Flat and HTML
allowCollapse boolean If false, the window will not contain a "Collapse" button. true All Flat and HTML
allowForward boolean If false, the window will not contain an activity related "Forward" button. true HTML None
allowLockUnlock boolean If false, the window will not contain a "Lock/Unlock" button. false All Flat and HTML
allowMaximize boolean If false, the window will not contain a "Maximize" button. true All Flat and HTML
allowMinimize boolean If false, the window will not contain a "Minimize" button. true All Flat and HTML
allowTabClose boolean If false, the tab header will not contain a "Close" button. true Tab None
allowUnstick boolean If false, the window will not unstick from other windows. true All None
autoAlign boolean If true, a snapped window will adjust its bounds to the same width/height of the window it has stuck to, and/or will occupy the space between other windows (if any). true All None
autoSnap boolean If true, when moving the window operation ends, the window will snap to one of the approaching edges of another window (if any edges of the other window are within the defined snapping distance). true All None
base64ImageSource string Image as Base64 string that will be used as a taskbar icon for the window. The supported formats are PNG, ICO, JPG, APNG. - All All
borderColor string Can be a color name such as "Red", or a hex-encoded RGB or ARGB value. - Flat None
collapseHeight number Defines the height of the window when collapsed (in pixels). System titlebar height Flat and HTML Flat and HTML
devToolsEnable boolean If true, allows opening a developer console (using F12) for the new window. true All None
downloadSettings Object Object that defines file download behavior in the window. - All None
downloadSettings.autoSave boolean If true, will auto save the file (without asking the user where to save it). If false, a system save dialog will appear. true All None
downloadSettings.autoOpenPath boolean If true, will open the folder that contains the downloaded file after the download is completed. false All None
downloadSettings.autoOpenDownload boolean If true, will open the download file after the download is completed. false All None
downloadSettings.enable boolean If true, enables the window to download files. true All None
downloadSettings.enableDownloadBar boolean If true, a download bar tracking the progress will appear at the bottom of the window when downloading. If false, the download process will be invisible. true All None
downloadSettings.path string Path where the downloaded file will be saved. Due to security reasons, it is only possible to provide two download paths: the Windows "Temp" or "Downloads" folder. - All None
focus boolean If false, the window will not be on focus when created. true All All
hasMoveAreas boolean If false, the window cannot be moved. true Flat and HTML Flat
hasSizeAreas boolean If false, the window cannot be resized by dragging its borders, maximizing, etc. true Flat and HTML Flat
height number Window height (in pixels). 400 All All
hidden boolean If true, the window will be started as a hidden window. false All All
historyNavigationEnabled boolean If true, this will allow the users to navigate back (CTRL + Left) and forward (CTRL + Right) through the web page history. GLOBAL CONFIG All None
isChild boolean If true, the window will open as a child window, sharing the lifetime and the environment of the opener. false All None
isCollapsed boolean If true, the window will start collapsed. false All None
isSticky boolean If true, the window will stick to other Glue42 Windows forming groups. true All All
left number Distance of the top left window corner from the left edge of the screen (in pixels). 0 All All
maxHeight number Specifies the maximum window height (in pixels). - All All
maxWidth number Specifies the maximum window width (in pixels). - All All
minHeight number Specifies the minimum window height (in pixels). 30 All All
minWidth number Specifies the minimum window width (in pixels). 50 All All
mode string The type of the Glue42 Window. Possible values are "flat", "tab" and "html". "flat" - None
moveAreaThickness string How much of the window area is to be considered as a moving area (meaning you can move the window by grabbing it). The string value corresponds to the left, top, right and bottom borders. "0, 12, 0, 0" HTML None
moveAreaTopMargin string Margin for the top window move area. The string value corresponds to the left, top, right and bottom borders of the move area. Setting moveAreaTopMargin to "10, 0, 0, 10" will take away 10 pixels from the left and the right side of the move area. "0, 0, 0, 0" HTML None
onTop boolean If true, the window will appear on top of the z-order. false All None
relativeDirection string Direction ("bottom", "top", "left", "right") of positioning the window relatively to the relativeTo window. Considered only if relativeTo is supplied. "right" All None
relativeTo string The ID of the window that will be used to relatively position the new window. Can be combined with relativeDirection. - All None
showInTaskbar boolean If false, the window will not appear on the Windows taskbar. true All None
showTitleBar boolean Determines whether the window will have a title bar. true Flat None
sizeAreaThickness string How much of the window area is to be considered as a sizing area (meaning you can resize the window using that area). The string value corresponds to the left, top, right and bottom borders. "5, 5, 5, 5" HTML None
snappingEdges string Specifies the active Glue42 Window snapping edges. Possible values are: "top", "left", "right", "bottom", "all" or any combination of them (e.g., "left, right"). "all" All None
startLocation string Specifies the start window location. Possible options are "Automatic" (The Glue42 Window decides where it will be positioned) and "CenterScreen". "Automatic" All None
stickyFrameColor string Specifies the Glue42 Window frame color. Accepts hex color as a string ("#666666") or named HTML colors ("red"). "#5b8dc9" All All
stickyGroup string If set, the Glue42 Window can only stick to windows that have the same group. "Any" All None
tabGroupId string Specifies the tab group ID. If two or more tab windows are defined with the same ID, they will be hosted in the same tab window. "Automatic" Tab None
tabIndex number Specifies the tab position index. Tab windows in the same tab group are ordered by their position index. Use negative index to make the tab active. - Tab None
tabSelected boolean Whether the tab is selected. false Tab None
tabTitle string Sets the tab title. "" Tab Tab
tabToolTip string Sets the tab tooltip. "" Tab Tab
title string Sets the window title. To work properly, there should be a <title> HTML tag in the page. - All All
top number Distance of the top left window corner from the top edge of the screen (in pixels). 0 All All
url string The URL of the app to be loaded in the new window. - All All
useRandomFrameColor boolean If true, this will set a random (from a predefined list of colors) frame color to the new window. false All None
width number Window width (in pixels). 400 All All
windowName string The name of the window. - All None
windowState string If set, the window will start in the specified state ("maximized", "minimized", "normal"). "normal" All All

Mode

Three window modes are supported for web applications - flat, tab and HTML. Specify the window mode in the WindowCreateOptions object when opening a new Glue42 Window:

const name = "Glue42 Docs";
const url = "https://docs.glue42.com";
// Specify window mode.
const options = {
    mode: "tab"
};

const g42Window = await glue.windows.open(name, url, options);

Relative Position

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

const clientsWindow = glue.windows.find("clientlist");

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 glue.windows.open(name, url, options);

And the result:

Opening a window relative to another window

Taskbar Icon

To specify an icon for the Glue42 Window, provide an image as a base64 encoded string in the WindowCreateOptions object:

const name = "Glue42 Docs";
const url = "https://docs.glue42.com";
// Specify taskbar icon.
const options = {
    base64ImageSource: "R0lGODlhPQBEAPeoAJosM//AwO/AwH..."
};

const g42Window = await glue.windows.open(name, url, options);

To get the taskbar icon of the current window:

const myWindow = glue.windows.my();
const icon = await myWindow.getIcon();

To change the taskbar icon of the current window:

const myWindow = glue.windows.my();
// Image encoded as a `base64` string.
const newIcon = "R0lGODlhPQBEAPeoAJosM//AwO/AwH...";

await myWindow.setIcon(newIcon);

Downloads

To define the window behavior when downloading files, use the donwloadSettings property of the WindowCreateOptions object. It accepts a DownloadSettings object as a value:

const name = "Glue42 Docs - test app";
const url = "https://docs.glue42.com/assets/js-test-app.zip";
// Specify window download behavior.
const options = {
    downloadSettings: {
        autoSave: true,  
        autoOpenDownload: true
    }
};

const g42Window = await glue.windows.open(name, url, options);

Window Operations

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

Stickiness

The Glue42 Window stickiness enables users to easily organize the windows on their desktop in visual groups.

Window stickiness is enabled by default, but can be controlled programmatically and through application configuration. The Sticky button (disabled by default) in the window header allows the users to toggle the stickiness of individual windows from the UI:

Stickiness

When the window is in a tab group, the Sticky button controls the stickiness of all windows in the tab group and of the group itself:

Stickiness group

If you drop a window in a tab group, it will assume the stickiness mode of the tab group and will remain in this mode after you tear it out of the tab group:

Stickiness tabs

For details on how to enable the Sticky button through system configuration, see the Developers: Glue42 Windows section.

To set the stickiness or the visibility of the Sticky button programmatically on a global level, use the configure() method. Pass a WindowsConfiguration object with a sticky and showStickyButton properties set to boolean values:

// Turn off the stickiness and hide the Sticky button globally.
const windowsConfig = { 
    sticky: false,
    showStickyButton: false
};

await glue.windows.configure(windowsConfig);

To set the stickiness of a Glue42 Window instance, use the setSticky() method and pass a boolean value as an argument:

const myWindow = glue.windows.my();

// Turn off the stickiness for the current window.
await myWindow.setSticky(false);

To check whether the window is sticky, use the isSticky property of a GDWindow instance:

// Returns a boolean value.
const isSticky = myWindow.isSticky;

Title

To get the title of a Glue42 Window, use the title property or the getTitle() method of a GDWindow instance:

const title = myWindow.title;
// or
const winTitle = await myWindow.getTitle();

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

await myWindow.setTitle("New Title");

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 a Glue42 Window, use the bounds property or the getBounds() method of a GDWindow instance:

const bounds = myWindow.bounds;
// or
const winBounds = await myWindow.getBounds();

To move or resize a Glue42 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);

Placement

The placement feature of the Window Management API provides a way for a Glue42 Window to occupy a specific position on the screen. This position can be set only once - initially, on window creation, or can be kept throughout the entire lifetime of the window. The placement feature solves the problem of reacting adequately to changes of the screen resolution or the size of the application virtualization window hosting the Glue42 Window, ensuring that the Glue42 Window always stays at the desired screen position and with the desired dimensions. This is especially useful if you are developing a toolbar or a notifications panel that must always stay at the same position on the screen.

Window placement is controlled through the application configuration (see the placement property in the application.json schema) and programmatically.

To get the current placement settings for a window, use the placementSettings property of a GDWindow instance:

const placementSettings = myWindow.placementSettings;

To place a window at a specific position on the screen, use the place() method of a GDWindow instance and pass a PlacementSettings object as an argument.

The following example shows how to place the window at the top of the screen, stretched horizontally (horizontalAlignment defaults to "stretch" when verticalAlignment is set, see the Placement Settings table below) and with height set to 40 pixels. The snapped property is set to true in order to instruct Glue42 Enterprise that this Glue42 Window must always occupy that position, even when the screen resolution changes or the application virtualization window hosting it is resized:

const settings = {
    snapped: true,
    verticalAlignment: "top",
    height: 40
};

await myWindow.place(settings);

Note that the settings specified in the place() method won't be merged with the existing placement settings (if any) but will entirely overwrite them. If snapped is set to true, the place() method will also overwrite the settings saved in the Application Default layout (see Layouts).

The following table describes the properties of the PlacementSettings object:

Property Accepts Description Required
snapped boolean If true, the Glue42 Window will remain snapped to the specified screen position even in cases of resolution changes, window visibility changes or when the application virtualization window hosting the Glue42 Window has been resized. However, this doesn't include any API calls or manual user interaction which affect the window placement or bounds. If false, the window will be positioned at the specified screen location only once when created. Yes
verticalAlignment "top" | "bottom" | "center" | "stretch" Defines a vertical alignment configuration. If horizontalAlignment is set, then verticalAlignment will default to "stretch". No
horizontalAlignment "top" | "bottom" | "center" | "stretch" Defines a vertical alignment configuration. If verticalAlignment is set, then horizontalAlignment will default to "stretch". No
margin string Sets the margin for all four sides of the window. No
width number | string Defines the window width. Use a number to define the width in pixels. Use a string to define the width in pixels or percentage of the screen width - e.g., "10px" or "10%". No
height number | string Defines the window height. Use a number to define the height in pixels. Use a string to define the height in pixels or percentage of the screen width - e.g., "10px" or "10%". No
display Display Defines the current display. No

Visibility

To check whether a Glue42 Window is visible, use the isVisible() property of a GDWindow instance:

const isWindowVisible = myWindow.isVisible;

if (isWindowVisible) {
    // ...
};

To change the window visibility, use the show(), hide() or setVisible() methods of a GDWindow instance.

To hide a window:

await myWindow.hide();

To make a window visible:

await myWindow.show();

To change the window visibility:

// Hide the window.
await myWindow.setVisible(false);

// Show the window.
await myWindow.setVisible(true);

State

To get the Glue42 Window state (normal, maximized or minimized), use the state property of a GDWindow instance:

const windowState = myWindow.state;

switch (windowState) {
    case "normal":
        // ...
        break;
    case "maximized":
        // ...
        break;
    case "minimized":
        // ...
        break;
};

Use the maximize(), minimize() and restore() methods to change the window state.

To maximize a window:

await myWindow.maximize();

To minimize a window:

await myWindow.minimize();

To restore a minimized or maximized window:

await myWindow.restore();

To check whether the window is in a collapsed state, use the isCollapsed property:

const isWindowCollapsed = myWindow.isCollapsed;

if (isWindowCollapsed) {
    // ...
};

Use the collapse() and expand() methods to collapse and expand a window:

// Collapse a window.
await myWindow.collapse();

// Expand a window.
await myWindow.expand();

Focus

To check whether a Glue42 Window is on focus, use the isFocused property of a GDWindow instance:

const isWindowFocused = myWindow.isFocused;

if (isWindowFocused) {
    // ...
};

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

await myWindow.focus();

Zoom

To get the zoom factor of a Glue42 Window, use the zoomFactor property of a GDWindow instance:

const windowZoomFactor = myWindow.zoomFactor;

Use the zoomIn(), zoomOut() and setZoomFactor() methods to change the window zoom factor.

To increment or decrement the zoom factor by one step, as defined in the system configuration:

// Zoom in by one step.
await myWindow.zoomIn();

// Zoom out by one step.
await myWindow.zoomOut();

To set the zoom factor:

// The specified zoom factor must be a valid factor value
// defined in the Glue42 Enterprise system configuration.
await myWindow.setZoomFactor(125);

Print

To print a web page opened in a Glue42 Window, use the print() method. It accepts a PrintOptions object as an optional parameter:

const printOptions = {
    silent: true,
    landscape: true,
    copies: 2,
    pageSize: "A4"
};

await myWindow.print(printOptions);

To print a web page as a PDF file, use the printToPDF() method. It accepts a PrintToPDFOptions object as an optional parameter:

const printOptions = {
    silent: true,
    autoSave: true,
    copies: 2,
    pageRanges: [{ from: 0, to: 10 }, { from: 12, to: 15 }]
    pageSize: "A4"
};

await myWindow.printToPDF(printOptions);

For details on how to configure the default printing options on system and application level, see the Printing section.

Close

To close a Glue42 Window, use the close() method of a GDWindow instance:

await myWindow.close();

Context

Each Glue42 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 applications 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 application 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 application, fetch the data using the data IDs saved as window context.

Get

To get the context of a Glue42 Window, use the context property or the getContext() method of a GDWindow instance:

const context = myWindow.context;
// or
const winContext = await myWindow.getContext();

Set

To open a Glue42 Window with initially set context, use the context property of the WindowCreateOptions object:

const name = "Glue42 Docs";
const url = "https://docs.glue42.com";
// Specify window context.
const options = {
    context: { glue: 42 }
};

const g42Window = await glue.windows.open(name, url, options);

Update

To update the context of a Glue42 Window, use the updateContext() method of a GDWindow instance:

const newContext = { glue: 4242 };

await myWindow.udpateContext(newContext);

Window Events

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

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

Window Added/Removed

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

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

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

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

Bounds Change

To track Glue42 Window bounds changes, use the onBoundsChanged() method of a GDWindow instance and pass an event handler:

const boundsChangedHandler = (g42window) => {
    console.log(`Window bounds: ${JSON.stringify(g42window.bounds)}`);
};

myWindow.onBoundsChanged(boundsChangedHandler);

Use this event to get notifications every time the position or the size of the window changes.

Placement Change

To track changes of the Glue42 Window placement settings, use the onPlacementSettingsChanged() method of a GDWindow instance and pass an event handler:

const placementChangedHandler = (g42window) => {
    console.log(`Window placement settings: ${JSON.stringify(g42window.placementSettings)}`);
};

myWindow.onPlacementSettingsChanged(placementChangedHandler);

Note that the onPlacementSettingsChanged() method notifies about runtime updates of the window placement settings, not the window bounds. To track changes of the window bounds (e.g., when the user resizes or moves the window, or when the window is moved/resized programmatically) use the onBoundsChanged() method.

Context Update

To track updates of the context of a Glue42 Window, use the onContextUpdated() method of a GDWindow instance and pass an event handler:

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

myWindow.onContextUpdated(contextUpdatedHandler);

Close and Refresh

To track when a Glue42 Window is about to be refreshed or closed, use its onClosing() and onRefreshing() methods. The onRefreshing() method can also be used to prevent page refresh if necessary.

The close and refresh handlers can be enabled/disabled globally through the system configuration of Glue42 Enterprise or individually for each window in its respective application configuration file. You can also specify a timeout (in ms) for their execution.

Handlers Configuration

To configure the close and refresh handlers globally for all windows, go to the system.json file located in %LocalAppData\Tick42\GlueDesktop\config and edit the refresheHandlers and closeHandlers properties under the windows top-level key:

"windows": {
    "refreshHandlers": {
        "enabled": true,
        "timeout": 2000
    },
    "closeHandlers": {
        "enabled": true,
        "timeout": 2000
    }
}

To configure close and refresh handlers only for specific windows, modify the details property in each respective application configuration file:

"details": {
    "refreshHandlers": {
        "enabled": false,
        "timeout": 2000
    },
    "closeHandlers": {
        "enabled": true,
        "timeout": 2000
    }
}

Window Close Handler

The onClosing() method allows you to execute code before the window is closed. The event handler can be asynchronous and will be awaited up to the configured timeout:

const closeHandler = async () => {
    await asyncOperation();
};

myWindow.onClosing(closeHandler);

Window Refresh Handler

The onRefreshing() method allows you to execute code before the window is refreshed. The event handler can be asynchronous and will be awaited up to the configured timeout:

const refreshHandler = async () => {
    await asyncOperation();
};

myWindow.onRefreshing(refreshHandler);

Preventing Page Refresh

To prevent page refresh, use the prevent() function that is passed as an argument to the onRefreshing() handler:

const refreshHandler = (prevent) => {
    const inputField = document.getElementById("input-field");
    const shouldNotRefresh = inputField.value !== "" ? true : false;

    if (shouldNotRefresh) {
        prevent();
    };
};

myWindow.onRefreshing(refreshHandler);

Window Groups

Glue42 Windows can be snapped together. One or more windows stuck together form a Group. The Window Management API offers methods for managing Glue42 Window groups. The Groups API is accessible through glue.windows.groups.

Finding Groups

Listing

To get a collection of all window groups, use the list() method:

const allGroups = glue.windows.groups.list();

Current Group

To get the group of the current window, use the group property of a GDWindow instance or the my property of the Groups API:

const myGroup = myWindow.group;
// or
const group = glue.windows.groups.my;

By Window

To find a Glue42 Window group by a window ID or a GDWindow object, use the findGroupByWindow() method:

const g42window = glue.windows.find("clientlist");
const windowID = g42window.id;

const group = glue.windows.groups.findGroupByWindow(windowID);
// or
const winGroup = glue.windows.groups.findGroupByWindow(g42window);

Group Operations

Title

To get the title of a Glue42 Window group, use the getTitle() method of a Group instance:

const groupTitle = await myGroup.getTitle();

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

await myGroup.setTitle("New Title");

State

To maximize a Glue42 Window group, use the maximize() method of a Group instance:

myGroup.maximize();

To restore a window group, use the restore() method of a Group instance:

myGroup.restore();

Group Header

To check whether the header of a Glue42 Window group is visible, use the isHeaderVisible property of a Group instance:

const isGroupHeaderVisible = myGroup.isHeaderVisible;

if (isGroupHeaderVisible) {
    // ...
};

To hide the header of a window group, use the hideHeader() method of a Group instance:

await myGroup.hideHeader();

To hide the header of a window group, use the showHeader() method of a Group instance:

await myGroup.showHeader();

Finding Windows in a Group

To get a collection of all Glue42 Windows participating in a Glue42 Window group, use the windows property of a Group instance:

const allGroupWindows = myGroup.windows;

To find a window in a Glue42 Window group by window ID, use the find() method of a Group instance:

const windowID = "25406_2";
const g42window = myGroup.find(windowID);

Ungrouping Windows

To extract a window from a Glue42 Window group, use the ungroup() method of a GDWindow instance and pass an optional UngroupOptions object as an argument:

const options = {
    bounds: {
        width: 400,
        height: 300
    },
    focus: true
};

const g42window = await myWindow.ungroup(options);

If you don't specify any options for ungroup(), the window will be moved up and to the right by default after being ungrouped:

Ungrouping

Using the ungroup() method on a tab window will extract the entire tab group:

Ungrouping tab

Window Neighbours

To get the neighbours of a window in a Glue42 Window group, use the topNeighbours, leftNeighbours, rightNeighbours and bottomNeighbours properties of a GDWindow instance:

const topNeighbours = myWindow.topNeighbours;
const leftNeighbours = myWindow.leftNeighbours;
const rightNeighbours = myWindow.rightNeighbours;
const bottomNeighbours = myWindow.bottomNeighbours;

An empty collection will be returned if the window doesn't have any neighbour windows in the respective direction.

Group Events

The Groups API offers several methods for tracking group events.

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

Window Added/Removed

To track adding or removing windows to a Glue42 Window group, use the onWindowAdded() and onWindowRemoved() methods of a Group instance and pass handlers for the respective events:

const handlers = {
    onAdded: (g42group, g42window) => {
        console.log(`Window "${g42window.name}" added to group with ID: ${g42group.id}`);
    },

    onRemoved: (g42group) => {
        console.log(`Window removed from group with ID: ${g42group.id}`);
    }
};

myGroup.onWindowAdded(handlers.onAdded);
myGroup.onWindowRemoved(handlers.onRemoved);

Header Visibility Changed

To track changes in the visibility of a Glue42 Window header, use the onHeaderVisibilityChanged() method of a Group instance and pass an event handler:

const handler = (g42group) => {
    console.log(`Header visibility of group with ID ${g42group.id} has changed.`)
};

myGroup.onHeaderVisibilityChanged(handler);

Tab Windows

To open a Glue42 Window as a tab window, set the mode property of the WindowCreateOptions object to "tab":

const name = "glue42-docs";
const url = "https://docs.glue42.com";
// Set `mode` to "tab".
const options = {
    mode: "tab"
};

const g42Window = await glue.windows.open(name, url, options);

Tab Group

Use the tabGroupId property of the WindowCreateOptions object to specify a tab group for the tab window. Tab windows with identical tabGroupId value will be opened in the same tab group:

const name = "glue42-docs";
const url = "https://docs.glue42.com";
// Specify a tab group.
const options = {
    tabGroupId: "my-tab-group"
};

const g42Window = await glue.windows.open(name, url, options);

Attaching and Detaching Tabs

To attach a tab to an existing tab window, use the attachTab() method of a GDWindow instance. Pass a window ID or a GDWindow object as a first argument:

const name = "glue42-docs";
const url = "https://docs.glue42.com";
const options = {
    mode: "tab"
};

const newTab = await glue.windows.open(name, url, options);

// Attach a new tab window to an existing tab window.
// It is assumed that `myWindow` is a tab window.
await myWindow.attachTab(newTab);

To detach a tab from a tab group, use the detachTab() method of a GDWindow instance. The detachTab() method accepts a DetachOptions object as an optional parameter. Use it to specify bounds and other options for the detached tab:

const detachOptions = {
    bounds: {
        top: 200,
        left: 200,
        height: 400,
        width: 300
    }
};

// Detach `myWindow` from the tab group.
// It is assumed that `myWindow` is a tab window.
await myWindow.detachTab(detachOptions);

Frame Buttons

The Window Management API allows placing custom buttons in the frame area of the window and handling clicks on them.

Frame button in a flat window:

Button in a flat window

Frame button in a tab window:

Button in a tab window

Frame button in an HTML window:

Button in an HTML window

Adding Buttons

To add or replace an existing frame button, use the addFrameButton() method of a GDWindow instance. It accepts a ButtonInfo object as a required first parameter. The buttonId (must be unique) and the imageBase64 (button image encoded as a base64 string) properties of the ButtonInfo object are required:

const buttonInfo = {
    buttonId: "search-button",
    tooltip: "Search",
    order: 1,
    imageBase64: "iVBORw0KGgoAAAAN..." 
}

await myWindow.addFrameButton(buttonInfo);

Use the order property to control the position of the buttons in the frame, and the tooltip property to provide concise information about the frame button to the user.

Removing Buttons

To remove a frame button, use the the removeFrameButton() method of a GDWindow instance and pass the ID of the button to remove:

const buttonID = "search-button";

await myWindow.removeFrameButton(buttonID);

Button Events

The frame button event methods return an unsubscribe function that you can use to stop tracking the respective event.

To track frame button clicks, use the onFrameButtonClicked() method of a GDWindow instance and pass an event handler:

const clickHandler = (buttonInfo, g42window) => {
    if (buttonInfo.buttonId === "search-button") {
        console.log(`The Search button of "${g42window.name}" was clicked.`);
    };
};

myWindow.onFrameButtonClicked(clickHandler);

To track adding or removing frame buttons, use the onFrameButtonAdded() and onFrameButtonRemoved() methods of a GDWindow instance and pass handlers for the respective events:

const handlers = {
    onAdded: (buttonInfo, g42window) => {
        console.log(`Frame button with ID "${buttonInfo.buttonId}" was added to "${g42window.name}".`);
    },

    onRemoved: (buttonInfo, g42window) => {
        console.log(`Frame button with ID "${buttonInfo.buttonId}" was removed from "${g42window.name}".`);
    }
};

myWindow.onFrameButtonAdded(handlers.onAdded);
myWindow.onFrameButtonRemoved(handlers.onRemoved);

Flydown Windows

Flydown windows are helper windows which can be easily configured to appear on hover on an area in your window. This spares you the need to write boilerplate code for showing and hiding additional windows. Note that flydowns work with existing windows - first, create a window and keep it hidden, and then use that window to create a flydown.

Flydown

See the JavaScript Flydown example on GitHub.

Basic Configuration

To create a flydown window, use the createFlydown() method. You can call it either through glue.windows.createFlydown() or directly on a window instance. The method accepts targetWindowId and a FlydownOptions object as arguments. If you call createFlydown() on a window instance, pass only a FlydownOptions object as an argument, since the current window will be used as a target for the created flydown window.

The following snippet shows how to use flydown windows in the most basic case when you need to show a flydown on hover on a button in an application. First, create a window which you will use as a flydown and then create the actual flydown. Open a window for a flydown with the open() method and pass hidden: true in the configuration object, or use a hidden application which has been auto started or started before creating the flydown. Use the createFlydown() method to create a flydown:

// Open a hidden window to be used as a flydown.
const name = "myFlydown";
const url = "http://localhost:22080/myFlydown";
const options = { hidden: true };

const myFlydownWindow = await glue.windows.open(name, url, options);

// Define a unique zone identifier for each zone that will trigger the flydown.
const myWindowID = glue.windows.find("MyWindow").id;
const zoneID = "uniqueZoneIdentifier";  
const flydownWindowID = myFlydownWindow.id;
const buttonBounds = { left:42, top:42, height:42, width:42 };
const flydownOptions = {
    windowId: flydownWindowID,
    // The flydown will appear at this position relative to the target (zone).
    targetLocation: "bottom",
    size: {
        width: 200,
        height: 200
    },
    zones: [
        {
            id: zoneID,
            // The flydown will appear on hover within these bounds.
            bounds: buttonBounds,
            flydownSize: {
                width: 300,
                height: 400
            }  
        }
    ]
};

// Create the actual flydown.
const flydown = await glue.windows.createFlydown(myWindowID, flydownOptions);
Property Description
targetWindowId The ID of the target window for which the flydown will be created. Not needed when you call createFlydown() on a window instance.
windowId The ID of the window which will be used as a flydown window.
targetLocation The location ("bottom", "top", "left", "right" or "none") where the flydown will appear relative to the defined flydown zone. If "none" is passed, the flydown will appear at { left: 0, top: 0 } of the flydown trigger zone.
size The size of the rendered flydown window (width and height). Can be an object with a specific size or a callback that calculates the size.
zones An array of defined FlydownZone objects which when triggered will show a flydown window.
id A unique zone ID.
bounds Bounds of the zone which can trigger a flydown window. These bounds are relative to the target window - the coordinates { left: 0, top: 0 } correspond to the top left corner of the target window, rather than the top left corner of the monitor.
flydownSize Either the desired size of the flydown or a callback invoked before the flydown is shown in order to calculate the flydown size or cancel the flydown.

The properties targetLocation and windowId can be set both in the FlydownOptions object and/or in each FlydownZone object within the zones array. The values set in the FlydownOptions object will be used as default values if no such value is specified in a FlydownZone object. If you specify a value for any of these properties both in the FlydownOptions object and in a FlydownZone object, the one in the FlydownZone object will have higher priority than the one in the FlydownOptions object.

The size of the flydown window, however, is handled a little differently. Since its value can be either a size object or a callback for calculating the size (see Dynamic Size Calculation), there are several cases if you set the flydown size both in the FlydownOptions object (the size property) and in a FlydownZone object (the flydownSize property). In any case, the values in the FlydownZone object have higher priority, except when you pass a callback in the FlydownOptions object and specific size in the FlydownZone object - then the callback in the FlydownOptions object will be taken into account.

Flydown Active Area

To create a flydown window which is triggered by a particular area within your app and remains active (visible) as long as the user stays within a certain range of the application window, use the activeArea property in the options object.

// Range where the flydown will remain active - values are relative to the target window.
const activeArea = { left: 20, top: 20, height: 60, width: 60 }; 
const flydownOptions = {
    windowId: flydownWindowID,
    // The flydown will appear at this position relative to the target (zone).
    targetLocation: "bottom",
    size: {
        width: 200,
        height: 200
    },
    // The flydown will not disappear while the user is hovering within that range.
    activeArea: activeArea,
    zones: [
        {
            id: zoneID,
            // The flydown will appear on hover within these bounds.
            bounds: buttonBounds,
            flydownSize: {
                width: 300,
                height: 400
            }  
        }
    ]
};

const flydown = await glue.windows.createFlydown(MyWindowID, flydownOptions);

Dynamic Size Calculation

To change the size of your flydown window at runtime, pass a callback function to the size property in the FlydownOptions object (or to the flydownSize property in the FlydownZone object) instead of a specific size:

const myWindow = glue.windows.my();
const flydownOptions = {
    windowId: flydownWindowID,
    targetLocation: "bottom",
    size: (data, cancel) => {
        // Make calculations here...
        return {
            width,
            height
        }
    },
    zones: [
        {
            id: zoneID,
            bounds: buttonBounds
        }
    ]
};

// The `targetWindowId` property is omitted, as `createFlydown()` is called on a window instance.
const flydown = await myWindow.createFlydown(flydownOptions);

The callback function receives two arguments - data and cancel. The data argument is an object with the following properties:

Property Description
zoneId The ID of the zone which has triggered the flydown.
flydownWindowId The ID of the window used as a flydown.
flydownWindowBounds The initial bounds of the flydown if set before the callback is invoked. If not set, this defaults to { left: 0, top: 0, height: 200, width: 200}.

Canceling Flydowns

The cancel argument of the callback that can be passed to the size property (or the flydownSize property) is a function that you can use to cancel the flydown:

// Condition on which to cancel the flydown.
const shouldBeCanceled = true;
const flydownOptions = {
    windowId: flydownWindowID,
    targetLocation: "bottom",
    size: (data, cancel) => {
        if (shouldBeCanceled) {
            cancel();
        }
        return {
            width: 200,
            height: 200
        }
    },
    zones: [
        {
            id: zoneID,
            bounds: buttonBounds
        }
    ]
};

const flydown = await myWindow.createFlydown(flydownOptions);

Note that this callback is not the place to make heavy calculations - you must return a response within 100 ms. Return a Promise from the callback if your logic is asynchronous.

The Flydown object has a destroy property that you can use to destroy the zones that trigger the flydowns. This will only remove the flydown trigger zones and not the actual windows used as flydowns:

const flydownOptions = {
    windowId: flydownWindowID,
    targetLocation: "bottom",
    size: (data, cancel) => {
        if (shouldBeCanceled) {
            cancel();
        }
        return {
            width: 200,
            height: 200
        }
    },
    zones: [
        {
            id: zoneID,
            bounds: buttonBounds
        }
    ]
};

const flydown = await myWindow.createFlydown(flydownOptions);

// Remove the flydown trigger zones.
await flydown.destroy();

Popup Windows

Popup windows are helper windows that can appear when the user clicks an area in your application.

Popup

See the JavaScript Popup example on GitHub.

Implementing the behavior of popup windows can be a very tedious task. You must handle all cases in which the popup may go out of screen, handle user input from multiple windows which may involve confusion with timeouts and potential race conditions. While not impossible, it is an endeavor prone to many errors, while the end result most often is unreliable. The showPopup() method handles all these problems and almost no additional code is required to make it work smoothly in all cases. You can call showPopup() either through glue.windows.showPopup() or directly on a window instance. This method accepts targetWindowId and a PopupOptions object as arguments. If you call showPopup() directly on a window instance, don't pass a targetWindowId, as the ID of the current window will be used to create the popup window.

As with the Flydown Windows, create a window which you will use as a popup and after that create the actual popup.Open a window for a popup with the open() method and pass hidden: true in the configuration object, or use a hidden application which has been auto started or started before creating the popup. Use the showPopup() method to create a popup.

The following snippet demonstrates the steps to follow to create a popup for a window:

// Open a window to use as a popup.
const name = "myPopup";
const url = "http://localhost:22080/myPopup";
const options = { hidden: true };

const myPopupWindow = await glue.windows.open(name, url, options);

const myWindowID = glue.windows.find("MyWindow").id;
// Area which will trigger the popup when the user clicks on it.
const buttonBounds = { left: 42, top: 42, width: 42, height: 42 };
const popupOptions = {
    windowId: myPopupWindow.id,
    targetBounds: buttonBounds,
    size: {
        width: 100,
        height: 200
    },
    targetLocation: "bottom"
};

// Create the popup.
const popup = await glue.windows.showPopup(myWindowID, popupOptions);
Property Description
targetWindowId The ID of the target window for which the popup will be created. Not needed when you call showPopup() on a window instance.
windowId The ID of the window which will be used as a popup window.
targetBounds The bounds of the area around which the popup window will appear.
size The size of the rendered popup window (width and height).
targetLocation The location ("bottom", "top", "left", "right" or "none") where the popup will appear relative to the defined popup area (targetBounds). If "none" is passed, the popup will appear at { left: 0, top: 0 } of the popup area.

Reference

Reference