Enabling pass-through mode for external windows

The enablePassthrough option in an app’s app.config.json file allows startup applications to customize the browser window by controlling the browser window’s transparency and mouse events programmatically. The window will not be resizable or movable by the user unless the movablePassthroughWindow option is also set. For an in-depth example of how to do this, reach out to the iTwin Studio team. The enablePassthrough option enables advanced workflows such as integrating with external rendering engines.

Configuration

To enable pass-through mode, add the following configuration to the browserWindow property in your app’s app.config.json file:

{
  "browserWindow": {
    "enablePassthrough": true
  }
}

API Usage

Startup applications can use the following APIs to control the window’s transparency and mouse event handling:

Toggle Transparency

The StudioStartupApp.setTransparentBackground method allows toggling the transparency of the browser window (excluding the header, navigation sidebar, and widgets/tools):

await StudioStartupApp.setTransparentBackground(true); // Enable transparency
await StudioStartupApp.setTransparentBackground(false); // Disable transparency

Ignore Mouse Events

The StudioStartupApp.setIgnoreMouseEvents method allows the transparent window to ignore or capture mouse events:

await StudioStartupApp.setIgnoreMouseEvents(true); // Ignore mouse events
await StudioStartupApp.setIgnoreMouseEvents(false); // Capture mouse events

Notes

• This feature is experimental and intended for advanced use cases.
• Ensure proper testing when using enablePassthrough to avoid unexpected behavior.
• When movablePassthroughWindow is enabled, iTwin Studio disables window resizing while maximized and allows double-clicking the header to toggle the maximize state.