InteractiveWindow - Vircadia API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts

An InteractiveWindow can display either inside Interface or in its own window separate from the Interface window. The window content is defined by a QML file, which can optionally include a WebView control that embeds an HTML web page. (The WebView control is defined by a "WebView.qml" file included in the Interface install.)

Create using Desktop.createWindow.

Properties

Name	Type	Summary
title	string	The title of the window.
position	Vec2	The absolute position of the window, in pixels.
relativePositionAnchor	InteractiveWindow.RelativePositionAnchor	The anchor for the `relativePosition`, if used.
relativePosition	Vec2	The position of the window, relative to the `relativePositionAnchor`, in pixels. Excludes the window frame.
size	Vec2	The size of the window, in pixels.
visible	boolean	`true` if the window is visible, `false` if it isn't.
presentationMode	InteractiveWindow.PresentationMode	The presentation mode of the window: `Desktop.PresentationMode.VIRTUAL` to display the window inside Interface, `.NATIVE` to display it as its own separate window.

Methods

Name	Return Value	Summary
`close`	None	Closes the window. It can then no longer be used.
`emitScriptEvent`	None	Sends a message to an embedded HTML web page. To receive the message, the HTML page's script must connect to the `EventBridge` that is automatically provided for the script: `EventBridge.scriptEventReceived.connect(function(message) { ... });`
`emitWebEvent`	None	Deprecated: This function is deprecated and will be removed.
`qmlToScript`	None	Deprecated: This method is deprecated and will be removed.
`raise`	None	Raises the window to the top.
`sendToQml`	None	Sends a message to the QML page. To receive the message, the QML page must implement a function: `function fromScript(message) { ... }`
`show`	None	Makes the window visible and raises it to the top.

Signals

Name	Summary
`closed`	Triggered when the window is closed.
`fromQml`	Triggered when a message from the QML page is received. The QML page can send a message (string or object) by calling: `sendToScript(message);`
`positionChanged`	Triggered when the window's position changes.
`presentationModeChanged`	Triggered when the window's presentation mode changes.
`scriptEventReceived`	Deprecated: This signal is deprecated and will be removed.
`sizeChanged`	Triggered when the window's size changes.
`titleChanged`	Triggered when window's title changes.
`visibleChanged`	Triggered when the window is made visible or invisible, or is closed.
`webEventReceived`	Triggered when a message from an embedded HTML web page is received. The HTML web page can send a message by calling: `EventBridge.emitWebEvent(message);`

Type Definitions

DockArea
Type: number

A docking location of an InteractiveWindow.

Value	Name	Description
`0`	TOP	Dock to the top edge of the Interface window.
`1`	BOTTOM	Dock to the bottom edge of the Interface window.
`2`	LEFT	Dock to the left edge of the Interface window.
`3`	RIGHT	Dock to the right edge of the Interface window.

DockAreas
Type: object

The possible docking locations of an InteractiveWindow.

Properties

Name	Type	Summary
TOP	InteractiveWindow.DockArea	Dock to the top edge of the Interface window.
BOTTOM	InteractiveWindow.DockArea	Dock to the bottom edge of the Interface window.
LEFT	InteractiveWindow.DockArea	Dock to the left edge of the Interface window.
RIGHT	InteractiveWindow.DockArea	Dock to the right edge of the Interface window.

Flags
Type: number

A set of flags controlling InteractiveWindow behavior. The value is constructed by using the | (bitwise OR) operator on the individual flag values.

Flag Name	Value	Description
ALWAYS_ON_TOP	`1`	The window always displays on top.
CLOSE_BUTTON_HIDES	`2`	The window hides instead of closing when the user clicks the "close" button.

OverrideFlags
Type: number

A set of flags customizing InteractiveWindow controls. The value is constructed by using the | (bitwise OR) operator on the individual flag values..

Value	Name	Description
`0x00000001`	Window	Displays the window as a window rather than a dialog.
`0x00001000`	WindowTitleHint	Adds a title bar.
`0x00002000`	WindowSystemMenuHint	Adds a window system menu.
`0x00004000`	WindowMinimizeButtonHint	Adds a minimize button.
`0x00008000`	WindowMaximizeButtonHint	Adds a maximize button.
`0x00040000`	WindowStaysOnTopHint	The window stays on top of other windows. Not used on Windows.
`0x08000000`	WindowCloseButtonHint	Adds a close button.

PresentationMode
Type: number

A display mode for an InteractiveWindow.

Value	Name	Description
`0`	VIRTUAL	The window is displayed inside Interface: in the desktop window in desktop mode or on the HUD surface in HMD mode.
`1`	NATIVE	The window is displayed separately from the Interface window, as its own separate window.

PresentationModes
Type: object

The possible display modes for an InteractiveWindow.

Properties

Name	Type	Summary
VIRTUAL	InteractiveWindow.PresentationMode	The window is displayed inside Interface: in the desktop window in desktop mode or on the HUD surface in HMD mode.
NATIVE	InteractiveWindow.PresentationMode	The window is displayed separately from the Interface window, as its own separate window.

PresentationWindowInfo
Type: object

Configures how a NATIVE window is displayed.

Properties

Name	Type	Summary
dockArea	InteractiveWindow.DockArea	The edge of the Interface window to dock to.

RelativePositionAnchor
Type: number

The anchor for a relative position of an InteractiveWindow.

Value	Name	Description
`0`	NO_ANCHOR	Position is not relative to any part of the Interface window.
`1`	TOP_LEFT	Position is offset from the top left of the Interface window.
`2`	TOP_RIGHT	Position is offset from the top right of the Interface window.
`3`	BOTTOM_RIGHT	Position offset from the bottom right of the Interface window.
`4`	BOTTOM_LEFFT	Position is offset from the bottom left of the Interface window.

RelativePositionAnchors
Type: object

The possible relative position anchors of an InteractiveWindow relative to the Interface window.

Properties

Name	Type	Summary
NO_ANCHOR	InteractiveWindow.RelativePositionAnchor	Position is not relative to any part of the Interface window.
TOP_LEFT	InteractiveWindow.RelativePositionAnchor	Position is offset from the top left of the Interface window.
TOP_RIGHT	InteractiveWindow.RelativePositionAnchor	Position is offset from the top right of the Interface window.
BOTTOM_RIGHT	InteractiveWindow.RelativePositionAnchor	Position offset from the bottom right of the Interface window.
BOTTOM_LEFT	InteractiveWindow.RelativePositionAnchor	Position is offset from the bottom left of the Interface window.

WindowProperties
Type: object

Property values used when creating an InteractiveWindow.

Properties

Name	Type	Attributes	Summary
title	string	<optional>	The title of the window. Default Value: "InteractiveWindow
position	Vec2	<optional>	The initial position of the window, in pixels.
size	Vec2	<optional>	The initial size of the window, in pixels
visible	boolean	<optional>	`true` to make the window visible when created, `false` to make it invisible. Default Value: true
presentationMode	InteractiveWindow.PresentationMode	<optional>	`Desktop.PresentationMode.VIRTUAL` to display the window inside Interface, `.NATIVE` to display it as its own separate window. Default Value: Desktop.PresentationMode.VIRTUAL
presentationWindowInfo	InteractiveWindow.PresentationWindowInfo	<optional>	Controls how a `NATIVE` window is displayed. If used, the window is docked to the specified edge of the Interface window, otherwise the window is displayed as its own separate window.
additionalFlags	InteractiveWindow.Flags	<optional>	Customizes window behavior. Default Value: 0
overrideFlags	InteractiveWindow.OverrideFlags	<optional>	Customizes window controls. Default Value: 0
relativePositionAnchor	InteractiveWindow.RelativePositionAnchor	<optional>	The anchor for the `relativePosition`, if used.
relativePosition	Vec2	<optional>	The position of the window, relative to the `relativePositionAnchor`, in pixels. Excludes the window frame.
isFullScreenWindow	boolean	<optional>	`true` to make the window full screen.

Method Details

(static) close( )
Closes the window. It can then no longer be used.

(static) emitScriptEvent( message )

Sends a message to an embedded HTML web page. To receive the message, the HTML page's script must connect to the EventBridge that is automatically provided for the script:

EventBridge.scriptEventReceived.connect(function(message) {
    ...
});

Parameters

Name	Type	Description
`message`	string \| object	The message to send to the embedded HTML web page.

(static) emitWebEvent( message )

Deprecated: This function is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object \| string	Message.

(static) qmlToScript( message )

Deprecated: This method is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.

(static) raise( )
Raises the window to the top.

(static) sendToQml( message )

Sends a message to the QML page. To receive the message, the QML page must implement a function:

function fromScript(message) {
  ...
}

Parameters

Name	Type	Description
`message`	string \| object	The message to send to the QML page.

Examples

Send and receive messages with a QML window.

// JavaScript file.

var interactiveWindow = Desktop.createWindow(Script.resolvePath("InteractiveWindow.qml"), {
    title: "Interactive Window",
    size: { x: 400, y: 300 }
});

interactiveWindow.fromQml.connect(function (message) {
    print("Message received: " + message);
});

Script.setTimeout(function () {
    interactiveWindow.sendToQml("Hello world!");
}, 2000);

Script.scriptEnding.connect(function () {
    interactiveWindow.close();
});

// QML file, "InteractiveWindow.qml".

import QtQuick 2.5
import QtQuick.Controls 1.4

Rectangle {

    function fromScript(message) {
        text.text = message;
        sendToScript("Hello back!");
    }

    Label {
        id: text
        anchors.centerIn: parent
        text: "..."
    }
}

(static) show( )
Makes the window visible and raises it to the top.

Signal Details

closed( ) Returns: Signal
Triggered when the window is closed.

fromQml( message )
Returns: Signal

Triggered when a message from the QML page is received. The QML page can send a message (string or object) by calling:

sendToScript(message);

Parameters

Name	Type	Description
`message`	string \| object	The message received.

positionChanged( ) Returns: Signal
Triggered when the window's position changes.

presentationModeChanged( ) Returns: Signal
Triggered when the window's presentation mode changes.

scriptEventReceived( message )
Returns: Signal

Deprecated: This signal is deprecated and will be removed.

Parameters

Name	Type	Description
`message`	object	Message.

sizeChanged( ) Returns: Signal
Triggered when the window's size changes.

titleChanged( ) Returns: Signal
Triggered when window's title changes.

visibleChanged( ) Returns: Signal
Triggered when the window is made visible or invisible, or is closed.

webEventReceived( message )
Returns: Signal

Triggered when a message from an embedded HTML web page is received. The HTML web page can send a message by calling:

EventBridge.emitWebEvent(message);

Parameters

Name	Type	Description
`message`	string \| object	The message received.