Window

Description

The Window API provides various facilities not covered elsewhere: window dimensions, window focus, normal or entity camera view, clipboard, announcements, user connections, common dialog boxes, snapshots, file import, domain changes, domain physics.

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.
location object Provides facilities for working with your current metaverse location. See location.
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 the domain is loading, otherwise false.

Default Value: true

Methods

Name Return Value Summary
alert None Display 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 Prompt the user to choose a file. Displays a modal dialog that navigates the directory tree.
browseAssets string Prompt the user to choose an Asset Server item. Displays a modal dialog that navigates the tree of assets on the Asset Server.
browseAssetsAsync None Prompt the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the Asset Server. A assetsDirChanged signal is emitted when an asset is chosen; no signal is emitted if the user cancels the dialog.
browseAsync None Prompt 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 Prompt the user to choose a directory. Displays a modal dialog that navigates the directory tree.
browseDirAsync None Prompt 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 Get Interface's build number.
closeMessageBox None Close a message box that was opened with openMessageBox.
confirm boolean Prompt the user to confirm something. Displays a modal dialog with a message plus "Yes" and "No" buttons. responds.
copyToClipboard None Copies text to the operating system's clipboard.
displayAnnouncement None Display a notification message. Notifications are displayed in panels by the default script, nofications.js. An announcement signal is emitted when this function is called.
getDeviceSize Vec2 Get the size of the drawable area of the Interface window if in desktop mode or the HMD rendering surface if in HMD mode.
getLastDomainConnectionError Window.ConnectionRefusedReason Gets the last domain connection error when a connection is refused.
has3DHTML boolean Returns true if device supports 3d HTML
hasFocus boolean Check if the Interface window has focus.
hasRift boolean Returns true if HTC Vive is connected (looks for hand controllers)
hasRift boolean Returns true if Oculus Rift is connected (looks for hand controllers)
hasRift boolean Returns true if device is standalone
isPhysicsEnabled boolean Check 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 Check 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 Emit a connectionAdded or a connectionError signal that indicates whether or not a user connection was successfully made using the Web API.
openAndroidActivity None Open an Android activity and optionally return back to the scene when the activity is completed. Android only.
openMessageBox number Open a non-modal message box that can have a variety of button combinations. See also, updateMessageBox and closeMessageBox.
openUrl None Open a URL in the Interface window or other application, depending on the URL's scheme. If the URL starts with hifi:// then that URL is navigated to in Interface, otherwise the URL is opened in the application the OS associates with the URL's scheme (e.g., a Web browser for http://).
prompt string Prompt the user to enter some text. Displays a modal dialog with a message and a text box, plus "OK" and "Cancel" buttons.
promptAsync None Prompt 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 Get the signature for Interface's protocol version.
raise None Raise the Interface window if it is minimized. If raised, the window gains focus.
save string Prompt 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 Prompt 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.
setDisplayTexture boolean Set what to show on the PC display: normal view or entity camera view. The entity camera is configured using Camera.setCameraEntity and Camera.mode.
setFocus None Make 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 Prepare a snapshot ready for sharing. A snapshotShared signal is emitted when the snapshot has been prepared.
showAssetServer None Open 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.
takeSecondaryCameraSnapshot None Takes a still snapshot of the current view from the secondary camera that can be set up through the Render 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. The path to store the snapshots and the length of the animated GIF to capture are specified in Settings > General > Snapshots. If user has supplied a specific filename for the snapshot: If the user's requested filename has a suffix that's contained within SUPPORTED_IMAGE_FORMATS, DON'T append ".jpg" to the filename. QT will save the image in the format associated with the filename's suffix. If you want lossless Snapshots, supply a `.png` filename. Otherwise, use `.jpeg` or `.jpg`. Otherwise, ".jpg" is appended to the user's requested filename so that the image is saved in JPG format. If the user hasn't supplied a specific filename for the snapshot: Save the snapshot in JPG format according to FILENAME_PATH_FORMAT
updateMessageBox None Update 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 displayed on the PC display.

Value View Displayed
"" Normal view.
"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 )

Display 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.

Prompt 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.

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

Prompt the user to choose an Asset Server item. Displays a non-modal dialog that navigates the tree of assets on the Asset Server. A 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 )

Prompt 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.

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

Prompt 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.

Get Interface's build number.

(static) closeMessageBox( id )

Close 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.

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

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 )

Display 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) getDeviceSize( ) → {Vec2}
Returns: The width and height of the Interface window or HMD rendering surface, in pixels.

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

(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) has3DHTML( ) → {boolean}
Returns: true if device supports 3d HTML, otherwise false.

Returns true if device supports 3d HTML

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

Check if the Interface window has focus.

(static) hasRift( ) → {boolean}
Returns: true if running on Windows, otherwise false.

Returns true if HTC Vive is connected (looks for hand controllers)

(static) hasRift( ) → {boolean}
Returns: true if running on Windows, otherwise false.

Returns true if Oculus Rift is connected (looks for hand controllers)

(static) hasRift( ) → {boolean}
Returns: true if device is a standalone device, otherwise false.

Returns true if device is standalone

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

Check 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.

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

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

Open 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.

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

Open a URL in the Interface window or other application, depending on the URL's scheme. If the URL starts with hifi:// then that URL is navigated to in Interface, otherwise the URL is opened in the application the OS associates with the URL's scheme (e.g., a Web browser for http://).

Parameters

Name Type Description
url string The URL to open.
(static) prompt( message, defaultText ) → {string}
Returns: The text that the user entered if they select "OK", otherwise "".

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

Prompt 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.

Get the signature for Interface's protocol version.

(static) raise( )

Raise 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.

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

Prompt 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) setDisplayTexture( texture ) → {boolean}
Returns: true if the display texture was successfully set, otherwise false.

Set what to show on the PC display: normal view or 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( )

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

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

Open 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.

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 is saved as an equirectangular image.
notify boolean <optional>
true This value is passed on through the stillSnapshotTaken signal.
filename string <optional>
"" If this parameter is not supplied, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". If this parameter is "" then the image will be saved as ".jpg". Otherwise, the image will be saved to this filename, with an appended ".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.

Parameters

Name Type Attributes Default Value Description
notify boolean <optional>
true This value is passed on through the stillSnapshotTaken signal.
filename string <optional>
"" If this parameter is not given, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". If this parameter is "" then the image will be saved as ".jpg". Otherwise, the image will be saved to this filename, with an appended ".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. The path to store the snapshots and the length of the animated GIF to capture are specified in Settings > General > Snapshots. If user has supplied a specific filename for the snapshot: If the user's requested filename has a suffix that's contained within SUPPORTED_IMAGE_FORMATS, DON'T append ".jpg" to the filename. QT will save the image in the format associated with the filename's suffix. If you want lossless Snapshots, supply a `.png` filename. Otherwise, use `.jpeg` or `.jpg`. Otherwise, ".jpg" is appended to the user's requested filename so that the image is saved in JPG format. If the user hasn't supplied a specific filename for the snapshot: Save the snapshot in JPG format according to FILENAME_PATH_FORMAT

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 this parameter is not given, the image will be saved as "hifi-snap-by-<user name>-YYYY-MM-DD_HH-MM-SS". If this parameter is "" then the image will be saved as ".jpg". Otherwise, the image will be saved to this filename, with an appended ".jpg".
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 = "";
Window.takeSnapshot(notify, animated, aspect, filename);
(static) updateMessageBox( id, title, text, buttons, defaultButton )

Update 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 bool The new interstitial mode value. If true, the interstitial graphics are displayed when the domain is loading.
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 If true, the user has been redirected to the error URL.
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.