Object “app”

Object > NativeObject > App

Provides information about the application and allows to handle global application ui events.

Type: App extends NativeObject
Constructor: private
Singleton: app
Namespace: tabris
Direct subclasses: None
JSX Support: No

See also:

JSX Displaying app properties [► Run in Playground]
JSX Displaying app events [► Run in Playground]
JSX Launching an url [► Run in Playground]
JS Register and use an external font [► Run in Playground]
JSX Share various types of data with the share() API [► Run in Playground]

Methods

close()

Android

Shuts down the running application and closes the UI.

Returns: undefined

getResourceLocation(path)

Returns the URL for a given resource that is bundled with the app. Can be used to access app resources like images, videos, etc. Note that these resources can only be accessed in read-only mode.

Parameter Type Description
path string The path of a resource relative to the application root.

Returns: string

launch(url)

Asks the operating system to open the given URL in an external app. Operating systems usually support a variety of URL schemes including http, https, mailto, tel, and sms. Apps can also register for custom URL schemes.

Parameter Type Description
url string The URL to launch.

Returns: Promise

See also:

JSX app-launch.jsx [► Run in Playground]

registerFont(alias, file)

Allows to register a font to use throughout the app. Once a font is registered its alias can be used to apply the font where ever a font can be configured, e.g. in TextView or GraphicalContext. Tabris.js supports TrueType fonts (.ttf) and OpenType fonts (.otf).

Parameter Type Description
alias string An identifier for the registered font. The alias can be used as a font family, e.g. in the font properties of TextView and Button.
file string The font file to register for later use. Similar to images paths, the file path can be absolute, relative or an URL.

Returns: undefined

reload(url?)

Closes the running application and either loads a different app at the given url or reloads the current app when no url is given.

Parameter Type Description
url string An optional url to an app to launch Optional.

Returns: undefined

share(data)

Asks the operating system to share data with another installed app. The returned promise resolves successfully when the data was shared with another app. The resolved promise contains a string providing platform specific information about the share target. In case sharing was not possible or the share operation has been canceled by the user, the promise is rejected with an appropriate error message.

The behavior of this API follows the W3C Web Share API.

In order to be able to share an image to the photo app on iOS, the Tabris.js app has to include the text string NSPhotoLibraryAddUsageDescription in its plist file. The string is used in the native permission dialog. See the 'camera' permissions docs for examples on how to configure the string.

Parameter Type Description
data {
  title: string, // Text to show in the share dialog. optional
  text: string, // A piece of text to share with another app. optional
  url: string, // A url to share with another app. optional
  files: File[] // An array of `File` objects to share with another app. optional
}		 The data to share. The object must contain at least one of the properties: title, text, url or files. The files need to have a name and mime type set.

On iOS the content of the url is previewed in the native share dialog. On Android it is treated as regular text. When both text and url are given on Android the two strings are concatenated with a blank space as defined in the W3C Web Share API.

Returns: Promise<string>

See also:

JSX app-share.jsx [► Run in Playground]

Properties

debugBuild

Returns false if this app was build build in production mode, otherwise true. In production mode no debugger can be attached to the JavaScript VM or native runtime.

Type: boolean
Settable: No
Change Event: Not supported

id

Uniquely identifies the app.

Type: string
Settable: No
Change Event: Not supported

idleTimeoutEnabled

Allows to control the device idle timout. When disabled the device will not go into sleep mode and turn off the screen to safe battery power.

The idleTimeoutEnabled will disable any system wide enabled idle settings while the app is in the foreground.

Type: boolean
Default: true
Settable: Yes
Change Event: idleTimeoutEnabledChanged

pinnedCertificates

Enables certificate pinning for HTTP requests. When pinned certificates are defined for a host, connections to this host will only be permitted if the server provides a matching certificate. Connections to hosts that are not in the list are not affected.

Certificate pinning affects the following components: XHR/fetch, WebSockets and image loading. It does not affect WebViews.

The list of pinned certificates has to be in the form of [{host: <string>, hash: <string>, algorithm: <RSA2048|RSA4096|ECDSA256>}, ..].

  • The host attribute denotes the host name (including subdomain) of the host to be pinned (wildcards allowed).
  • The hash attribute is the base64 encoded sha256 fingerprint of the subjectPublicKeyInfo, prefixed with sha256/.
  • The algorithm attribute denotes the public key algorithm of the SSL certificate and can have the values RSA2048, RSA4096 or ECDSA256. This attribute is only required on iOS.

Example: [{host: 'freegeoip.net', hash: 'sha256/+SVYjThgePRQxQ0e8bWTQDRtPYR/xBRufqyMoeaWteo=', algorithm: 'ECDSA256'}]

For further details see https://www.owasp.org/index.php/Certificate_and_Public_Key_Pinning.

Type: any[]
Settable: Yes
Change Event: pinnedCertificatesChanged

trustedCertificates

Adds a set of certificates to validated ssl connections against. The certificates are applied in addition to the system wide default certificates.

The ArrayBuffer entries of the trustedCertificates array consist of the bytes of the certificate files. On Android the certificate file has to be a *.pem (Privacy Enhanced Mail) file whereas on iOS it has to be *.der (Distinguished Encoding Rules) file.

Type: ArrayBuffer[]
Settable: Yes
Change Event: trustedCertificatesChanged

version

The user facing version number of the app.

Type: string
Settable: No
Change Event: Not supported

versionCode

An alternative version number used in app stores to identify different versions of an app. Usually incremented with each release. This property reflects the versionCode on Android and CFBundleVersion on iOS.

Type: number
Settable: No
Change Event: Not supported

Events

foreground

The event is fired when the app starts or when it returns from the background.

EventObject Type: EventObject<App>

This event has no additional parameter.

resume

Fired when the app is visible and ready to interact with the user. The event is preceded by either foreground (the app becomes visible again) or pause (the app regains ability to interact with user).

EventObject Type: EventObject<App>

This event has no additional parameter.

pause

Fired when the app is not the interaction target of the user anymore. Usually preceded by resume.

EventObject Type: EventObject<App>

This event has no additional parameter.

background

Fired when the app becomes invisible. Either because another app is in the foreground or the user has returned to the home screen.

EventObject Type: EventObject<App>

This event has no additional parameter.

terminate

Fired when the app is being destroyed. After this callback no more interaction with the app is possible.

On Android the terminate event is fired when closing the app via the back navigation or when the system shuts down the app to reclaim memory. In case the app is hard killed by eg. clearing it from the app switcher, the event is not fired.

On iOS the event might not always be fired reliably due to the scheduling behavior of the underlying operating system.

It is therefore recommended to use the event to clean up resources but not to rely on it for mission critical operations.

EventObject Type: EventObject<App>

This event has no additional parameter.

keyPress

Android

Fired when a hardware key is pressed. Note that these events stem from physical hardware, not from the virtual keyboard.

When invoking event.preventDefault() the key event is not propagated to the widget hierarchy. However, a TextInput with focus will still receive the key event.

EventObject Type: AppKeyPressEvent<App>

Property Type Description
action 'up' | 'down' The action of this key event.
altKey boolean The pressed state of the ALT key.
character string The character generated by the specified key and modifier key state combination.
ctrlKey boolean The pressed state of the CTRL key.
deviceId number The id for the device that this event came from. An id of zero indicates that the event didn’t come from a physical device and maps to the default keymap. The other numbers are arbitrary and you shouldn’t depend on the values.
functionKey boolean The pressed state of the FUNCTION key.
keyCode number The key code of the key event. It represents the physical key that was pressed, not the Unicode character.
preventDefault Function Call to suppress the key events to be dispatched to the apps widget hierarchy. Note that a TextInput with focus will still receive the event and add a character to its text accordingly.
shiftKey boolean The pressed state of the SHIFT key.
time number The time this event occurred, in the android.os.SystemClock#uptimeMillis time base.

backNavigation

Android

Fired when a back navigation is invoked by the user.

EventObject Type: AppBackNavigationEvent<App>

Property Type Description
preventDefault Function Call to suppress the default back navigation behavior.

Change Events

pinnedCertificatesChanged

Fired when the pinnedCertificates property has changed.

EventObject Type: PropertyChangedEvent<App, Array>

Property Type Description
value any[] The new value of pinnedCertificates.

trustedCertificatesChanged

Fired when the trustedCertificates property has changed.

EventObject Type: PropertyChangedEvent<App, Array>

Property Type Description
value ArrayBuffer[] The new value of trustedCertificates.

idleTimeoutEnabledChanged

Fired when the idleTimeoutEnabled property has changed.

EventObject Type: PropertyChangedEvent<App, boolean>

Property Type Description
value boolean The new value of idleTimeoutEnabled.

See Also

Get involved

Help us improve Tabris.js!

Install the app

Use the Tabris.js app to try examples and run your own snippets.