What’s new

Table of Contents

New functions takeScreenshot and addPageToPDF

Two new functions allow you to save current Screen Data as an Image or PDF. See the chapter Saving Screen State for details.

Global notifications

You can now display a notification dizmo along the right edge of dizmoViewer to display global alerts and notifications. See the chapter Notifications for details.

Geolocation support

There are new attributes to query the geolocation of the computer on which dizmoViewer is installed on.

viewer.getAttribute("system/closestCity");
viewer.getAttribute("system/geoLocation/Latitude");
viewer.getAttribute("system/geoLocation/Longitude");

With this, your dizmo can already preconfigure itself to the nearest location (e.g Map, Clock or Weather)

RGBA Color Model

With version 1.3 of the dizmoJS API, we’ve switched from using ARGB colors to RGBA colors, to be more aligned to what a developer knows and uses on the web.

Example:

dizmo.setAttribute("settings/framecolor","A0A0A0FF");

A0A0A0 is the RGB color, and FF is the transparency value.

Attributes that accept colors:

viewer.setAttribute("settings/backgroundColor",colorString);
dizmo.setAttribute("settings/frameColor",colorString);
dizmo.setAttribute("settings/titleColor",colorString);

Hint: When working with HSV and Hex Colors and need to convert, use the Color.js Library

Colors.js can do the following:

  • Change RGB to a Hexadecimal color
  • Change Hexadecimal to an RGB color
  • Change Hexadecimal to an HSV color
  • Get the complementary value of a Hexadecimal color
  • Get the complementary value of an RGB color
  • Named color to an RGB object, HSV object or Hexadecimal string

New dizmo.clone() function

With the new dizmo.clone() function, you can create a clone of any existing dizmo. You can overwrite attributes of the cloned dizmo like so:

dizmo.clone({"settings/title":"foobar"},function(dizmoInstance,error){console.log(dizmoInstance.getAttribute("settings/title"));}); 

Note: dizmo.clone() is processed asynchronous, use a callback to access any property of the cloned dizmo.

New dizmo attribute state/frozen

dizmoViewer automatically saves a screenshot of each dizmo state when dizmoViewer is closed or a setup is saved. When starting dizmoViewer or loading a setup, said screenshot is displayed first and then replaced with the live content of the dizmo for a better user experience. The dizmoElements library takes care of freezing and unfreezing a dizmo to enable that functionality. If your dizmo is not using dizmoElements, you’ll need to update the following attribute to true as part of the initialization:

dizmo.setAttribute("state/frozen",false);

Otherwise, your dizmo will appear non-functional, as it just displays the last saved screenshot and is not reacting to any events like touches or clicks.

New viewer attribute system/online

For dizmos that need to check if they have internet connectivity, there is a new attribute called system/online.

online: Indicates if dizmoViewer and the dizmos have access to the internet write: false type: Boolean

However, as this flag is updated whenever the call is made to read it, it is not subscribable. After you queried the attribute, you will have to wait 3 minutes before you can query it again. During that time, the last status is returned.

Example:

viewer.getAttribute("system/online");

New viewer attributes settings/uiScaling and system/logicalDpi

In order to cope with devices that have a logical resolution of anything else than 96 dpi, dizmoViewer reads the pixels per inch from the OS and adjusts the size of UI elements according to these values. This fixes a problem we had on Surface 3 devices where dizmoViewer UI elements became too small to work.

In addition we have introduced a new parameter that allows you to further scale dizmoViewer UI elements by a factor of between 0.5 to 2 to cope with special circumstances.

Adujst the value in GlobalSettings.xml, within a range from 0.5 to 2

 <UserInterface_UserDefinedScale>1<!---->
 </UserInterface_UserDefinedScale>

 New LoadMainPageWithScheme option in package.json

We have introduced the dizmo:// scheme to be used when loading local content like the index.html page of a dizmo. The dizmo:// scheme has been marked as local which allows AJAX access to other sites for dizmos (cross site scripting).

A dizmo can choose the scheme to be used when loading its index.html page (dizmo or https), the default is dizmo.

Any path to a local file returned by dizmoViewer will be supplied with the same scheme as the dizmo, with the exception of storage files, which will always be served / made available through http

If you want to specify https as the scheme, add the the LoadMainPageWithScheme key to the settings in package.json:

    "settings": {
      "LoadMainPageWithScheme": "https" }

New URLs to access storage and bundle files

When reading from the data tree, instead of stpt:// we now use an internal webserver to serve files via http://localhost:42612/storage/… or https://localhost:42613/storage/…

Also, to access files stored in the dizmo bundle, you use the internal webserver as well.

Example:

    https://localhost:42613/bundles/com.dizmo.example/style/images/language.svg
    http://localhost:42612/bundles/com.dizmo.example/style/images/language.svg

New API call to get the absolute geometry of a dizmo

In order to provide absolute geometry in the most efficient way possible we have added the absoluteGeometry subtree that now provides this information.

dizmo.getAttribute("absoluteGeometry/zoom");
dizmo.getAttribute("absoluteGeometry/x");
dizmo.getAttribute("absoluteGeometry/y");
dizmo.getAttribute("absoluteGeometry/angle");
dizmo.getAttribute("absoluteGeometry/width");
dizmo.getAttribute("absoluteGeometry/height");

A more detailed description of absolute and relative geometry can be found in the Chapter Dizmo Attributes.

Asynchronous subscriptions

All subscriptions are now asynchronous. This means that when a subscription is called and immediately after the value is changed, it will not trigger the subscription. An additional (optional) callback was added to bridge that gap. It is called the moment the subscription is registered and ready to be fired. Place your code to change the value inside this callback to ensure that the subscription is triggered.

dizmo.subscribeToAttribute('foo', function (p, v, of) { ... }, function () { // it is assured that the subscription is triggered
dizmo.setAttribute('foo','bar'); 
});

Here is a full list of all the functions where you can specify a subscribedCallback:

dizmo functions

  • subscribeToProperty (publicStorage and privateStorage)
  • subscribeToAttribute
  • subscribeToAttributeConditional

  • onShow
  • onHide
  • onMaximized
  • onIconized
  • onClosing
  • onCancelClosing
  • onDragEnd
  • onResizeStart
  • onResizeEnd
  • onShowFront
  • onShowBack
  • onRemoteHostConnected
  • onRemoteHostDisconnected
  • onParentChanged
  • onChildrenAdded
  • onChildrenRemoved

viewer functions

  • onRemoteHostAdded
  • onRemoteHostRemoved
  • onDizmoAdded
  • onDizmoRemoved
  • onBundleAdded
  • onBundleRemoved

New viewer.loadMediaInfo function

In order to handle media data (e.g video, audio, images) properly we have added a function to get information about media files independent of HTML5, which seems not to work properly all the time on all platforms. It returns the following information items based on an URI passed to the call:

  • width
  • height
  • videocodec
  • audiocodec
  • mimetype
  • datasize
viewer.loadMediaInfo("<uri>", callback(info));

New CookieJarToUse option in package.json

The new CookieJarToUse option allows you to specify if and where to store Cookies (per dizmo, per bundle or global in the viewer). Per dizmo Cookie Jar is recommended for sensitive or private Cookies, that should only be visible to the own dizmo instance, per bundle Cookie Jar for Cookies that need to be shared among all dizmo instances of the same bundle and viewer global Cookie Jar for all others. If your dizmo only processes Cookies but does not store them, you don’t need a Cookie Jar.

Set to none by default, can be set to viewer, bundle or dizmo. Add the CookieJarToUse key to the settings in package.json:

    "settings": {
            "CookieJarToUse": "dizmo"
        },

Audio capturing

dizmoViewer now supports audio capturing, this is done on the global level. If any dizmo has started the audio recording, it runs for any dizmo subscribed on the audio tree. If the last dizmo (which started the recording) stops the recording it is stopped for every dizmo. So each dizmo should start the recording, even when its already running to make sure it stays running.

The default samplerate is 8000, default sample size is 16 and the default codec is "audio/pcm".

This values have to be set before the audiorecording is started.

settings.sampleSize=16;
settings.sampleRate=8000;
settings.codec="audio/pcm";

Apply the new audio settings (this will only work if the viewer is currently not recording)

viewer.setAudioSettings(settings);

If the audio recording has already started, the settings can’t be changed, but read. These settings can change with the start of the recording if the audio device doesn’t support the selected settings.

You can retrieve the current settings via

viewer.getAudioSettings();

Return if the audio recording is running or not

viewer.recordingIsRunning();

Stop the audio recording (for this dizmo) and remove subscription calls

viewer.stopAudioRecording();

Start the audio recording (if not already started) and subscribe to the data

viewer.startAudioRecording(callback);

The callback will receive the audio data, which is base64 encoded.