Window

Description

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.

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

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.
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 a web browser in a pop-up 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 model 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-model 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.
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.
LoginError 2 You could not be logged into the domain.
NotAuthorized 3 You are not authorized to connect to the domain.
TooManyUsers 4 The domain already has its maximum number of users.
TimedOut 5 Connecting to the domain timed out.

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) 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( )

Opens a web browser in a pop-up window.

(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 model 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-model 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 "hifi-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 "hifi-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 "hifi-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.
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.