Window

Description

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

The Window API provides various facilities not covered elsewhere, including: window dimensions, window focus, camera view, announcements, user connections, common dialog boxes, snapshots, file import, domain navigation, domain changes, domain physics, OS clipboard, build number.

Properties

Name Type Summary
innerWidth number

The width of the drawable area of the Interface window (i.e., without borders or other chrome), in pixels. Read-only.

innerHeight number

The height of the drawable area of the Interface window (i.e., without borders or other chrome), in pixels. Read-only.

x number

The x display coordinate of the top left corner of the drawable area of the Interface window. Read-only.

y number

The y display coordinate of the top left corner of the drawable area of the Interface window. Read-only.

interstitialModeEnabled boolean

true if the interstitial graphics are displayed when a domain is loading, otherwise false.

Default Value: false

location location

Provides facilities for working with your current metaverse location.

Methods

Name Return Value Summary
alert None

Displays a dialog with the specified message and an "OK" button. The dialog is non-modal; the script continues without waiting for a user response.

browse string

Prompts the user to choose a file. Displays a modal dialog that navigates the directory tree.

browseAssets string

Prompts the user to choose an Asset Server item. Displays a modal dialog that navigates the tree of assets on the Asset Server.

browseAssetsAsync None

Prompts the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the Asset Server. An assetsDirChanged signal is emitted when an asset is chosen; no signal is emitted if the user cancels the dialog.

browseAsync None

Prompts the user to choose a file. Displays a non-modal dialog that navigates the directory tree. A browseChanged signal is emitted when a file is chosen; no signal is emitted if the user cancels the dialog.

browseDir string

Prompts the user to choose a directory. Displays a modal dialog that navigates the directory tree.

browseDirAsync None

Prompts the user to choose a directory. Displays a non-modal dialog that navigates the directory tree. A browseDirChanged signal is emitted when a directory is chosen; no signal is emitted if the user cancels the dialog.

checkVersion string

Gets Interface's build number.

closeMessageBox None

Closes a message box that was opened with openMessageBox.

confirm boolean

Prompts the user to confirm something. Displays a modal dialog with a message plus "Yes" and "No" buttons.

copyToClipboard None

Copies text to the operating system's clipboard.

displayAnnouncement None

Displays a notification message. Notifications are displayed in panels by the default script, nofications.js. An announcement signal is emitted when this function is called.

domainLoadingProgress number

Deprecated: This function is deprecated and will be removed.

getActiveDisplayPlugin number

Gets the index of the currently active display plugin.

getDeviceSize Vec2

Gets the size of the drawable area of the Interface window if in desktop mode or the HMD rendering surface if in HMD mode.

getDisplayPluginCount number

Gets the number of display plugins currently available.

getDisplayPluginName string

Gets the name of a display plugin.

getLastDomainConnectionError Window.ConnectionRefusedReason

Gets the last domain connection error when a connection is refused.

getUserAgent string

Gets Interface's user agent.

hasFocus boolean

Checks whether the Interface window has focus.

isDisplayPluginHmd boolean

Checks whether a display plugin is an HMD.

isPhysicsEnabled boolean

Checks to see if physics is active for you in the domain you're visiting - there is a delay between your arrival at a domain and physics becoming active for you in that domain.

isPointOnDesktopWindow boolean

Checks if a 2D point is within the desktop window if in desktop mode, or the drawable area of the HUD overlay if in HMD mode.

makeConnection None

Emits a connectionAdded or a connectionError signal that indicates whether or not a user connection was successfully made using the Web API.

openAndroidActivity None

Opens an Android activity and optionally return back to the scene when the activity is completed. Android only.

openMessageBox number

Opens a non-modal message box that can have a variety of button combinations. See also, updateMessageBox and closeMessageBox.

openUrl None

Opens a URL in the Interface window or other application, depending on the URL's scheme. The following schemes are supported:

  • hifi: Navigate to the URL in Interface.
  • hifiapp: Open a system app in Interface.

Other schemes will either be handled by the OS (e.g. http, https, or mailto) or will display a dialog asking the user to confirm that they want to try to open the URL.

openWebBrowser None

Opens an Interface web browser window.

prompt string

Prompts the user to enter some text. Displays a modal dialog with a message and a text box, plus "OK" and "Cancel" buttons.

promptAsync None

Prompts the user to enter some text. Displays a non-modal dialog with a message and a text box, plus "OK" and "Cancel" buttons. A promptTextChanged signal is emitted when the user OKs the dialog; no signal is emitted if the user cancels the dialog.

protocolSignature string

Gets the signature for Interface's protocol version.

raise None

Raises the Interface window if it is minimized. If raised, the window gains focus.

save string

Prompts the user to specify the path and name of a file to save to. Displays a modal dialog that navigates the directory tree and allows the user to type in a file name.

saveAsync None

Prompts the user to specify the path and name of a file to save to. Displays a non-modal dialog that navigates the directory tree and allows the user to type in a file name. A saveFileChanged signal is emitted when a file is specified; no signal is emitted if the user cancels the dialog.

setActiveDisplayPlugin None

Sets the currently active display plugin.

setDisplayTexture boolean

Sets what to show on the PC display. For entity camera view, the entity camera is configured using Camera.setCameraEntity and Camera.mode.

setFocus None

Makes the Interface window have focus. On Windows, if Interface doesn't already have focus, the task bar icon flashes to indicate that Interface wants attention but focus isn't taken away from the application that the user is using.

shareSnapshot None

Prepares a snapshot ready for sharing. A snapshotShared signal is emitted when the snapshot has been prepared.

showAssetServer None

Opens the Asset Browser dialog. If a file to upload is specified, the user is prompted to enter the folder and name to map the file to on the asset server.

takeSecondaryCamera360Snapshot None

Takes a 360° snapshot at a given position for the secondary camera. The secondary camera does not need to have been set up.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

takeSecondaryCameraSnapshot None

Takes a still snapshot of the current view from the secondary camera that can be set up through the Render API.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

takeSnapshot None

Takes a snapshot of the current Interface view from the primary camera. When a still image only is captured, stillSnapshotTaken is emitted; when a still image plus moving images are captured, processingGifStarted and processingGifCompleted are emitted.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

updateMessageBox None

Updates the content of a message box that was opened with openMessageBox.

Signals

Name Summary
announcement

Triggered when a message is announced by displayAnnouncement.

assetsDirChanged

Triggered when the user chooses an asset in a browseAssetsAsync dialog.

browseChanged

Triggered when the user chooses a file in a browseAsync dialog.

browseDirChanged

Triggered when the user chooses a directory in a browseDirAsync dialog.

connectionAdded

Triggered when you've successfully made a user connection.

connectionError

Triggered when you failed to make a user connection.

domainChanged

Triggered when you change the domain you're visiting.

Warning: Is not emitted if you go to a domain that isn't running.

domainConnectionRefused

Triggered when you try to visit a domain but are refused connection.

geometryChanged

Triggered when the position or size of the Interface window changes.

interstitialModeChanged

Triggered when the interstitial mode changes.

messageBoxClosed

Triggered when the user closes a message box that was opened with openMessageBox.

minimizedChanged

Triggered when "minimized" state of the Interface window changes.

processingGifCompleted

Triggered when a GIF has been prepared of the snapshot images captured by takeSnapshot.

processingGifStarted

Triggered when the snapshot images have been captured by takeSnapshot and the GIF is starting to be processed.

promptTextChanged

Triggered when the user OKs a promptAsync dialog.

redirectErrorStateChanged

Triggered when you try to visit a domain but are redirected into the error state.

saveFileChanged

Triggered when the user specifies a file in a saveAsync dialog.

snapshot360Taken

Triggered when a still 360° snapshot has been taken by calling takeSecondaryCamera360Snapshot.

snapshotShared

Triggered when a snapshot submitted via shareSnapshot is ready for sharing. The snapshot may then be shared via the Account.metaverseServerURL Web API.

stillSnapshotTaken

Triggered when a still snapshot has been taken by calling takeSnapshot with includeAnimated = false or takeSecondaryCameraSnapshot.

svoImportRequested

Triggered when you try to navigate to a *.json, *.svo, or *.svo.json URL in a Web browser within Interface.

Type Definitions

ConnectionRefusedReason
Type: number

The reasons that you may be refused connection to a domain are defined by numeric values:

Reason Value Description
Unknown 0 Some unknown reason.
ProtocolMismatch 1 The communications protocols of the domain and your Interface are not the same.
LoginErrorMetaverse 2 You could not be logged into the domain per your metaverse login.
NotAuthorizedMetaverse 3 You are not authorized to connect to the domain per your metaverse login.
TooManyUsers 4 The domain already has its maximum number of users.
TimedOut 5 Connecting to the domain timed out.
LoginErrorDomain 2 You could not be logged into the domain per your domain login.
NotAuthorizedDomain 6 You are not authorized to connect to the domain per your domain login.
DisplayTexture
Type: string

The views that may be visible on the PC display.

Value View Displayed
"" Normal view.
"resource://hmdPreviewFrame" HMD preview.
"resource://spectatorCameraFrame" Entity camera view.
MessageBoxButton
Type: number

The buttons that may be included in a message box created by openMessageBox are defined by numeric values:

Button Value Description
NoButton 0x0 An invalid button.
Ok 0x400 "OK"
Save 0x800 "Save"
SaveAll 0x1000 "Save All"
Open 0x2000 "Open"
Yes 0x4000 "Yes"
YesToAll 0x8000 "Yes to All"
No 0x10000 "No"
NoToAll 0x20000 "No to All"
Abort 0x40000 "Abort"
Retry 0x80000 "Retry"
Ignore 0x100000 "Ignore"
Close 0x200000 "Close"
Cancel 0x400000 "Cancel"
Discard 0x800000 "Discard" or "Don't Save"
Help 0x1000000 "Help"
Apply 0x2000000 "Apply"
Reset 0x4000000 "Reset"
RestoreDefaults 0x8000000 "Restore Defaults"

Method Details

(static) alert( messageopt )

Displays a dialog with the specified message and an "OK" button. The dialog is non-modal; the script continues without waiting for a user response.

Parameters

Name Type Attributes Default Value Description
message string <optional>
""

The message to display.

Example

Display a friendly greeting.

Window.alert("Welcome!");
print("Script continues without waiting");
(static) browse( titleopt, directoryopt, nameFilteropt ) → {string}
Returns: The path and name of the file if one is chosen, otherwise null.

Prompts the user to choose a file. Displays a modal dialog that navigates the directory tree.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example

Ask the user to choose an image file.

var filename = Window.browse("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)");
print("File: " + filename);
(static) browseAssets( titleopt, directoryopt, nameFilteropt ) → {string}
Returns: The path and name of the asset if one is chosen, otherwise null.

Prompts the user to choose an Asset Server item. Displays a modal dialog that navigates the tree of assets on the Asset Server.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example

Ask the user to select an FBX asset.

var asset = Window.browseAssets("Select FBX File", "/", "*.fbx");
print("FBX file: " + asset);
(static) browseAssetsAsync( titleopt, directoryopt, nameFilteropt )

Prompts the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the Asset Server. An assetsDirChanged signal is emitted when an asset is chosen; no signal is emitted if the user cancels the dialog.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example
function onAssetsDirChanged(asset) {
    print("FBX file: " + asset);
}
Window.assetsDirChanged.connect(onAssetsDirChanged);

Window.browseAssetsAsync("Select FBX File", "/", "*.fbx");
print("Script continues without waiting");
(static) browseAsync( titleopt, directoryopt, nameFilteropt )

Prompts the user to choose a file. Displays a non-modal dialog that navigates the directory tree. A browseChanged signal is emitted when a file is chosen; no signal is emitted if the user cancels the dialog.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example

Ask the user to choose an image file without waiting for the answer.

function onBrowseChanged(filename) {
    print("File: " + filename);
}
Window.browseChanged.connect(onBrowseChanged);

Window.browseAsync("Select Image File", Paths.resources, "Images (*.png *.jpg *.svg)");
print("Script continues without waiting");
(static) browseDir( titleopt, directoryopt ) → {string}
Returns: The path of the directory if one is chosen, otherwise null.

Prompts the user to choose a directory. Displays a modal dialog that navigates the directory tree.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

Example

Ask the user to choose a directory.

var directory = Window.browseDir("Select Directory", Paths.resources);
print("Directory: " + directory);
(static) browseDirAsync( titleopt, directoryopt )

Prompts the user to choose a directory. Displays a non-modal dialog that navigates the directory tree. A browseDirChanged signal is emitted when a directory is chosen; no signal is emitted if the user cancels the dialog.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

Example

Ask the user to choose a directory without waiting for the answer.

function onBrowseDirChanged(directory) {
    print("Directory: " + directory);
}
Window.browseDirChanged.connect(onBrowseDirChanged);

Window.browseDirAsync("Select Directory", Paths.resources);
print("Script continues without waiting");
(static) checkVersion( ) → {string}
Returns: Interface's build number.

Gets Interface's build number.

(static) closeMessageBox( id )

Closes a message box that was opened with openMessageBox.

Parameters

Name Type Description
id number

The ID of the message box.

(static) confirm( messageopt ) → {boolean}
Returns: true if the user selects "Yes", otherwise false.

Prompts the user to confirm something. Displays a modal dialog with a message plus "Yes" and "No" buttons.

Parameters

Name Type Attributes Default Value Description
message string <optional>
""

The question to display.

Example

Ask the user a question requiring a yes/no answer.

var answer = Window.confirm("Are you sure?");
print(answer);  // true or false
(static) copyToClipboard( text )

Copies text to the operating system's clipboard.

Parameters

Name Type Description
text string

The text to copy to the operating system's clipboard.

(static) displayAnnouncement( message )

Displays a notification message. Notifications are displayed in panels by the default script, nofications.js. An announcement signal is emitted when this function is called.

Parameters

Name Type Description
message string

The announcement message.

Example

Send and capture an announcement message.

function onAnnouncement(message) {
    // The message is also displayed as a notification by notifications.js.
    print("Announcement: " + message);
}
Window.announcement.connect(onAnnouncement);

Window.displayAnnouncement("Hello");
(static) domainLoadingProgress( ) → {number}
Returns: Progress.

Deprecated: This function is deprecated and will be removed.

(static) getActiveDisplayPlugin( ) → {number}
Returns: The index of the currently active display plugin. The first display plugin has an index of 0.

Gets the index of the currently active display plugin.

(static) getDeviceSize( ) → {Vec2}
Returns: The width and height of the Interface window or HMD rendering surface, in pixels.

Gets the size of the drawable area of the Interface window if in desktop mode or the HMD rendering surface if in HMD mode.

(static) getDisplayPluginCount( ) → {number}
Returns: The number of display plugins currently available.

Gets the number of display plugins currently available.

(static) getDisplayPluginName( index ) → {string}
Returns: The name of the display plugin.

Gets the name of a display plugin.

Parameters

Name Type Description
index number

The index of the display plugin. Must be less than the value returned by getDisplayPluginCount. The first display plugin has an index of 0.

Example

Print the names of all available display plugins.

for (var i = 0, length = Window.getDisplayPluginCount(); i < length; i++) {
    print(Window.getDisplayPluginName(i));
}
(static) getLastDomainConnectionError( ) → {Window.ConnectionRefusedReason}
Returns: Integer number that enumerates the last domain connection refused.

Gets the last domain connection error when a connection is refused.

(static) getUserAgent( ) → {string}
Returns: Interface's user agent.

Gets Interface's user agent.

(static) hasFocus( ) → {boolean}
Returns: true if the Interface window has focus, false if it doesn't.

Checks whether the Interface window has focus.

(static) isDisplayPluginHmd( index ) → {boolean}
Returns: true if the display plugin is a HMD, false if it isn't.

Checks whether a display plugin is an HMD.

Parameters

Name Type Description
index number

The index of the display plugin. Must be less than the value returned by getDisplayPluginCount. The first display plugin has an index of 0.

(static) isPhysicsEnabled( ) → {boolean}
Returns: true if physics is currently active for you, otherwise false.

Checks to see if physics is active for you in the domain you're visiting - there is a delay between your arrival at a domain and physics becoming active for you in that domain.

Example

Wait for physics to be enabled when you change domains.

function checkForPhysics() {
    var isPhysicsEnabled = Window.isPhysicsEnabled();
    print("Physics enabled: " + isPhysicsEnabled);
    if (!isPhysicsEnabled) {
        Script.setTimeout(checkForPhysics, 1000);
    }
}

function onDomainChanged(domain) {
    print("Domain changed: " + domain);
    Script.setTimeout(checkForPhysics, 1000);
}

Window.domainChanged.connect(onDomainChanged);
(static) isPointOnDesktopWindow( point ) → {boolean}
Returns: true if the point is within the window or HUD, otherwise false.

Checks if a 2D point is within the desktop window if in desktop mode, or the drawable area of the HUD overlay if in HMD mode.

Parameters

Name Type Description
point Vec2

The point to check.

(static) makeConnection( success, description )

Emits a connectionAdded or a connectionError signal that indicates whether or not a user connection was successfully made using the Web API.

Parameters

Name Type Description
success boolean

If true then connectionAdded is emitted, otherwise connectionError is emitted.

description string

Descriptive text about the connection success or error. This is sent in the signal emitted.

(static) openAndroidActivity( activityName, backToScene )

Opens an Android activity and optionally return back to the scene when the activity is completed. Android only.

Parameters

Name Type Description
activityName string

The name of the activity to open: one of "Home", "Login", or "Privacy Policy".

backToScene boolean

If true, the user is automatically returned back to the scene when the activity is completed.

(static) openMessageBox( title, text, buttons, defaultButton ) → {number}
Returns: The ID of the message box created.

Opens a non-modal message box that can have a variety of button combinations. See also, updateMessageBox and closeMessageBox.

Parameters

Name Type Description
title string

The title to display for the message box.

text string

Text to display in the message box.

buttons Window.MessageBoxButton

The buttons to display on the message box; one or more button values added together.

defaultButton Window.MessageBoxButton

The button that has focus when the message box is opened.

Example

Ask the user whether that want to reset something.

var messageBox;
var resetButton = 0x4000000;
var cancelButton = 0x400000;

function onMessageBoxClosed(id, button) {
    if (id === messageBox) {
        if (button === resetButton) {
            print("Reset");
        } else {
            print("Don't reset");
        }
    }
}
Window.messageBoxClosed.connect(onMessageBoxClosed);

messageBox = Window.openMessageBox("Reset Something", 
    "Do you want to reset something?",
    resetButton + cancelButton, cancelButton);
(static) openUrl( url )

Opens a URL in the Interface window or other application, depending on the URL's scheme. The following schemes are supported:

  • hifi: Navigate to the URL in Interface.
  • hifiapp: Open a system app in Interface.

Other schemes will either be handled by the OS (e.g. http, https, or mailto) or will display a dialog asking the user to confirm that they want to try to open the URL.

Parameters

Name Type Description
url string

The URL to open.

(static) openWebBrowser( urlopt )

Opens an Interface web browser window.

Parameters

Name Type Attributes Default Value Description
url string <optional>
""

The URL of the web page to display.

(static) prompt( message, defaultText ) → {string}
Returns: The text that the user entered if they select "OK", otherwise "".

Prompts the user to enter some text. Displays a modal dialog with a message and a text box, plus "OK" and "Cancel" buttons.

Parameters

Name Type Description
message string

The question to display.

defaultText string

The default answer text.

Example

Ask the user a question requiring a text answer.

var answer = Window.prompt("Question", "answer");
if (answer === "") {
    print("User canceled");
} else {
    print("User answer: " + answer);
}
(static) promptAsync( messageopt, defaultTextopt )

Prompts the user to enter some text. Displays a non-modal dialog with a message and a text box, plus "OK" and "Cancel" buttons. A promptTextChanged signal is emitted when the user OKs the dialog; no signal is emitted if the user cancels the dialog.

Parameters

Name Type Attributes Default Value Description
message string <optional>
""

The question to display.

defaultText string <optional>
""

The default answer text.

Example

Ask the user a question requiring a text answer without waiting for the answer.

function onPromptTextChanged(text) {
    print("User answer: " + text);
}
Window.promptTextChanged.connect(onPromptTextChanged);

Window.promptAsync("Question", "answer");
print("Script continues without waiting");
(static) protocolSignature( ) → {string}
Returns: A string uniquely identifying the version of the metaverse protocol that Interface is using.

Gets the signature for Interface's protocol version.

(static) raise( )

Raises the Interface window if it is minimized. If raised, the window gains focus.

(static) save( titleopt, directoryopt, nameFilteropt ) → {string}
Returns: The path and name of the file if one is specified, otherwise null. If a single file type is specified in the nameFilter, that file type extension is automatically appended to the result when appropriate.

Prompts the user to specify the path and name of a file to save to. Displays a modal dialog that navigates the directory tree and allows the user to type in a file name.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example

Ask the user to specify a file to save to.

var filename = Window.save("Save to JSON file", Paths.resources, "*.json");
print("File: " + filename);
(static) saveAsync( titleopt, directoryopt, nameFilteropt )

Prompts the user to specify the path and name of a file to save to. Displays a non-modal dialog that navigates the directory tree and allows the user to type in a file name. A saveFileChanged signal is emitted when a file is specified; no signal is emitted if the user cancels the dialog.

Parameters

Name Type Attributes Default Value Description
title string <optional>
""

The title to display at the top of the dialog.

directory string <optional>
""

The initial directory to start browsing at.

nameFilter string <optional>
""

The types of files to display. Examples: "*.json" and "Images (*.png *.jpg *.svg)". All files are displayed if a filter isn't specified.

Example

Ask the user to specify a file to save to without waiting for an answer.

function onSaveFileChanged(filename) {
    print("File: " + filename);
}
Window.saveFileChanged.connect(onSaveFileChanged);

Window.saveAsync("Save to JSON file", Paths.resources, "*.json");
print("Script continues without waiting");
(static) setActiveDisplayPlugin( index )

Sets the currently active display plugin.

Parameters

Name Type Description
index number

The index of the display plugin. Must be less than the value returned by getDisplayPluginCount. The first display plugin has an index of 0.

(static) setDisplayTexture( texture ) → {boolean}
Returns: true if the display texture was successfully set, otherwise false.

Sets what to show on the PC display. For entity camera view, the entity camera is configured using Camera.setCameraEntity and Camera.mode.

Parameters

Name Type Description
texture Window.DisplayTexture

The view to display.

(static) setFocus( )

Makes the Interface window have focus. On Windows, if Interface doesn't already have focus, the task bar icon flashes to indicate that Interface wants attention but focus isn't taken away from the application that the user is using.

(static) shareSnapshot( path, hrefopt )

Prepares a snapshot ready for sharing. A snapshotShared signal is emitted when the snapshot has been prepared.

Parameters

Name Type Attributes Default Value Description
path string

The path and name of the image file to share.

href string <optional>
""

The metaverse location where the snapshot was taken.

(static) showAssetServer( uploadFileopt )

Opens the Asset Browser dialog. If a file to upload is specified, the user is prompted to enter the folder and name to map the file to on the asset server.

Parameters

Name Type Attributes Default Value Description
uploadFile string <optional>
""

The path and name of a file to upload to the asset server.

Example

Upload a file to the asset server.

var filename = Window.browse("Select File to Add to Asset Server", Paths.resources);
print("File: " + filename);
Window.showAssetServer(filename);
(static) takeSecondaryCamera360Snapshot( cameraPosition, cubemapOutputFormatopt, notifyopt, filenameopt )

Takes a 360° snapshot at a given position for the secondary camera. The secondary camera does not need to have been set up.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

Parameters

Name Type Attributes Default Value Description
cameraPosition Vec3

The position of the camera for the snapshot.

cubemapOutputFormat boolean <optional>
false

If true then the snapshot is saved as a cube map image, otherwise it is saved as an equirectangular image.

notify boolean <optional>
true

This value is passed on through the stillSnapshotTaken signal.

filename string <optional>
""

If a filename is not provided, the image is saved as "vircadia-snap-by-<user name>-on-YYYY-MM-DD_HH-MM-SS".

Images are saved in JPEG or PNG format according to the extension provided — ".jpg", ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of ".jpg".

(static) takeSecondaryCameraSnapshot( notifyopt, filenameopt )

Takes a still snapshot of the current view from the secondary camera that can be set up through the Render API.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

Parameters

Name Type Attributes Default Value Description
notify boolean <optional>
true

This value is passed on through the stillSnapshotTaken signal.

filename string <optional>
""

If a filename is not provided, the image is saved as "vircadia-snap-by-<user name>-on-YYYY-MM-DD_HH-MM-SS".

Images are saved in JPEG or PNG format according to the extension provided — ".jpg", ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of ".jpg".

(static) takeSnapshot( notifyopt, includeAnimatedopt, aspectRatioopt, filenameopt )

Takes a snapshot of the current Interface view from the primary camera. When a still image only is captured, stillSnapshotTaken is emitted; when a still image plus moving images are captured, processingGifStarted and processingGifCompleted are emitted.

Snapshots are saved to the path specified in Settings > General > Snapshots, which can be accessed via the Snapshot API.

Parameters

Name Type Attributes Default Value Description
notify boolean <optional>
true

This value is passed on through the stillSnapshotTaken signal.

includeAnimated boolean <optional>
false

If true, a moving image is captured as an animated GIF in addition to a still image.

aspectRatio number <optional>
0

The width/height ratio of the snapshot required. If the value is 0, the full resolution is used (window dimensions in desktop mode; HMD display dimensions in HMD mode), otherwise one of the dimensions is adjusted in order to match the aspect ratio.

filename string <optional>
""

If a filename is not provided, the image is saved as "vircadia-snap-by-<user name>-on-YYYY-MM-DD_HH-MM-SS".

Still images are saved in JPEG or PNG format according to the extension provided — ".jpg", ".jpeg", or ".png" — or if not provided then in JPEG format with an extension of ".jpg". Animated images are saved in GIF format.

Example

Using the snapshot function and signals.

function onStillSnapshotTaken(path, notify) {
    print("Still snapshot taken: " + path);
    print("Notify: " + notify);
}

function onProcessingGifStarted(stillPath) {
    print("Still snapshot taken: " + stillPath);
}

function onProcessingGifCompleted(animatedPath) {
    print("Animated snapshot taken: " + animatedPath);
}

Window.stillSnapshotTaken.connect(onStillSnapshotTaken);
Window.processingGifStarted.connect(onProcessingGifStarted);
Window.processingGifCompleted.connect(onProcessingGifCompleted);

var notify = true;
var animated = true;
var aspect = 1920 / 1080;
var filename = "example-snapshot";
Window.takeSnapshot(notify, animated, aspect, filename);
(static) updateMessageBox( id, title, text, buttons, defaultButton )

Updates the content of a message box that was opened with openMessageBox.

Parameters

Name Type Description
id number

The ID of the message box.

title string

The title to display for the message box.

text string

Text to display in the message box.

buttons Window.MessageBoxButton

The buttons to display on the message box; one or more button values added together.

defaultButton Window.MessageBoxButton

The button that has focus when the message box is opened.

Signal Details

announcement( message )
Returns: Signal

Triggered when a message is announced by displayAnnouncement.

Parameters

Name Type Description
message string

The message text.

assetsDirChanged( asset )
Returns: Signal

Triggered when the user chooses an asset in a browseAssetsAsync dialog.

Parameters

Name Type Description
asset string

The path and name of the asset the user chose in the dialog.

browseChanged( filename )
Returns: Signal

Triggered when the user chooses a file in a browseAsync dialog.

Parameters

Name Type Description
filename string

The path and name of the file the user chose in the dialog.

browseDirChanged( directory )
Returns: Signal

Triggered when the user chooses a directory in a browseDirAsync dialog.

Parameters

Name Type Description
directory string

The directory the user chose in the dialog.

connectionAdded( message )
Returns: Signal

Triggered when you've successfully made a user connection.

Parameters

Name Type Description
message string

A description of the success.

connectionError( message )
Returns: Signal

Triggered when you failed to make a user connection.

Parameters

Name Type Description
message string

A description of the error.

domainChanged( domainURL )
Returns: Signal

Triggered when you change the domain you're visiting.

Warning: Is not emitted if you go to a domain that isn't running.

Parameters

Name Type Description
domainURL string

The domain's URL.

Example

Report when you change domains.

function onDomainChanged(domain) {
    print("Domain changed: " + domain);
}

Window.domainChanged.connect(onDomainChanged);
domainConnectionRefused( reasonMessage, reasonCode, extraInfo )
Returns: Signal

Triggered when you try to visit a domain but are refused connection.

Parameters

Name Type Description
reasonMessage string

A description of the refusal.

reasonCode Window.ConnectionRefusedReason

Integer number that enumerates the reason for the refusal.

extraInfo string

Extra information about the refusal.

geometryChanged( geometry )
Returns: Signal

Triggered when the position or size of the Interface window changes.

Parameters

Name Type Description
geometry Rect

The position and size of the drawable area of the Interface window.

Example

Report the position of size of the Interface window when it changes.

function onWindowGeometryChanged(rect) {
    print("Window geometry: " + JSON.stringify(rect));
}

Window.geometryChanged.connect(onWindowGeometryChanged);
interstitialModeChanged( interstitialMode )
Returns: Signal

Triggered when the interstitial mode changes.

Parameters

Name Type Description
interstitialMode boolean

true if the interstitial graphics are displayed when the domain is loading, false if they are not.

messageBoxClosed( id, button )
Returns: Signal

Triggered when the user closes a message box that was opened with openMessageBox.

Parameters

Name Type Description
id number

The ID of the message box that was closed.

button number

The button that the user clicked. If the user presses Esc, the Cancel button value is returned, whether or not the Cancel button is displayed in the message box.

minimizedChanged( isMinimized )
Returns: Signal

Triggered when "minimized" state of the Interface window changes.

Parameters

Name Type Description
isMinimized boolean

true if the Interface window is minimized, false if it isn't.

Example

Report the "minimized" state of the Interface window when it changes.

function onWindowMinimizedChanged(minimized) {
    print("Window minimized: " + minimized);
}

Window.minimizedChanged.connect(onWindowMinimizedChanged);
     
processingGifCompleted( pathAnimatedSnapshot )
Returns: Signal

Triggered when a GIF has been prepared of the snapshot images captured by takeSnapshot.

Parameters

Name Type Description
pathAnimatedSnapshot string

The path and name of the moving snapshot GIF file.

processingGifStarted( pathStillSnapshot )
Returns: Signal

Triggered when the snapshot images have been captured by takeSnapshot and the GIF is starting to be processed.

Parameters

Name Type Description
pathStillSnapshot string

The path and name of the still snapshot image file.

promptTextChanged( text )
Returns: Signal

Triggered when the user OKs a promptAsync dialog.

Parameters

Name Type Description
text string

The text the user entered in the dialog.

redirectErrorStateChanged( isInErrorState )
Returns: Signal

Triggered when you try to visit a domain but are redirected into the error state.

Parameters

Name Type Description
isInErrorState boolean

true if the user has been redirected to the error URL, false if they haven't.

saveFileChanged( filename )
Returns: Signal

Triggered when the user specifies a file in a saveAsync dialog.

Parameters

Name Type Description
filename string

The path and name of the file that the user specified in the dialog.

snapshot360Taken( pathStillSnapshot, notify )
Returns: Signal

Triggered when a still 360° snapshot has been taken by calling takeSecondaryCamera360Snapshot.

Parameters

Name Type Description
pathStillSnapshot string

The path and name of the snapshot image file.

notify boolean

The value of the notify parameter that takeSecondaryCamera360Snapshot was called with.

snapshotShared( isError, reply )
Returns: Signal

Triggered when a snapshot submitted via shareSnapshot is ready for sharing. The snapshot may then be shared via the Account.metaverseServerURL Web API.

Parameters

Name Type Description
isError boolean

true if an error was encountered preparing the snapshot for sharing, otherwise false.

reply string

JSON-formatted information about the snapshot.

stillSnapshotTaken( pathStillSnapshot, notify )
Returns: Signal

Triggered when a still snapshot has been taken by calling takeSnapshot with includeAnimated = false or takeSecondaryCameraSnapshot.

Parameters

Name Type Description
pathStillSnapshot string

The path and name of the snapshot image file.

notify boolean

The value of the notify parameter that takeSnapshot was called with.

svoImportRequested( url )
Returns: Signal

Triggered when you try to navigate to a *.json, *.svo, or *.svo.json URL in a Web browser within Interface.

Parameters

Name Type Description
url string

The URL of the file to import.