dizmojs.Viewer

Viewer

Provides convenience methods to manage properties of dizmoViewer.

Each dizmo is provided with an instance of this class in the global
variable viewer.

new dizmojs.Viewer()

dizmojs.Viewer Class

Methods

openURL()

Open an URL in the TinyBrowser dizmo
Throws:
If the provided URL is not a string
Type

NotAStringError

openPDF(path) → {String}

Open a pdf file or create a new one at the given path.
Parameters:
Name Type Description
path

String

Path to the PDF file
Returns:
Id to use in addPageToPDF and closePDF calls
Type

String

addPageToPDF(id, options)

Save the current view to the PDF file as a new page
Parameters:
Name Type Argument Description
id

String

The id of the PDF file
options

Object

<optional>

An optional object containing parmeters for the view
{
x: {Number} The x coordinate corresponding to the center of the pdf image,
y: {Number} The y coordinate corresponding to the center of the pdf image,
height: {Number} The height of the image to be captured,
width: {Number} The width of the image to be captured,
zoom: {Number} The zoom of the image to be captured,
angle: {Number} The angle of the viewer for the image to be captured
}

closePDF(id)

Close the PDF file opened by openPDF
Parameters:
Name Type Description
id

String

The id of the PDF file

loadMediaInfo(url, callback)

Retrieve media info for a given URL. The info is provided in a callback. Possible
values are: width, height, videocodec, audiocodec, mimetype, datasize. If a value
is not defined for the given URL it will be undefined. Details
Parameters:
Name Type Description
url

String

An URL to retrieve media info from
callback

dizmojs.Viewer~mediaInfoCallback

The callback to call when the information has been loaded

getAttribute(attributeName) → {String|Number|Boolean|Array}

Get value of an attribute of the viewer (attribute name is case INsensitive!). One can also get the parent attribute: For example dizmo.getAttribute(‘geometry’); will return an object with all the values under geometry. This is recursive, so ALL children on ALL levels below the parent will be retrieved.
Parameters:
Name Type Description
attributeName

String

name of the attribute of the viewer. For a list, refer to the data tree.
To Do:
  • Do not document the attributes here! Instead, provide a link to a proper documentation of the whole tree!
Throws:
  • If the provided attribute name is not a string
    Type

    NotAStringError

  • If the provided attribute does not exist
    Type

    AttributeDoesNotExistError

Returns:
value of the Attribute of the viewer
Type

String
|

Number
|

Boolean
|

Array

setAttribute(attributeName, value)

set value of an attribute of the viewer (attribute names are case INsensitive)
Parameters:
Name Type Description
attributeName

String

name of the attribute of the viewer. For a full list, see the data tree.
value

Number
|

String
|

Boolean

value to be set to the attribute
Throws:
  • If the provided attribute name is not a string
    If the attribute requests the value to be a string, but it isn’t
    Type

    NotAStringError

  • If the attribute requests the value to be a number, but it isn’t
    Type

    NotANumberError

  • If the attribute requests the value to be a boolean, but it isn’t
    Type

    NotABooleanError

  • If the provided attribute does not exist
    Type

    AttributeDoesNotExistError

  • If the attribute is not writable
    Type

    AttributeNotWritableError

  • If the attribute is out of the given range
    Type

    OutOfRangeError

  • If the given value is not accepted
    Type

    NotAcceptedValueError

subscribeToAttribute(attributeName, callback, subscribedCallback) → {String}

Subscribe a callback to changes on the given attribute. If subscribing on a parent node, the changes that are made to any sub nodes will be listened to. This is as subscribing to a recursive node on the private/public store.
Parameters:
Name Type Argument Description
attributeName

String

The attribute on which to listen for changes. For a list, refer to the data-tree.
callback

function

The function to call once changes have occurred
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Throws:
  • If the provided attribute is not a string
    Type

    NotAStringError

  • If the attribute does not exist
    Type

    AttributeDoesNotExistError

  • If the callback is not a function
    Type

    NotAFunctionError

Returns:
The subscription id
Type

String

subscribeToAttributeConditional(attributeName, condition, callback, subscribedCallback) → {String}

Subscribe to an attribute and only call the given callback when the attribute is equal to the given condition
Parameters:
Name Type Argument Description
attributeName

String

The name of the attribute. For a list, refer to the data-tree.
condition

String
|

Boolean
|

Number

The value the attribute has to be equal to
callback

function

The function to call once the attribute is equal to the condition
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Throws:
  • If the provided attribute name is not a string
    Type

    NotAStringError

  • If the attribute does not exist
    Type

    AttributeDoesNotExistError

  • If the callback is not a function
    Type

    NotAFunctionError

Returns:
The subscription id
Type

String

unsubscribeAttribute(subscriptionId)

Unsubscribe from the given attribute change
Parameters:
Name Type Description
subscriptionId

String

The subscription id returned from a subscribeToAttribute call
Throws:
If the given subscription id is not a string
Type

NotAStringError

setPosition(x, y)

Set the position of the viewer
Parameters:
Name Type Description
x

Number

The x coordinates the viewer should be moved to
y

Number

The y coordinates the viewer should be moved to
Throws:
  • If the provided value for x or y is not a number
    Type

    NotANumberError

  • If the provided value for x is smaller than -3000 or bigger than 3000
    If the provided value for y is smaller than -3000 or bigger than 3000
    Type

    OutOfRangeError

getPosition() → {Object}

Returns:
The position of the viewer as an object
Type

Object

getLanguage() → {String}

Get the language the viewer is set to
Returns:
The language code (ex.: de, en)
Type

String

activateLicense(The, The) → {Boolean}

Activate the license specified by name and key. Returns true or false depending if the
license could have been activated or not.
Parameters:
Name Type Description
The

String

username for the new license
The

String

new license key to set
Returns:
True if the new license was activated, false if not
Type

Boolean

onRemoteHostAdded(callback, subscribedCallback) → {String}

Register a function which is being called whenever a new remote host is connected.
Parameters:
Name Type Argument Description
callback

function

The function to call. Gets a remote host object as parameter
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id.
Type

String

onRemoteHostRemoved(callback, subscribedCallback) → {String}

Register a function to be called when an existing remote host has been closed
Parameters:
Name Type Argument Description
callback

function

The function to call. Gets a the host name (of the closed connection) as parameter
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id
Type

String

unsubscribeRemoteHost(subscriptionId)

Unsubscribe from an existing open live connection subscription.
Parameters:
Name Type Description
subscriptionId

String

The subscription id retrieved from the register functions

takeScreenshot(options, The)

Retrieve a screenshot from the viewer and provide the image data in a callback.

The function can be called with several configurations.

With An Object
viewer.takeScreenshot({
geometry: {
x: x coordinate of the center of the screenshot,
y: y coordinate of the center of the screenshot,
height: height of the rectangle to be provided as a bitmap,
width: width of the rectangle to be provided as a bitmap,
zoom: the viewer zoom level to be used when capturing the rectangle to be provided as a bitmap,
angle: the viewer rotation to be used when capturing the rectangle to be provided as a bitmap,
}
bitmap: {
height: the height of the bitmap that is produced from the screenshot,
width: the width of the bitmap that is produced from the screenshot
}
},function(image){
// do something with the image
});
some of the values can be omitted. For example the whole geometry section can be omitted, in which
case the default values will be used. Same goes for the bitmap section, in which case the default values
(the width and height set in geometry) will be used as well.

With A Function
viewer.takeScreenshot(function(image) {
// do something with the image
});

Full Parameters
The function can be called with all parameters present.
viewer.takeScreenshot({
// options parameters
}, function(image) {
// do something with the image
});

Parameters:
Name Type Description
options

Object
|

function

Various configuration options. See description.
The

function

callback function to be called when a screenshot has been taken
Throws:
  • If a parameter is missing or incorrect
    Type

    MissingConfigParameter

  • If a parameter is not a number but supposed to be
    Type

    NotANumberError

  • If a parameter is out of the allowed range
    Type

    OutOfRangeError

transitionTo(x, y, zoom, angle)

Moves the viewer to a certain position, angle and zoom level at the same time in a smooth animation
Parameters:
Name Type Description
x

Number

The x coordinates the viewer should be moved to
y

Number

The y coordinates the viewer should be moved to
zoom

Number

The zoom level the viewer should have after the transition is finished
angle

Number

The angle the viewer should be set to after the transition is finished
Throws:
  • If any of the provided parameters is not a number
    Type

    NotANumberError

  • If the any of the given parameter is out of range
    Type

    OutOfRangeError

focusOnDizmo(identifier, zoom)

Focus the viewer on a dizmo identified by its id
Parameters:
Name Type Argument Description
identifier

String

The identifier of a dizmo
zoom

Number

<optional>

A zoom value between 0.1 and 10
Throws:
  • If the zoom is not between 0.1 and 10
    Type

    OutOfRangeError

  • If the zoom is not a number or undefined
    Type

    NotANumberError

  • If the provided identifier is not a string
    Type

    NotAStringError

  • If the dizmo with the given identifier is not instantiated
    Type

    DizmoNotInstantiatedError

getChildDizmos() → {Array}

Get all the root dizmos of the viewer.
Returns:
An array of dizmo instances
Type

Array

getDizmos() → {Array}

Get a list of all currently instantiated dizmos
Returns:
An array of dizmojs.Dizmo instances
Type

Array

getDizmoById(id) → {dizmojs.Dizmo}

Get an instantiated dizmo by its identifier.
Parameters:
Name Type Description
id

String

The identifier of the dizmo instance
Throws:
If the provided identifier does not match an instanciated dizmo
Type

DizmoNotExistsError

Returns:
The dizmo instance of the provided identifier
Type

dizmojs.Dizmo

getBundles() → {Array}

Get all the installed bundles
Returns:
An array of installed bundle instances
Type

Array

getBundleById(id) → {dizmojs.Bundle}

Get an installed bundle by its id. You can also provide a dizmo identifier and the corresponding
bundle will be returned.
Parameters:
Name Type Description
id

String

The bundle identifier or dizmo identifier.
Throws:
If the provided bundle identifier (or dizmo identifier) does not correspond to an installed bundle
Type

BundleNotExistsError

Returns:
The bundle instance of the provided identifier
Type

dizmojs.Bundle

updatePeerList()

Update peer list with a call

getRemoteHosts() → {Array}

Retrieve a list of all connected remote hosts
Returns:
An array of remote host instances
Type

Array

getRemoteHostById(id) → {dizmojs.RemoteHost}

Retrieve a single remote host specified by its id
Parameters:
Name Type Description
id

String

The id of the remote host to retrieve
Returns:
A single remote host instance
Type

dizmojs.RemoteHost

getRemoteHostByIp(ipaddress) → {dizmojs.RemoteHost}

Get the remote host by an ip address
Parameters:
Name Type Description
ipaddress

String

The ip address of the remote host (ipv4 or ipv6)
Throws:
  • If the provided ip address is not a string
    Type

    NotAStringError

  • If the provided ip address is not in the correct format
    Type

    InvalidIPAddressError

  • If the remote host with the provided ip address does not exist
    Type

    RemoteHostNotExistsError

Returns:
A remote host instance of the remote host corresponding to the ip address provided
Type

dizmojs.RemoteHost

addRemoteHost(remoteHostId, callback)

Add a new remote host connection (it will always start as closed)
Parameters:
Name Type Description
remoteHostId

String

The remote host id of the new remote host
callback

dizmojs.Viewer~addRemoteHostCallback

A callback to call when a remote host was successfully added
Throws:
  • If the provided remoteHostId is not a string
    Type

    NotAStringError

  • If the provided ipv4 or ipv6 address is not correctly formatted
    Type

    InvalidIPAddressError

  • If the provided callback is not a function or undefined.
    Type

    NotAFunctionError

startAudioRecording(callback)

Start the audio recording (has no effect if it is already running) Details
Parameters:
Name Type Description
callback

function

Subscription callback for received stream

stopAudioRecording()

Stop the audio recording Details

getAudioSettings() → {Object}

Retrieve the audio settings
Returns:
An object containing sampleRate, sampleSize and codec of the audio stream
Type

Object

setAudioSettings(settings)

Set audio settings. This only works when the recording is not currently running.
These values might change when starting the recording based on the device the audio
is catured with.
Parameters:
Name Type Description
settings

Object

{
sampleSize: {Number} the sample size
sampleRate: {Number} the sample rate
codec: {Number} codec to capture with
}
Throws:
  • If the provided settings object is not an object
    Type

    NotAnObjectError

  • If the provided sample rate is not a number
    If the provided sample size is not a number
    Type

    NotANumberError

  • If the provided codec is not a string
    Type

    NotAStringError

recordingIsRunning() → {Boolean}

Returns:
When the recording is running
Type

Boolean

clearSetup()

Clears the current dizmoViewer setup

saveSetup(name, id, password, callback, padId)

Save the current setup to the synchronization server with the given name, id and password.
Parameters:
Name Type Argument Description
name

String

The name of the setup
id

String

A unique if for the setup
password

String

The password this setup has
callback

dizmojs.Viewer~setupSaveLoadCallback

<optional>

The function to call when the setup was saved
padId

String

<optional>

The id of a pad to save as a setup
Throws:
  • If the provided name is not a string.
    If the provided ID is not a string.
    If the provided password is not a string.
    If the provided padId is defined but not a string.
    Type

    NotAStringError

  • If the provided callback is defined but not a function.
    Type

    NotAFunctionError

  • If the provided padId can not be matched to an instantiated pad.
    Type

    DizmoNotInstantiatedError

loadSetup(id, password, callback, options)

Load the setup identified by its id.
Parameters:
Name Type Argument Description
id

String

The identifier of the setup.
password

String

The password for the setup to load.
callback

dizmojs.Viewer~setupSaveLoadCallback

<optional>

A function to call when the setup was loaded.
options

Object

<optional>

Options (clearSpace defaults to true and loadAsPad default to false)
{
clearSpace: {Boolean} Clear the viewer before loading the setup
loadAsPad: {Boolean} Load the setup inside a pad
targetPad: {String} The target pad in which the setup should be loaded
}
Throws:
  • If the provided id is not a string.
    If the provided password is not a string.
    Type

    NotAStringError

  • If the provided callback is defined but not a function.
    Type

    NotAFunctionError

  • If the provided options is defined but not an object.
    Type

    NotAnObjectError

  • If the options.clearSpace parameter is defined but not a boolean.
    If the options.loadAsPad parameter is defined but not a boolean.
    Type

    NotABooleanError

  • If the provided target pad does not exists.
    Type

    DizmoNotExistsError

  • If the provided target dizmo is not a pad.
    Type

    NotAPadDizmoError

changeSetupSecret(id, oldPassword, newPassword, callback)

Change the secret of a setup identified by its id. Requires the current password.
Parameters:
Name Type Argument Description
id

String

The id of the setup.
oldPassword

String

The current password of the setup.
newPassword

String

The new password for the setup.
callback

dizmojs.Viewer~setupChangeSecretCallback

<optional>

A function to call when the secret has been changed.
Throws:
  • If the provided id is not a string.
    If the provided oldPassword is not a string.
    If the provided newPassword is not a string.
    Type

    NotAStringError

  • If the callback is defined but not a function.
    Type

    NotAFunctionError

onDizmoAdded(callback, subscribedCallback) → {String}

Register to the new dizmos event. The provided callback is called whenever a new dizmo has been instantiated.
Parameters:
Name Type Argument Description
callback

function

The function to call
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id
Type

String

onDizmoRemoved(callback, subscribedCallback) → {String}

Register a callback on the remove dizmo event. The provided function is called as soon as a dizmo has been removed from the viewer.
Parameters:
Name Type Argument Description
callback

function

The function to call
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id
Type

String

unsubscribeDizmoChanges(subscriptionId)

Unsubscribe from any dizmo calls
Parameters:
Name Type Description
subscriptionId

String

The subscription id returned by the onDizmosRemoved and onNewDizmos functions

installBundle(bundleURI, callback)

Install bundle(s) specified by the given path. The path can be either a web url pointing to a dizmo or a relative path inside the current dizmos directory:
bundle://dizmos/somedizmo.dzm (which will resolve to the full path where your current dizmos files are)
https://www.dizmo.com/myowndizmo.dzm
Parameters:
Name Type Description
bundleURI

String

The location of the bundle to install
callback

function

The callback to call when a bundle is installed.
viewer.installBundle(‘com.dizmo.example’, function(bundleid, error) {});
Throws:
  • If the provided bundle uri is not a string
    Type

    NotAStringError

  • If the provided callback is not a function (or undefined).
    Type

    NotAFunctionError

installStoreBundle(bundleId, version, callback)

Install a bundle from the store with a given bundle id and version.
Parameters:
Name Type Description
bundleId

String

The bundle id of the bundle to install
version

String

The version of the bundle to install
callback

dizmojs.Dizmo~storeBundleInstalledCallback

A function that is called after the bundle has been installed

onBundleAdded(callback, subscribedCallback) → {String}

Register to the new bundle event. The provided callback is called whenever a new bundle has been added.
Parameters:
Name Type Argument Description
callback

function

The function to call
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id
Type

String

onBundleRemoved(callback, subscribedCallback) → {String}

Register a callback on the remove bundle event. The provided function is called as soon as a bundle has been uninstalled.
Parameters:
Name Type Argument Description
callback

function

The function to call
subscribedCallback

dizmojs.Viewer~onSubscriptionRegisteredCallback

<optional>

The function called once the subscription is registered
Returns:
The subscription id
Type

String

unsubscribeBundleChanges(subscriptionId)

Unsubscribe from any bundle calls
Parameters:
Name Type Description
subscriptionId

String

The subscription id returned by the onBundleRemoved and onBundleAdded functions

storeWorkspace()

Store the workspace locally. The stored workspace can be retrieved with viewer.loadWorkspace()

loadWorkspace()

Load a previously stored workspace. Workspaces can be stored with viewer.storeWorkspace()

notify(opts)

Shows a notification dizmo along the right edge starting from the top.
Parameters:
Name Type Description
opts

object

Options the dizmo will be instantiated with:

title – {String} Required first line of notification.
button_1 – {String} Right hand side upper button name.
button_2 – {String} Right hand side lower button name.
callback – {Function} Callback to be invoked with a message string
parameter indicating either `click`, `timeout`, `ignore` or one of the
button identifiers (and names); the second parameter is a custom defined
`data` object; further, the `this` scope of the function is the
notification dizmo invoking the callback.
closable – {Boolean} Flag to enable auto-close when upper button
is clicked; default is `undefined`. If set and button_1 is not
set, then the latter is set to `Close`.
color - {String} Hex code to color the frame of dizmo.
data - {Object} An object with custom data.
icon - {String} URL or relative path to an icon; by default the
`assets/Icon.svg` image of the notifying dizmo is chosen.
notification_id - {String} ID of an existing notification dizmo
to refresh.
opacity - {Number} A number between 0.0 and 1.0 to set opacity.
sub_title - {String} Second line of notification.
text - {String} Third line of notification.
timeout - {Number} Timeout in milli-seconds to auto-close dizmo; if
it is set to `null` then the timeout is disabled.
path - {String} An internal path to be used to communicate between
the notifying and notification dizmos; default is `notification`.
important - {Boolean} Displays the notification using a predefined
`red` color.

Type Definitions

setupSaveLoadCallback(id, error)

A callback invoked when a setup has been loaded or saved.
Parameters:
Name Type Description
id

String

The id of the saved/loaded setup
error

number

An error number

setupChangeSecretCallback(id, error)

A callback invoked when a secret for a callback has changed.
Parameters:
Name Type Description
id

String

The id of the setup the password was changed
error

Number

An error number

addRemoteHostCallback(remoteHost, error)

A callback invoked when a remote host has been added after the user calls addRemoteHost
Parameters:
Name Type Description
remoteHost

Object

The remote host instance if the call was successful (otherwise null)
error

Object

The error object if the call failed.
{
name: {String} The name of the error
message: {String} A message accompanying the error
}

remoteRemoteHostCallback()

A callback invoked when a manually added remote host has been removed

activateLicenseCallback(success)

A callback invoked when a new activation has been activated or failed to activate
Parameters:
Name Type Description
success

Boolean

True if the activation was successful, otherwise false

mediaInfoCallback(info, error)

A callback to retrieve media information for a given URL.
Parameters:
Name Type Description
info

Object

The information retrieved. Values that do not apply to the media type are undefined
{
width: {Number} The width of the media
height: {Number} The height of the media
videocodec: {String} The video codec used
audiocodec: {String} The audio codec used
mimeytpe: {String} The mimetype
datasize: {Number} The size of the media
}
error

Object

If an error has occured the following field will contain the error number and the message
{
errornumber: {Number} The number of the error
errormessage: {String} A short explanation
}

onSubscriptionRegisteredCallback()

A callback that is called as soon as the subscription has been registered in the dizmoViewer.