Introduction

This is a reference of public JavaScript API of NuvolaKit, the core part of Nuvola Player 3. 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:

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, init_args)

    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 init_args... - 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.clickOnElement(elm)

    Simulates click on element

    Parameters

    • HTMLElement elm - Element object
  • 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.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.triggerMouseEvent(elm, name)

    Triggers mouse event on element

    Parameters

    • HTMLElement elm - Element object
    • String name - Event name
  • 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 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, mnemo_label, 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.

      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);
      
    • method isEnabled(name)

      Checks whether action is enabled

      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)

      Emitted when an action is activated.

      Parameters

      • Actions emitter - object that emitted the signal
      • String name - action name
      MyObject.$init = function()
      {
          Nuvola.actions.connect("ActionActivated", this);
      }
      
      MyObject._onActionActivated = function(emitter, name)
      {
          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 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 SignalsMixin

    Prototype object to manage Nuvola Player Core

    • method $init()

      Initializes new Core instance object

    • method getComponentInfo(id)

      Returns information about a component

      Parameters

      • id ide - of the component

      Returns

      • Object component info

    • method isComponentLoaded(id)

      Returns whether a component is loaded

      Parameters

      • id id - of the component

      Returns

      • Boolean true if the component is loaded

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

      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.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(object, request)
      {
          request.approved = isAddressAllowed(request.url);
      }
      
    • 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.)

      Parameters

      • String key - key name

      Returns

    • method hasKey(key)

      Check whether the storage has given key

      Parameters

      • String key - storage key name

      Returns

    • method set(key, value)

      Set value for given key

      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.

      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");
      }
      
  • 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 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

  • prototype Nuvola.MediaPlayer extends Object, contains 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 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.

      @since API 3.1

      Parameters

      • Boolean canRate - true if remote rating 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

    • 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.
    • signal RatingSet(emitter, rating)

      Emitted when a rating is set.

      Note that rating has to be enabled first with a method MediaPlayer.setCanRate.

      @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

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

    • NEXT_SONG - Skip to previous track
    • PAUSE - Pause playback
    • PLAY - Start playback
    • PLAYBACK_NOTIFICATION - Show playback notification
    • PREV_SONG - Skip to next track
    • STOP - Stop playback
    • TOGGLE_PLAY - Toggle playback (play/pause)