Contact - Documentation

The Contact control interface can be used to control the state of the output contacts (VP330 / EVP380) and to retrieve the state of the input contacts.

The following API is asynchronous and using Promise.
To use this API, you first need to get the contact control interface thanks to IDAL.getControlInterfaces().

Methods

getInputByName(name) → {Promise.<Contact~InputContactInfo>|Promise.<ErrorStatus>}

Get the current state of the input contacts.

Input contacts are identified by a name:

"standalone" for the single contact available on all players.
"combined" for the 8 input contacts available on VP330 and EVP380.

You can also retrieve the contact states in real time thanks to the InputContactEvent event.

Parameters:

Name	Type	Description
`name`	string	Input contact name ("standalone" or "combined").

Returns:

A promise resolved with an InputContactInfo.

Type

Promise.<Contact~InputContactInfo>
A promise rejected with an ErrorStatus.

Type

Promise.<ErrorStatus>

setInputConfiguration(config) → {Promise.<boolean>|Promise.<ErrorStatus>}

Set the input contacts configuration (control mode).

Input contact combinations are binded to actions ("play folder" by default) which are automatically managed by the video playback engine.
If you need to override this behavior and control the input contacts from the HTML/JavaScript layer, you have to call this method with config.controller set to 'browser'.

The configuration can be automatically reverted to the default depending on the value of config.lifetime.

This method can also be used to map input contact events to regular keyboard events. It makes it possible to use input contacts as a keyboard and use generic key event handlers such as keyup and keydown.

Example

Usage of input contacts to keyboard events mapping.

// In this example, 'contact' is the variable referencing the contact control interface..
// Configuring input contacts to act as arrows, enter and escape keys...
// The configuration will be reverted when a new page is loaded.
var config = {
    controller: "browser",
    lifetime: "url",
    keymaps: {
        combined: [
            "ArrowLeft",
            "ArrowRight",
            "ArrowUp",
            "ArrowDown",
            "Enter",
            "Escape"
        ]
    }
};
contact.setInputConfiguration(config)
    .then(function(e) {
         // Do what you need here
     })
    .catch(function(e) {
         // Handle error here
    });

// Install keyboard event handler
window.addEventListener("keydown", function(e) {
    console.log("Key down: key=" + e.key + ", code=" + e.code + ", keyCode=" + e.keyCode);
});

Parameters:

Name	Type	Description
`config`	Contact~InputContactConfig	The configuration to apply to input contacts.

Returns:

A promise resolved with a boolean value.

Type

Promise.<boolean>
A promise rejected with an ErrorStatus.

Type

Promise.<ErrorStatus>

setOutputById(id, value) → {Promise.<boolean>|Promise.<ErrorStatus>}

Set a single output contact state using its identifier.

Parameters:

Name Type Description

Name	Type	Description
`id`	number	The contact identifier is a value between 0 and 7.
`value`	number \| boolean	The new contact state: 0 or false to open the contact. non zero or true to close the contact.

id

number

The contact identifier is a value between 0 and 7.

value

number | boolean

The new contact state:

0 or false to open the contact.
non zero or true to close the contact.

Returns:

A promise resolved with a boolean value.

Type

Promise.<boolean>
A promise rejected with an ErrorStatus.

Type

Promise.<ErrorStatus>

setOutputByMask(value, mask) → {Promise.<boolean>|Promise.<ErrorStatus>}

Set many output contacts at once.

Parameters:

Name	Type	Description
`value`	number	The bitmask of all the output contact values. One bit per contact. The least significant bit is the contact number 0.
`mask`	number	The bitmask of the contacts to actually set. One bit per contact. The least significant bit is the contact number 0. Only the contacts having their bit set to 1 are modified.

Returns:

A promise resolved with a boolean value.

Type

Promise.<boolean>
A promise rejected with an ErrorStatus.

Type

Promise.<ErrorStatus>

Type Definitions

InputContactConfig

Configuration to set on input contacts.
It defines the entity responsible for managing the input contacts: the browser or the video player.
It is also possible to configure the input contact keyboard mapping.

Properties:

Name Type Attributes Default Description

controller

'browser' | 'videoplayer'

The name of input contact controller.
It must be set to 'browser' to let the HTML/JavaScript layer control the inputs or 'videoplayer' to let the playback engine handle input contact actions.

lifetime

'url' | 'site' | 'session' | 'scenario'

'url'

The configuration lifetime can be set when the controller is the web browser.
This parameter defines when the configuration has to be reverted to video engine control.

Value	Description
'url'	The config is only applied to the current URL and is reverted when: the page location has changed following an hyperlink click or a programmatic change such as a modification of `window.location`. the page has been reloaded following a programmatic change such as `window.location.reload()`. the playback engine has processed a tag such as `[WEBS x]` or `[WEBE x]`. the browser has been closed with `[WEBS OFF]` or `[WEBE OFF]`.
'site'	The config is only applied to the current site and is reverted when: the playback engine has processed a tag such as `[WEBS x]` or `[WEBE x]`. the browser has been closed with `[WEBS OFF]` or `[WEBE OFF]`. Here we are referring to an engine site (not an URL) which is loaded using the `[WEBS x]` or `[WEBE x]` tags...
'session'	The config is applied to the current browser session. A session is started with `[WEBS x]` or `[WEBE x]` tags and is closed with `[WEBS OFF]` or `[WEBE OFF]`. The config is reverted when the browser session is closed.
'scenario'	The configuration is applied on the current scenario. It remains active between session (when the browser is closed), sites and URLs. To make it simple: the configuration stays active until another configuration is explicitly set.

keymaps

Object

Can only be used when controller is set to 'browser'.
Contains the keyboard events associated to each contact.
It makes it possible to handle input contact events as regular keyboard events, using keyup and keydown event handlers.

Properties

Name	Type	Attributes	Description
`combined`	Array.<string>	<optional>	The key mapping to use on the combined input contacts. This array must contain a maximum of 8 key names, one for each contact.
`standalone`	Array.<string>	<optional>	The key mapping to use on the standalone input contact. This array contains one single key name.

List of available key codes

Hover the mouse over the keys to see their names.

InputContactInfo

A InputContactInfo contains the states of one or more input contacts.

Properties:

Name	Type	Description
`name`	string	The logical name of the input contact group.
`values`	Array.<boolean>	An array of input contact values.

Events

InputContactEvent

InputContactEvent are fired when the state of the input contacts is modified.

Properties:

Name	Type	Description
`type`	'idal-contact-event'	The custom event type.
`detail`	Contact~InputContactInfo	The state of the input contacts.

This event shall be registered using window.addEventListener() as defined by the DOM specification.

Type:

external:CustomEvent

Example

window.addEventListener('idal-contact-event', function(e) {
    var info = e.detail;
    console.log("Input contact name: " + info.name);
    for (var i = 0 ; i < info.values.length ; i++) {
        console.log("Contact " + i + ": " + info.values[i]);
    }
});