NuvolaKit 4 JavaScript API Reference

Introduction

This is a reference of public JavaScript API of NuvolaKit, the core part of Nuvola Apps Runtime. Undocumented parts of the API are considered unstable, internal or experimental, so you should not use them.

Prototypal inheritance

Unlike C++ or Java, JavaScript doesn't have class-based inheritance, but prototype-based inheritance. New objects are created from other object that are prototypes and inheritance creates prototype chain. While some JavaScript frameworks try to simulate the class-based inheritance, NuvolaKit enforces usage of Object.create() method to create new objects from prototypes and provides two convenience wrappers: Nuvola.$prototype to create new prototype objects and Nuvola.$object to create new instance objects.

Base API

Most of the integration scripts will probably use only a small part of the API:

Nuvola.$WebApp to create a new web app controller
Nuvola.MediaPlayer to provide playback details

Advanced API

If you want to do more magic, you will need new spells:

use Nuvola.config to store persistent configuration
use Nuvola.session to store temporary configuration or session information
override default signal handlers in Nuvola.WebApp
connect to Nuvola.core signals for URI manipulation and custom preferences
use Nuvola.actions to define custom actions (thumbs up, like, star rating, etc.)

Low-level API

Objects like Nuvola.menuBar, Nuvola.launcher, Nuvola.browser, Nuvola.mediaKeys are low-level components you probably don't want to use directly since Nuvola.MediaPlayer takes care about it.

Namespace Nuvola

Fields

field Nuvola.actions

Instance object of Actions prototype connected to Nuvola backend.
field Nuvola.browser

Instance object of Browser prototype connected to Nuvola backend.
field Nuvola.config

Instance object of ConfigStorage prototype connected to Nuvola backend.
field Nuvola.core

Instance object of Core prototype connected to Nuvola backend.
field Nuvola.global

Global JavaScript Object

Note that only the web worker process has global window object provided by a web browser engine. The app runner process has bare global object.
field Nuvola.launcher

Instance object of Launcher prototype connected to Nuvola backend.
field Nuvola.mediaKeys

Instance object of MediaKeys prototype connected to Nuvola backend.
field Nuvola.menuBar

Instance object of MenuBar prototype connected to Nuvola backend.
field Nuvola.session

Instance object of SessionStorage prototype connected to Nuvola backend.

Functions

function Nuvola.$WebApp()

Convenience function to create new prototype object extending WebApp prototype.
Returns
- new prototype object extending WebApp
```
var WebApp = Nuvola.$WebApp()
```
function Nuvola.$object(proto, initArgs)

Creates new initialized object from prototype.

Creates new object that will have proto as its prototype and will be initialized by calling $init method with provided arguments args. This is similar to creating an instance object from a class in class-based inheritance. Instance object names are in lowerCamelCase.
Parameters
- Object proto - object prototype or null to use Object
- variant initArgs... - arguments to pass to the $init method
Returns
- new initialized object
```
var house = Nuvola.$object(Building, 'King Street 1024, London')
house.printAddress()

var candyShop = Nuvola.$object(Shop, 'King Street 1024, London', 'candies')
candyShop.printAddress()
candyShop.printGoods()
```
function Nuvola.$prototype(proto, mixins)

Creates new object from prototype and mixins.

Creates new object that will have proto as its prototype and will be extended with properties from all specified mixins. This is similar to creating a subclass in class-based inheritance. See $object for instance object creation. Prototype object names are in UpperCamelCase.
Parameters
- Object|null proto - object prototype or null to use Object
- Object mixins... - mixins objects
Returns
- new prototype object
```
var Building = Nuvola.$prototype(null)

Building.$init = function (address) {
  this.address = address
}

Building.printAddress = function () {
  console.log(this.address)
}

var Shop = Nuvola.$prototype(Building)

Shop.$init = function (address, goods) {
  Building.$init.call(this, address)
  this.goods = goods
}

Shop.printGoods = function() {
  console.log(this.goods)
}
```
function Nuvola.checkVersion(major, minor, micro)

Check sufficient Nuvola's version
Available since API 4.5

Parameters
- Number major - major version
- Number minor - minor version
- Number micro - micro version
Returns
- true if Nuvola's version is greater than or equal to the required version
```
if (Nuvola.checkVersion && Nuvola.checkVersion(4, 5)) {
  // Safe to use API >= 4.5
}
```
function Nuvola.clickOnElement(elm, x, y)

Simulates click on element
Available since API 4.5: x, y coordinates were added.

Parameters
- HTMLElement elm - Element object
- Number x - Relative x position within the element 0.0..1.0 (default 0.5)
- Number y - Relative y position within the element 0.0..1.0 (default 0.5)
function Nuvola.encodeVersion(major, minor, micro)

Encode version info as a single number
Available since API 4.5

Parameters
- Number major - major version
- Number minor - minor version
- Number micro - micro version
Returns
- encoded version number
function Nuvola.exportImageAsBase64(url, callback)

Download image and export it as base64 data-URI
Available since API 4.11

Parameters
- String url - The image URL
- Function callback - The function to be called when the image is exported. The first argument is null if any error occurred, base64 data-URI otgerwise.
function Nuvola.format()

Replaces placeholders in a template string with provided data.

Placeholders are in form of {n} where n is index of data argument starting at 1. Special placeholders are {-1} for { and {-2} for }.
Parameters
- String template - template string
- Variant data... - other arguments will be used as data for replacement
Returns
- String
```
alert(Nuvola.format('My name is {2}. {1} {2}!', 'James', 'Bond'))
// 'My name is Bond. James Bond!'

// You can create an alias
var $fmt = Nuvola.format;
alert($fmt('My name is {2}. {1} {2}!', 'James', 'Bond'))
```
function Nuvola.log(template)

Log message to terminal

Note: This function doesn't print to JavaScript console of WebKit Web Inspector, but to real console/terminal.
Parameters
- String template - template string, see Nuvola.format for details
- Variant data... - other arguments will be used as data for replacement
function Nuvola.logException(e)

Log exception to terminal
Available since Nuvola 4.8

Parameters
- Exception e - The exception to log.
function Nuvola.makeElement(name, attributes, text)

Creates HTML element
Parameters
- String name - element name
- Object attributes - element attributes (optional)
- String text - text of the element (optional)
Returns
- new HTML element
function Nuvola.makeText(text)

Creates HTML text node
Parameters
- String text - text of the node
Returns
- new text node
function Nuvola.objectDiff(object1, object2)

Compares own properties of two objects
Parameters
- Object object1 - the first object to compare
- Object object2 - the second object to compare
Returns
- Array of names of different properties
function Nuvola.parseTimeUsec(time)

Parse time as number of microseconds
Parameters
- String time - time expression `HH:MM:SS'
Returns
- the time in microseconds
function Nuvola.queryAttribute(selector, attribute, func)

Query element and return its attribute or null.
Available since API 4.11

Available since API 4.12: You can specify a parent element and a relative selector as an array of [parent element, selector].

Parameters
- String|Array selector - CSS selector for element or an array containing [parent element, selector].
- String attribute - Attribute name.
- Function func - Optional function to modify resulting value.
Returns
- The attribute of the element, possibly modified with func, null if element is not found.
function Nuvola.queryText(selector, func)

Query element and return text content or null.
Available since API 4.11

Available since API 4.12: You can specify a parent element and a relative selector as an array of [parent element, selector].

Parameters
- String|Array selector - CSS selector for element or an array containing [parent element, selector].
- Function func - Optional function to modify resulting text.
Returns
- Text content of the element, possibly modified with func, null if element is not found.
function Nuvola.setInputValueWithEvent(elm, value)

Simulates input and change event
Available since API 4.11

Available since API 4.12: The change event is emitted as well.

Parameters
- HTMLInputElement elm - Input element object
- Var value - The value to set
async function Nuvola.showInfoBar(id, type, text)

Show infobar to user.
Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.

Available since Nuvola 4.10

Parameters
- String id - The id of the infobar. The same infobars should have the same id to prevent duplicity.
- InfoBarType type - The type of the message.
- String text - The text of the info bar.
Returns
- true if a new info bar has been show, false if there already is an info bar with the same id.
function Nuvola.triggerMouseEvent(elm, name, x, y)

Triggers mouse event on element
Available since API 4.5: x, y coordinates were added.

Parameters
- HTMLElement elm - Element object
- String name - Event name
- Number x - Relative x position within the element 0.0..1.0 (default 0.5)
- Number y - Relative y position within the element 0.0..1.0 (default 0.5)
function Nuvola.warn(template)

Log warning to terminal

Note: This function doesn't print to JavaScript console of WebKit Web Inspector, but to real console/terminal.
Parameters
- String template - template string, see Nuvola.format for details
- Variant data... - other arguments will be used as data for replacement

Prototypes

prototype Nuvola.Actions extends Object, contains Nuvola.SignalsMixin

Manages actions

Actions can be shown in various user interface components such as menu, tray icon menu, Unity HUD, Unity Laucher Quicklist, or invoked by keyboard shortcut, remote control, etc.

Some actions are provided by the Nuvola Player backend (e. g. browser actions), some are created by JavaScript API objects (e. g. media player actions) and web app integration scripts can create custom actions with Actions.addAction or Actions.addRadioAction.
- method $init()
  
  Initializes new Actions object
- method activate(name, parameter)
  
  Activate (invoke) action
  Parameters
  - String name - action name
  - optional Variant parameter - parameter to the action
- method addAction(group, scope, name, label, mnemoLabel, icon, keybinding, state)
  
  Adds new simple or toggle action.
  
  when action is activated, signal ActionActivated is emitted.
  Parameters
  - String group - action group, e.g. 'playback'
  - String scope - action scope, use 'win' for window-specific actions (preferred) or 'app' for app-specific actions
  - String name - action name, should be in dash-separated-lower-case, e.g. toggle-play
  - String|null label - label shown in user interface, e.g. Play
  - String|null mnemo_label - label shown in user interface with keyboard navigation using Alt key and letter prefixed with underscore, e.g. Alt+p for _Play
  - String|null icon - icon name for action
  - String|null keybinding - in-app keyboard shortcut, e.g. <ctrl>P
  - Boolean|null state - null for simple actions, true/false for toggle actions (on/off)
```
// Add new simple action ``play`` with icon ``media-playback-start``
Nuvola.actions.addAction('playback', 'win', 'play', 'Play', null, 'media-playback-start', null)

// Add new toggle action ``thumbs-up`` with initial state ``true`` (on)
Nuvola.actions.addAction('playback', 'win', 'thumbs-up', 'Thumbs up', null, null, null, true)
```
- method addRadioAction(group, scope, name, stateId, options)
  
  Adds new radio action (action with multiple states/option like old radios)
  
  when action is activated, signal ActionActivated is emitted.
  Parameters
  - String group - action group, e.g. 'playback'
  - String scope - action scope, use 'win' for window-specific actions (preferred) or 'app' for app-specific actions
  - String name - action name, should be in dash-separated-lower-case, e.g. toggle-play
  - variant stateId - initial state of the action. must be one of states specified in options array
  - Array options - array of options definition in form [stateId, label, mnemo_label, icon, keybinding]. stateId is unique identifier (Number or String), other parameters are described in addAction method.
```
// define rating options - 5 states with state id 0-5 representing 0-5 stars
var ratingOptions = [
  // stateId, label, mnemo_label, icon, keybinding
  [0, 'Rating: 0 stars', null, null, null, null],
  [1, 'Rating: 1 star', null, null, null, null],
  [2, 'Rating: 2 stars', null, null, null, null],
  [3, 'Rating: 3 stars', null, null, null, null],
  [4, 'Rating: 4 stars', null, null, null, null],
  [5, 'Rating: 5 stars', null, null, null, null]
]

// Add new radio action named ``rating`` with initial state ``0`` (0 stars)
Nuvola.actions.addRadioAction('playback', 'win', 'rating', 0, ratingOptions)
```
- method bindButton(button, name, parameter)
  
  Bind HTML button to an action
  
  The button.disabled and action.enabled properties are synchronized and action is activated when button is clicked.
  Parameters
  - HTMLButton button - HTML button element
  - String name - action name
  - optional Variant parameter - parameter to the action
```
var navigateBack = Nuvola.makeElement('button', null, '<')
var elm = document.getElementById('bar')
elm.appendChild(navigateBack)
Nuvola.actions.bindButton(navigateBack, Nuvola.BrowserAction.GO_BACK)
```
- method getState(name)
  
  Get current state of toggle or radio actions.
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String name - action name
  Returns
  - current state: true/false for toggle actions, one of stateId entries of radio actions
```
var thumbsUp = Nuvola.actions.getState('thumbs-up')
console.log('Thumbs up is toggled ' + (thumbsUp ? 'on' : 'off'))

var stars = Nuvola.actions.getState('rating')
console.log('Number of stars: ' + stars)
```
- async method getStateAsync(name)
  
  Get current state of toggle or radio actions.
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String name - action name
  Returns
  - current state: true/false for toggle actions, one of stateId entries of radio actions
```
Nuvola.actions.getStateAsync('thumbs-up').then(function (state) {
  console.log('Thumbs up is toggled ' + (state ? 'on' : 'off'));
})

Nuvola.actions.getStateAsync('rating').then(function (stars) {
  console.log('Number of stars: ' + stars)
})
```
- method isEnabled(name)
  
  Checks whether action is enabled
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String name - action name
  Returns
  - true is action is enabled, false otherwise
- async method isEnabledAsync(name)
  
  Checks whether action is enabled
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String name - action name
  Returns
  - true is action is enabled, false otherwise
- method setEnabled(name, enabled)
  
  Sets whether action is enabled
  
  Note: consider use of method Actions.updateEnabledFlag that is more effective, because it performs caching of enabled flags and updates them only if necessary.
  Parameters
  - String name - action name
  - Boolean enabled - true is action is enabled, false otherwise
- method setState(name, state)
  
  Set current state of toggle or radio actions.
  
  Note: consider use of method Actions.updateState that is more effective, because it performs caching of states and updates them only if necessary.
  Parameters
  - String name - action name
  - variant state - current state: true/false for toggle actions, one of stateId entries of radio actions
```
// toggle thumbs-up off
Nuvola.actions.setState('thumbs-up', false)

// Set 5 stars
Nuvola.actions.setState('rating', 5)
```
- method updateEnabledFlag(name, enabled)
  
  Update action enabled flag
  
  This method uses cache of action enabled flags to update them only if necessary.
  Parameters
  - String name - action name
  - Boolean enabled - true is action is enabled, false otherwise
- method updateEnabledFlags(enabledFlags)
  
  Bulk update of action enabled flags
  
  This method uses cache of action enabled flags to update them only if necessary.
  Parameters
  - Object enabledFlags - mapping of action name: enabled flag
- method updateState(name, state)
  
  Update of action state
  
  This method uses cache of action states to update them only if necessary.
  Parameters
  - String name - action name
  - variant state - current state: true/false for toggle actions, one of stateId entries of radio actions
- method updateStates(states)
  
  Bulk update of action states
  
  This method uses cache of action states to update them only if necessary.
  Parameters
  - Object states - mapping of action name: state
- signal ActionActivated(emitter, name, param)
  
  Emitted when an action is activated.
  Parameters
  - Actions emitter - object that emitted the signal
  - String name - action name
  - Variant param - action parameter, usually null
```
MyObject.$init = function () {
  Nuvola.actions.connect('ActionActivated', this)
}

MyObject._onActionActivated = function (emitter, name, param) {
  console.log('Action activated: ' + name)
}
```
- signal ActionEnabledChanged(emitter, name, enabled)
  
  Emitted when an action has been enabled or disabled.
  Parameters
  - Actions emitter - object that emitted the signal
  - String name - action name
  - Boolean enabled - true if the action is enabled
```
MyObject.$init = function () {
  Nuvola.actions.connect('ActionEnabledChanged', this)
}

MyObject._ActionEnabledChanged = function (emitter, name, enabled) {
  console.log('Action ' + name + ' ' + (enabled ? 'enabled' : 'disabled') + '.')
}
```
prototype Nuvola.Browser extends Object

Prototype object for web browser management
- method $init()
  
  Initializes new Browser object
- method downloadFileAsync(uri, basename, callback, data)
  
  Request download of a file
  Parameters
  - String uri - file to download
  - String basename - a filename of the result
  - Function callback - function to call after file is downloaded
  - Variant data - extra data passed to the callback
  callback will be called with two arguments:
  - result object with properties
    - success - true if the download has been successful, false otherwise
    - statusCode - a HTTP status code
    - statusText - description of the HTTP status code
    - filePath - filesystem path to the downloaded file
    - fileURI - URI of the downloaded file (file:///...)
  - data - data argument passed to downloadFileAsync
prototype Nuvola.ConfigStorage extends KeyValueStorage, contains Nuvola.SignalsMixin

Prototype object to access persistent configuration

Note: Use SessionStorage for temporary data.
- method $init()
  
  Initializes new ConfigStorage object
- signal ConfigChanged(emitter, key)
  
  Emitted when a configuration key is changed
  Parameters
  - ConfigStorage emitter - object that emitted the signal
  - String key - key name
prototype Nuvola.Core extends Object, contains Nuvola.SignalsMixin

Prototype object to manage Nuvola Player Core
- method $init()
  
  Initializes new Core instance object
- method getComponentInfo(id)
  
  Returns information about a component
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - id id - of the component
  Returns
  - Object component info
- async method getComponentInfoAsync(id)
  
  Returns information about a component
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - id id - of the component
  Returns
  - Object component info
- method isComponentActive(id)
  
  Returns whether a component is loaded and active
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - id id - of the component
  Returns
  - Boolean true if the component is active
- async method isComponentActiveAsync(id)
  
  Returns whether a component is loaded and active
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - id id - of the component
  Returns
  - Boolean true if the component is active
- method isComponentLoaded(id)
  
  Returns whether a component is loaded
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - id id - of the component
  Returns
  - Boolean true if the component is loaded
- async method isComponentLoadedAsync(id)
  
  Returns whether a component is loaded
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - id id - of the component
  Returns
  - Boolean true if the component is loaded
- method toggleComponentActive(id, active)
  
  Activates or deactivates a component
  
  The component must be loaded.
  Parameters
  - id id - of the component
  - Boolean active - whether to activate or deactivate the component
  Returns
  - Boolean true (since Nuvola 4.8)
- signal ComponentLoaded(emitter, name)
  
  Emitted when a component has been loaded.
  Parameters
  - Core emitter - object that emitted the signal
  - string name - the name of the component
- signal ComponentUnloaded(emitter, id, name)
  
  Emitted when a component has been unloaded.
  Parameters
  - Core emitter - object that emitted the signal
  - string id - the id of the component
  - string name - the name of the component
- signal HomePageRequest(emitter, request)
  
  Emitted on request for home page URL.
  
  See Web apps with a variable home page URL.
  Parameters
  - Core emitter - object that emitted the signal
  - String request.url - property to assign home page url to
```
var _onHomePageRequest = function (emitter, request) {
  request.url = "http://tiliado.eu"
}
```
- signal InitAppRunner(emitter)
  
  Emitted at start-up when initialization of the app runner process is needed. You can use it to perform own initialization routine.
  Parameters
  - Core emitter - object that emitted the signal
- signal InitWebWorker(emitter)
  
  InitWebWorker initialize web worker process hook
  
  This signal is emitted every time just before a web page is loaded in the main frame of the web view.
  Parameters
  - Core emitter - object that emitted the signal
- signal InitWebWorkerHelper(emitter)
  
  InitWebWorkerHelper initialize web worker helper hook
  
  This signal is emitted only once just before a web page is loaded in the main frame of the web view.
  Parameters
  - Core emitter - object that emitted the signal
- signal InitializationForm(emitter, values, fields)
  
  Emitted at start-up when initialization form is being built.
  Parameters
  - Core emitter - object that emitted the signal
  - Object values - mapping between form field names and their values
  - Array of FormFieldArray fields - specification of form fields, see Initialization and Preferences Forms for details
- signal LastPageRequest(emitter, result)
  
  Emitted on request for the last visited URL.
  Parameters
  - Core emitter - object that emitted the signal
  - String|null result.url - property to assign the last visited URL to
```
var _onLastPageRequest = function (emitter, result) {
  request.url = Nuvola.config.get("last_uri") || null
}
```
- signal NavigationRequest(emitter, request)
  
  Emitted on request for navigation to a new web page.
  Available since API 4.12: You can overwrite `request.url` field to force redirect.
  
  Parameters
  - Core emitter - object that emitted the signal
  - String request.url - URL of the new page, you can overwrite this field to force redirect
  - Boolean request.newWindow - whether to open request in a new window, you can overwrite this field
  - Boolean request.approved - whether the navigation is approved, set to false when the request.url should be opened in user's default web browser
```
var _onNavigationRequest = function (emitter, request) {
  request.approved = isAddressAllowed(request.url)
}
```
- signal PageSettings(emitter, request)
  
  Emitted on request for web page settings.
  Parameters
  - Core emitter - object that emitted the signal
  - String request.url - URL of the new page
  - Boolean request.newWindow - whether to open request in a new window, you can overwrite this field
  - Boolean request.javascript - whether javascript should be enabled
  - String request.userAgent - whether to override user agent string
```
var _onPageSettings = function (emitter, request) {
  request.userAgent = (
    request.url.startsWith("https://accounts.google.com/")
    || request.url.startsWith("https://accounts.youtube.com/")
    ? "WEBKIT" : null
    )
}
```
- signal PreferencesForm(emitter, values, entries)
  
  Emitted when preferences dialog is being built.
  Parameters
  - Core emitter - object that emitted the signal
  - Object values - mapping between form field names and their values
  - Array of FormFieldArray entries - specification of form fields, see Initialization and Preferences Forms for details
- signal QuitRequest(emitter, result)
  
  Emitted on request to quit the application by closing the main window.
  
  This signal is emitted in both App Runner and Web Worker processes.
  Parameters
  - Core emitter - object that emitted the signal
  - bool result.approved - Whether application can quit. If false, application will continue running in background.
```
var _onQuitRequest = function (emitter, result) {
  if (Nuvola.config.get("myapp.run_in_background")) {
    result.approved = false
  }
}
```
- signal ResourceRequest(emitter, request)
  
  Emitted on request for loading a web resource.
  Parameters
  - Core emitter - object that emitted the signal
  - String request.url - URL of the resource (can be overwritten)
  - Boolean request.approved - whether the resource loading is approved
```
var _onResourceRequest = function (emitter, request) {
  request.url = request.url.replace("webcomponents.js", "webcomponents2.js")
}
```
- signal UriChanged(emitter, uri)
  
  Emitted after approved navigation to a new page URL.
  Parameters
  - Core emitter - object that emitted the signal
  - string uri - URI of the new page
```
var _onUriChanged = function(emitter, uri) {
  Nuvola.config.set("last_uri", uri)
}
```
prototype Nuvola.KeyValueStorage extends Object

Prototype object to hold key-value mapping
- method $init(index)
  
  Initializes new key-value storage
  Parameters
  - Number index - index in storage pool
- method get(key)
  
  Get value by key name
  
  Note that behavior on a key without an assigned value nor the default value is undefined - it may return anything or throw and error. (The current implementation returns string '<UNDEFINED>' as it helps to identify unwanted manipulation with undefined value type.)
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String key - key name
  Returns
  - value set by KeyValueStorage.set or KeyValueStorage.setDefault for given key
- async method getAsync(key)
  
  Get value by key name
  
  Note that behavior on a key without an assigned value nor the default value is undefined - it may return anything or throw and error. (The current implementation returns string '<UNDEFINED>' as it helps to identify unwanted manipulation with undefined value type.)
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String key - key name
  Returns
  - value set by KeyValueStorage.set or KeyValueStorage.setDefault for given key
- method hasKey(key)
  
  Check whether the storage has given key
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String key - storage key name
  Returns
  - false if the storage doesn't contain value for the key (even if default value has been set), true otherwise
- async method hasKeyAsync(key)
  
  Check whether the storage has given key
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String key - storage key name
  Returns
  - false if the storage doesn't contain value for the key (even if default value has been set), true otherwise
- method set(key, value)
  
  Set value for given key
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String key - key name
  - Variant value - value of given key
- async method setAsync(key, value)
  
  Set value for given key
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String key - key name
  - Variant value - value of given key
- method setDefault(key, value)
  
  Set default value for given key
  
  This function should be called only once per key, for example in Core::InitAppRunner handler.
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Parameters
  - String key - the key name
  - Variant value - value of the key
```
WebApp._onInitAppRunner = function (emitter) {
  Nuvola.WebApp._onInitAppRunner.call(this, emitter)

  var ADDRESS = 'app.address'
  // Nuvola.config is a KeyValueStorage
  Nuvola.config.setDefault(ADDRESS, 'default')
}
```
- async method setDefaultAsync(key, value)
  
  Set default value for given key
  
  This function should be called only once per key, for example in Core::InitAppRunner handler.
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Parameters
  - String key - the key name
  - Variant value - value of the key
```
WebApp._onInitAppRunner = function(emitter) {
  Nuvola.WebApp._onInitAppRunner.call(this, emitter)

  var ADDRESS = 'app.address'
  // Nuvola.config is a KeyValueStorage
  Nuvola.config.setDefaultAsync(ADDRESS, 'default').catch(console.log.bind(console))
}
```
prototype Nuvola.Launcher extends Object

Manages launcher component (Unity dock item, tray icon, ...)
- method addAction(action)
  
  Add action to launcher's menu.
  Parameters
  - String action - action name
- method removeAction(action)
  
  Remove action from launcher's menu.
  Parameters
  - String action - action name
- method removeActions()
  
  Removes all launcher menu actions.
- method setActions(actions)
  
  Set launcher menu actions.
  
  This functionality has two implementations:
  - menu of a tray icon
  - menu of a Unity dock item
  Parameters
  - Array of String actions - action names
- method setTooltip(tooltip)
  
  Set launcher tooltip.
  
  This functionality is currently implemented only by the tray icon.
  Parameters
  - String tooltip - short tooltip text
prototype Nuvola.MediaKeys extends Object, contains Nuvola.SignalsMixin

Prototype object integrating media keys handling
- method $init()
  
  Initializes new MediaKeys object.
- signal MediaKeyPressed(emitter, key)
  
  Emitted when a media key is pressed.
  Parameters
  - MediaKeys emitter - object that emitted the signal
  - MediaKey key - the pressed key
prototype Nuvola.MediaPlayer extends Object, contains Nuvola.SignalsMixin

Media player controller.
- method $init()
  
  Initializes media player
- method addExtraActions(actions)
  
  Add actions for media player capabilities
  
  For example: star rating, thumbs up/down, like/love/unlike.
  
  Actions that have been already added are ignored.
  Parameters
  - Array of String actions - names of actions
- method setCanChangeVolume(canChangeVolume)
  
  Set whether it is possible to change volume
  
  If the argument is same as in the previous call, this method does nothing.
  Available since API 4.5
  
  Parameters
  - Boolean canChangeVolume - true if remote volume setting should be allowed
- method setCanGoNext(canGoNext)
  
  Set whether it is possible to go to the next track
  
  If the argument is same as in the previous call, this method does nothing.
  Parameters
  - Boolean canGoNext - true if the "go to next track" button is active
- method setCanGoPrev(canGoPrev)
  
  Set whether it is possible to go to the previous track
  
  If the argument is same as in the previous call, this method does nothing.
  Parameters
  - Boolean canGoPrev - true if the "go to previous track" button is active
- method setCanPause(canPause)
  
  Set whether it is possible to pause playback
  
  If the argument is same as in the previous call, this method does nothing.
  Parameters
  - Boolean canPause - true if the "pause" button is active
- method setCanPlay(canPlay)
  
  Set whether it is possible to start playback
  
  If the argument is same as in the previous call, this method does nothing.
  Parameters
  - Boolean canPlay - true if the "play" button is active
- method setCanRate(canRate)
  
  Set whether it is possible to rate tracks
  
  If rating is enabled, signal MediaPlayer::RatingSet is emitted. If the argument is same as in the previous call, this method does nothing.
  Available since API 3.1
  
  Parameters
  - Boolean canRate - true if remote rating should be allowed
- method setCanRepeat(canRepeat)
  
  Set whether it is possible to repeat a track or a playlist.
  
  If the argument is same as in the previous call, this method does nothing.
  Available since Nuvola 4.13
  
  Parameters
  - Boolean canRepeat - true if the repeat state can be changed.
- method setCanSeek(canSeek)
  
  Set whether it is possible to seek to a specific position of the track
  
  If the argument is same as in the previous call, this method does nothing.
  Available since API 4.5
  
  Parameters
  - Boolean canSeek - true if remote seeking should be allowed
- method setCanShuffle(canShuffle)
  
  Set whether it is possible to shuffle playlist.
  
  If the argument is same as in the previous call, this method does nothing.
  Available since Nuvola 4.13
  
  Parameters
  - Boolean canShuffle - true if shuffle state should be allowed
- method setPlaybackState(state)
  
  Set current playback state
  
  If the current state is same as the previous one, this method does nothing.
  Parameters
  - PlaybackState state - current playback state
- method setRepeatState(repeat)
  
  Set the current repeat state.
  
  If the current state is same as the previous one, this method does nothing.
  Parameters
  - PlayerRepeat repeat - The current repeat state.
- method setShuffleState(shuffle)
  
  Set the current shuffle state.
  
  If the argument is same as in the previous call, this method does nothing.
  Available since Nuvola 4.13
  
  Parameters
  - Boolean shuffle - true if the playback is in the shuffle mode
- method setTrack(track)
  
  Set info about currently playing track.
  
  If track info is same as in the previous call, this method does nothing.
  Parameters
  - String|null track.title - track title
  - String|null track.artist - track artist
  - String|null track.album - track album
  - String|null track.artLocation - URL of album/track artwork
  - double|null track.rating - track rating from 0.0 to 1.0. This item is ignored prior API 3.1.
  - double|null track.length - track length as a string (HH:MM:SS.xxx, e.g. 1:25.54) or number of microseconds. This item is ignored prior API 4.5.
- method setTrackPosition(position)
  
  Set current playback position
  
  If the current position is the same as the previous one, this method does nothing.
  Available since API 4.5
  
  Parameters
  - String|Number position - the current track position as a string (HH:MM:SS.xxx, e.g. 1:25.54) or number of microseconds.
- method updateVolume(volume)
  
  Update current volume
  
  If the current volume is the same as the previous one, this method does nothing.
  Available since API 4.5
  
  Parameters
  - Number volume - the current volume from 0.0 to 1.0.
- signal RatingSet(emitter, rating)
  
  Emitted when a rating is set.
  
  Note that rating has to be enabled first with a method MediaPlayer.setCanRate.
  Available since API 3.1
  
  Parameters
  - MediaPlayer emitter - object that emitted the signal
  - Number rating - Ratting from 0.0 to 1.0.
prototype Nuvola.MenuBar extends Object

Prototype object for Menubar management
- method setMenu(id, label, actions)
  
  Adds new menu to the menubar or replaces existing menu with the same id
  Parameters
  - String id - menu identifier
  - String label - label shown in user interface
  - Array of String actions - actions shown in the menu
prototype Nuvola.Notification extends Object

Desktop notification.
- method $init(name, resident, category)
  
  Creates new named notification.
  Parameters
  - String name - notification name (identifier)
  - Boolean resident - mark the notification as resident by default
  - optional String category - category of a notification
- method removeActions()
  
  Remove all actions available as buttons in notification.
- method setActions(actions)
  
  Set actions available as buttons in notification.
  Parameters
  - String[] actions - array of action names
- method show(force)
  
  Shows notification.
  Parameters
  - force ensure - notification is shown if true, otherwise show it when suitable
- method update(title, text, iconName, iconPath, resident)
  
  Update properties of a notification
  Parameters
  - String title - short title
  - String text - text of the notification
  - String? iconName - name of icon for notification
  - String? iconPath - path to an icon for notification
  - Boolean resident - mark the notification as resident, use null/undefined to reuse last value
prototype Nuvola.Notifications extends Object

Manages desktop notifications.
- method getNamedNotification(name, resident, category)
  
  Convenience method to creates new named notification.
  Parameters
  - String name - notification name (identifier)
  - Boolean resident - mark the notification as resident by default
  - optional String category - category of a notification
- method isPersistenceSupported()
  
  Check whether persistence is supported
  Deprecated since Nuvola 4.8: Use async variant instead.
  
  Returns
  - Boolean true if persistence is supported
- async method isPersistenceSupportedAsync()
  
  Check whether persistence is supported
  Asynchronous: This function returns a Promise object to resolve the value when it is ready. Read Using Promises to learn how to work with them.
  
  Available since Nuvola 4.8
  
  Returns
  - Boolean true if persistence is supported
- method showNotification(title, text, iconName, iconPath, force, category)
  
  Instantly show anonymous notification.
  Parameters
  - String title - short title
  - String text - text of the notification
  - String? iconName - name of icon for notification
  - String? iconPath - path to an icon for notification
  - Boolean force - ensure notification is shown if true, otherwise show it when suitable
  - optional String category - category of a notification
prototype Nuvola.SessionStorage extends KeyValueStorage

Prototype object of a key-value storage with a lifetime limited to the current session

Note: Use SessionStorage to store persistent data.
- method $init()
  
  Initializes new SessionStorage object.
prototype Nuvola.WebApp extends Object, contains Nuvola.SignalsMixin

Prototype object for web app integration.
- method $init()
  
  Initializes new web app object.
- method _onHomePageRequest(emitter, result)
  
  Signal handler for Core::HomePageRequest
- method _onInitAppRunner(emitter)
  
  Signal handler for Core::InitAppRunner
- method _onInitWebWorker(emitter)
  
  Signal handler for Core::InitWebWorker. Override this method to integrate the web page.
```
WebApp._onInitWebWorker = function (emitter) {
    Nuvola.WebApp._onInitWebWorker.call(this, emitter)

    var state = document.readyState
    if (state === 'interactive' || state === 'complete') {
      this._onPageReady()
    } else {
      document.addEventListener('DOMContentLoaded', this._onPageReady.bind(this))
    }
}

WebApp._onPageReady = function (event) {
  ...
}
```
- method _onInitWebWorkerHelper(emitter)
  
  Signal handler for Core::InitWebWorkerHelper. Override this method to connect to Core::ResourceRequest signal.
- method _onLastPageRequest(emitter, request)
  
  Signal handler for Core::LastPageRequest
- method _onNavigationRequest(object, request)
  
  Signal handler for Core::NavigationRequest
- method _onUriChanged(object, uri)
  
  Signal handler for Core::UriChanged
- method start()
  
  Convenience function to create new WebApp object linked to Nuvola API.
```
var WebApp = Nuvola.$WebApp()

...

WebApp.start()
```

Namespaces

namespace Nuvola.Translate
Translation functions.

These functions are only placeholders for now, but you can use them to mark translatable strings and then check whether they are properly recognized by a tool xgettext from the gettext package.

See also translations documentation.
- method gettext(text)
  
  Translate string.
  
  Placeholder: This function is only a placeholder for future functionality, but you can use it to mark translatable strings.
  
  Usage notes
  - It is usual to create alias var _ = Nuvola.Translate.gettext
  - You have to pass plain string literals, not expressions nor variables.
  Parameters
  - String text - text to translate
  Returns
  - String translated string
```
var _ = Nuvola.Translate.gettext
/// You can use tree slashes to add comment for translators.
/// It has to be on a line preceding the translated string though.
console.log(_('Hello world!')) // Right

var greeting = 'Hello world!'
console.log(_(greeting)) // Wrong!

var greeting = _('Hello world!') // Right
console.log(greeting)

var name = 'John'
console.log(_('Hello ' + name + '!')) // Wrong!
console.log(Nuvola.format(_('Hello {1}!'), name)) // Right
```
- method ngettext(text1, text2, n)
  
  Translate string with support of singluar and plural forms.
  
  Placeholder: This function is only a placeholder for future functionality, but you can use it to mark translatable strings.
  
  Usage notes
  - It is usual to create alias var ngettext = Nuvola.Translate.ngettext
  - You have to pass plain string literals, not expressions nor variables.
  Parameters
  - String text1 - singular form
  - String text2 - plural form
  - Number n - number of items
  Returns
  - String translated string
```
var ngettext = Nuvola.Translate.ngettext
var eggs = 5
var text = ngettext(
  'There is {1} egg in the fridge.',
  'There are {1} eggs in the fridge.',
  eggs)
console.log(Nuvola.format(text, eggs))

var text = ngettext(
  /// You can use tree slashes to add comment for translators.
  /// It has to be on a line preceding the singular string though.
  /// {1} will be replaced by number of eggs in both forms,
  /// but can be omitted as shown in singular form.
  'There is one egg in the fridge.',
  'There are {1} eggs in the fridge.',
  eggs)
```
- method pgettext(context, text)
  
  Translate string with support of a disambiguating message context.
  
  This is mainly useful for short strings which may need different translations, depending on the context in which they are used. e.g.: pgettext('Navigation', 'Back') vs pgettext('Body part', 'Back').
  
  Placeholder: This function is only a placeholder for future functionality, but you can use it to mark translatable strings.
  
  Usage notes
  - It is usual to create alias var C_ = Nuvola.Translate.pgettext
  - You have to pass plain string literals, not expressions nor variables.
  Parameters
  - String context - the message context
  - String text - text to translate
  Returns
  - String translated string
```
var C_ = Nuvola.Translate.pgettext
/// You can use tree slashes to add comment for translators.
/// It has to be on a line preceding the translated string though.
console.log(C_('Navigation', 'Back'))
console.log(C_('Body part', 'Back'))
```

Mixins

mixin Nuvola.SignalsMixin
Provides signaling functionality.
- method addSignal(name)
  
  Adds new signal listeners can connect to
  Parameters
  - String name - signal name, should be in CamelCase
```
BookStore.$init = function() {
  /**
   * Emitted when a book is added.
   *
   * @param Book book    book that has been added
   */
  this.addSignal('BookAdded')
}
```
- method connect(name, object, handlerName)
  
  Connect handler to a signal
  
  The first argument passed to the handler is the emitter object, i.e. object that has emitted the signal, other arguments should be specified at each signal's description.
  Parameters
  - String name - signal name
  - Object object - object that contains handler method
  - optional String handlerName - name of handler method of an object, default name is _onSignalName
  Throws
  - Error if signal doesn't exist
```
Logger._onBookAdded = function(emitter, book) {
  console.log('New book: ' + book.title + '.')
}

Logger.$init = function() {
  bookStore.connect('BookAdded', this)
  // equivalent: bookStore.connect('BookAdded', this, '_onBookAdded')
}
```
- method disconnect(name, object, handlerName)
  
  Disconnect handler from a signal
  Parameters
  - String name - signal name
  - Object object - object that contains handler method
  - optional String handlerName - name of handler method of an object, default name is _onSignalName
  Throws
  - Error if signal doesn't exist
- method emit(name, varArgsList)
  
  Emit a signal
  Parameters
  - String name - signal name
  - Variant varArgsList... - arguments to pass to signal handlers
  Throws
  - Error if signal doesn't exist
```
BookStore.addBook = function(book) {
  this.books.push(book)
  this.emit('book-added', book)
}
```

Enums

enumeration Nuvola.BrowserAction

Names on browser's actions
- GO_BACK - Go back to the previous page
- GO_FORWARD - Go forward
- GO_HOME - Go to the web app's home page.
- RELOAD - Reload page
enumeration Nuvola.MediaKey

Identifiers of media keys
- NEXT - Go to the next track key
- PAUSE - Pause key
- PLAY - Play key
- PREV - Go to the previous track key
- STOP - Stop key
enumeration Nuvola.PlaybackState

Media player playback states
- PAUSED - Playback is paused.
- PLAYING - Track is playing.
- UNKNOWN - Track is not playing nor paused.
enumeration Nuvola.PlayerAction

Base media player actions
Available since Nuvola 4.13: `REPEAT` and `SHUFFLE` actions were added.
- CHANGE_VOLUME - Change volume
- NEXT_SONG - Skip to previous track
- PAUSE - Pause playback
- PLAY - Start playback
- PLAYBACK_NOTIFICATION - Show playback notification
- PREV_SONG - Skip to next track
- REPEAT - Repeat status
- SEEK - Seek to a new position
- SHUFFLE - Shuffle status.
- STOP - Stop playback
- TOGGLE_PLAY - Toggle playback (play/pause)
enumeration Nuvola.PlayerRepeat

Media player repeat status
Available since Nuvola 4.13
- NONE - The playback will stop when there are no more tracks to play.
- PLAYLIST - The playback loops through a list of tracks.
- TRACK - The current track will start again from the beginning once it has finished playing.

Changelog

Since 4.12

Nuvola.Core::NavigationRequest (new): You can overwrite `request.url` field to force redirect.
Nuvola.queryAttribute (new): You can specify a parent element and a relative selector as an array of [parent element, selector].
Nuvola.queryText (new): You can specify a parent element and a relative selector as an array of [parent element, selector].
Nuvola.setInputValueWithEvent (new): The change event is emitted as well.

Since 4.13

Nuvola.MediaPlayer.setCanRepeat (new)
Nuvola.MediaPlayer.setCanShuffle (new)
Nuvola.MediaPlayer.setShuffleState (new)
PlayerAction (new): `REPEAT` and `SHUFFLE` actions were added.
PlayerRepeat (new)

Questions? Feedback?

Having trouble? We'd like to help!

Search for information in the archives of the nuvola-player-devel mailing list, or post a question.
If you notice errors with this documentation, please open a ticket and let us know! Please only use the ticket tracker for criticisms and improvements on the docs.

Generated by Pelican. Get source code. Uses Bootstrap theme United.

NuvolaKit 4 JavaScript API Reference

NuvolaKit 4

Namespace Nuvola

Fields

Functions

Prototypes

Namespaces

Mixins

Enums

Changelog

Miscellaneous

Introduction

Prototypal inheritance

Base API

Advanced API

Low-level API

Namespace Nuvola

Fields

Functions

Prototypes

Namespaces

Mixins

Enums

Changelog

Since 3.1

Since 4.5

Since 4.8

Since 4.10

Since 4.11

Since 4.12

Since 4.13