TabletProxy

Description

An instance of a tablet. In toolbar mode (Developer > UI > Tablet Becomes Toolbar), the tablet's menu buttons are displayed in a toolbar and other tablet content is displayed in a dialog.

Create a new tablet or retrieve an existing tablet using Tablet.getTablet.

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

Constructor
new TabletProxy( )

Properties

Name Type Summary
name string A unique name that identifies the tablet. Read-only.
toolbarMode boolean true if the tablet is in toolbar mode, false if it isn't.
landscape boolean true if the tablet is displayed in landscape mode, false if it is displayed in portrait mode.

Note: This property isn't used in toolbar mode.

tabletShown boolean true if the tablet is currently displayed, false if it isn't.

Note: This property isn't used in toolbar mode.

buttons TabletProxy.TabletButtonListModel Information on the buttons in the tablet main menu (or toolbar in toolbar mode) for use in QML. Read-only.

Methods

Name Return Value Summary
addButton TabletButtonProxy Adds a new button to the tablet menu.
closeDialog None Closes any open modal, non-modal, or message dialog, opened by Window.prompt, Window.promptAsync, Window.openMessageBox, or similar.
desktopWindowClosed None

Deprecated: This function is deprecated and will be removed.

emitScriptEvent None Sends a message to the current web page. To receive the message, the web page's script must connect to the EventBridge that is automatically provided to the script:
EventBridge.scriptEventReceived.connect(function(message) {
    ...
});
emitWebEvent None

Deprecated: This function is deprecated and will be removed.

getLandscape boolean Gets whether the tablet is displayed in landscape or portrait mode.

Note: The setting isn't used in toolbar mode.

gotoHomeScreen None Displays the tablet home screen, if the tablet is open.
gotoMenuScreen None Displays the tablet menu. The tablet is opened if it isn't already open.
gotoWebScreen None Opens a web page or app on the tablet.
initialScreen None

Deprecated: This function is deprecated and will be removed.

isMessageDialogOpen boolean Checks if the tablet has a modal, non-modal, or message dialog open.
isPathLoaded boolean Checks if a path is the current app or dialog displayed.
loadQMLOnTop None Opens a QML app or dialog in addition to any current app. In tablet mode, the app or dialog is displayed over the top of the current app; in toolbar mode, the app or dialog is opened in a new window. If in tablet mode, the app can be closed using TabletProxy#returnToPreviousApp.
loadQMLSource None Opens a QML app or dialog on the tablet.
loadWebScreenOnTop None Opens a web app or page in addition to any current app. In tablet mode, the app or page is displayed over the top of the current app; in toolbar mode, the app is opened in a new window. If in tablet mode, the app or page can be closed using TabletProxy#returnToPreviousApp.
onHomeScreen boolean Checks if the tablet is on the home screen.
onTabletShown None

Deprecated: This function is deprecated and will be removed.

popFromStack None Closes a QML dialog that was displayed using pushOntoStack with a dialog implementing a QML StackView; otherwise, no action is taken.

If using a QML StackView, its popSource() function is called.

pushOntoStack boolean Displays a QML dialog over the top of the current dialog, without closing the current dialog. Use popFromStack to close the dialog.

If the current dialog or its ancestors contain a QML StackView with objectName: "stack" and function pushSource(path), that function is called; otherwise, loadQMLSource is called. The Create app provides an example of using a QML StackView.

removeButton None Removes a button from the tablet menu.
returnToPreviousApp None Closes the current app and returns to the previous app, if in tablet mode and the current app was loaded using loadQMLOnTop or loadWebScreenOnTop.
sendToQml None Sends a message to the current QML page. To receive the message, the QML page must implement a function:
function fromScript(message) {
  ...
}
setLandscape None Sets whether the tablet is displayed in landscape or portrait mode.

Note: The setting isn't used in toolbar mode.

Signals

Name Summary
fromQml Triggered when a message from the current QML page displayed on the tablet is received. The QML page can send a message (string or object) by calling:
sendToScript(message);
screenChanged Triggered when the tablet's screen changes.
tabletShownChanged Triggered when the tablet is opened or closed.

Note: Doesn't apply in toolbar mode.

toolbarModeChanged Triggered when the tablet's toolbar mode changes.
webEventReceived Triggered when a message from the current HTML web page displayed on the tablet is received. The HTML web page can send a message by calling:
EventBridge.emitWebEvent(message);

Type Definitions

TabletButtonListModel
Type: object

Information on the buttons in the tablet main menu (toolbar in toolbar mode) for use in QML. Has properties and functions per http://doc.qt.io/qt-5/qabstractlistmodel.html.

Method Details

addButton( properties ) → {TabletButtonProxy}
Returns: The button added.

Adds a new button to the tablet menu.

Parameters

Name Type Description
properties TabletButtonProxy.ButtonProperties Button properties.
Example

Add a menu button.

var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
var button = tablet.addButton({ text: "TEST" });

button.clicked.connect(function () {
    print("TEST button clicked");
});

Script.scriptEnding.connect(function () {
    tablet.removeButton(button);
});
closeDialog( )

Closes any open modal, non-modal, or message dialog, opened by Window.prompt, Window.promptAsync, Window.openMessageBox, or similar.

desktopWindowClosed( )

Deprecated: This function is deprecated and will be removed.

emitScriptEvent( message )

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

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

Parameters

Name Type Description
message string | object The message to send to the web page.
emitWebEvent( message )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
message object | string Message
getLandscape( ) → {boolean}
Returns: true if the tablet is displayed in landscape mode, false if it is displayed in portrait mode.

Gets whether the tablet is displayed in landscape or portrait mode.

Note: The setting isn't used in toolbar mode.

gotoHomeScreen( )

Displays the tablet home screen, if the tablet is open.

gotoMenuScreen( submenuopt )

Displays the tablet menu. The tablet is opened if it isn't already open.

Parameters

Name Type Attributes Default Value Description
submenu string <optional>
"" The name of a submenu to display, if any.
Example

Go to the "View" menu.

tablet.gotoMenuScreen("View");
gotoWebScreen( url, injectedJavaScriptUrlopt, loadOtherBaseopt )

Opens a web page or app on the tablet.

Parameters

Name Type Attributes Default Value Description
url string The URL of the web page or app.
injectedJavaScriptUrl string <optional>
"" The URL of JavaScript to inject into the web page.
loadOtherBase boolean <optional>
false If true, the web page or app is displayed in a frame with "back" and "close" buttons.
initialScreen( url )

Deprecated: This function is deprecated and will be removed.

Parameters

Name Type Description
url string URL.
isMessageDialogOpen( ) → {boolean}
Returns: true if a modal, non-modal, or message dialog is open, false if there isn't.

Checks if the tablet has a modal, non-modal, or message dialog open.

isPathLoaded( path ) → {boolean}
Returns: true if path is the current app or dialog, false if it isn't.

Checks if a path is the current app or dialog displayed.

Parameters

Name Type Description
path string The path to test.
loadQMLOnTop( path )

Opens a QML app or dialog in addition to any current app. In tablet mode, the app or dialog is displayed over the top of the current app; in toolbar mode, the app or dialog is opened in a new window. If in tablet mode, the app can be closed using TabletProxy#returnToPreviousApp.

Parameters

Name Type Description
path string The path to the app's QML.
loadQMLSource( path, resizableopt )

Opens a QML app or dialog on the tablet.

Parameters

Name Type Attributes Default Value Description
path string The path of the QML app or dialog.
resizable boolean <optional>
false true to make the dialog resizable in toolbar mode, false to have it not resizable.
loadWebScreenOnTop( path, injectedJavaScriptURLopt )

Opens a web app or page in addition to any current app. In tablet mode, the app or page is displayed over the top of the current app; in toolbar mode, the app is opened in a new window. If in tablet mode, the app or page can be closed using TabletProxy#returnToPreviousApp.

Parameters

Name Type Attributes Default Value Description
path string The URL of the web page or HTML app.
injectedJavaScriptURL string <optional>
"" The URL of JavaScript to inject into the web page.
onHomeScreen( ) → {boolean}
Returns: true if the tablet is on the home screen, false if it isn't.

Checks if the tablet is on the home screen.

onTabletShown( )

Deprecated: This function is deprecated and will be removed.

popFromStack( )

Closes a QML dialog that was displayed using pushOntoStack with a dialog implementing a QML StackView; otherwise, no action is taken.

If using a QML StackView, its popSource() function is called.

pushOntoStack( path ) → {boolean}
Returns: true if the dialog was successfully opened, false if it wasn't.

Displays a QML dialog over the top of the current dialog, without closing the current dialog. Use popFromStack to close the dialog.

If the current dialog or its ancestors contain a QML StackView with objectName: "stack" and function pushSource(path), that function is called; otherwise, loadQMLSource is called. The Create app provides an example of using a QML StackView.

Parameters

Name Type Description
path string The path to the dialog's QML.
removeButton( button )

Removes a button from the tablet menu.

Parameters

Name Type Description
button TabletButtonProxy The button to remove.
returnToPreviousApp( )

Closes the current app and returns to the previous app, if in tablet mode and the current app was loaded using loadQMLOnTop or loadWebScreenOnTop.

sendToQml( message )

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

function fromScript(message) {
  ...
}

Parameters

Name Type Description
message string | object The message to send to the QML page.
setLandscape( landscape )

Sets whether the tablet is displayed in landscape or portrait mode.

Note: The setting isn't used in toolbar mode.

Parameters

Name Type Description
landscape boolean true to display the tablet in landscape mode, false to display it in portrait mode.

Signal Details

fromQml( message )
Returns: Signal

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

sendToScript(message);

Parameters

Name Type Description
message string | object The message received.
screenChanged( type, url )
Returns: Signal

Triggered when the tablet's screen changes.

Parameters

Name Type Description
type string The type of the new screen or change: "Home", "Menu", "QML", "Web", "Closed", or "Unknown".
url string The url of the page displayed. Only valid for Web and QML.
tabletShownChanged( )
Returns: Signal

Triggered when the tablet is opened or closed.

Note: Doesn't apply in toolbar mode.

toolbarModeChanged( )
Returns: Signal

Triggered when the tablet's toolbar mode changes.

Example

Report when the system tablet's toolbar mode changes.

var tablet = Tablet.getTablet("com.highfidelity.interface.tablet.system");
tablet.toolbarModeChanged.connect(function () {
    print("Tablet toolbar mode changed to: " + tablet.toolbarMode);
});
// Use Developer > UI > Tablet Becomes Toolbar to change the toolbar mode.
webEventReceived( message )
Returns: Signal

Triggered when a message from the current HTML web page displayed on the tablet is received. The HTML web page can send a message by calling:

EventBridge.emitWebEvent(message);

Parameters

Name Type Description
message string | object The message received.