dizmojs.Viewer

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.