TOI3/JS Events

TOI uses JavaScript events and event listeners to allow the portal to asynchronously respond to events within the KreaTV platform. Useful events include playback of a recorded program reaching the end, the connection or disconnection of an HDMI cable, errors with playback or with the network, and so on. The portal registers listeners, also known as callback functions, with event targets (a TOI object that generates events). When the event occurs, the appropriate callback function will be called, and useful information about the event will be passed into the callback as an argument.

Examples

Video output event

Let's look at a simplified example of adding an event listener to detect when a TV is connected or disconnected with a HDMI cable:

var vos = toi.videoOutputService;
var vconfig = vos.getVideoConfiguration();

vconfig.addEventListener(toi.consts.ToiVideoOutputConfiguration.ON_DISPLAY_CAPABILITIES_CHANGED,
                         onDisplayCapabilitiesChanged);

function onDisplayCapabilitiesChanged(evt)
{
  alert("Display changed!");
  switch (evt.info.status) {
    case toi.consts.ToiVideoOutputConfiguration.DISPLAY_STATUS_CONNECTED:
      console.log("Display Connected");
      break;
    case toi.consts.ToiVideoOutputConfiguration.DISPLAY_STATUS_DISCONNECTED:
      console.log("Display Disconnected");
      break;
    ...
  }
}

This example begins by asking the Video Output Service for the current ToiVideoOutputConfiguration. In the documentation for ToiVideoOutputConfiguration you can see that several events are defined.

When the HDMI cable is inserted or removed, the ON_DISPLAY_CAPABILITIES_CHANGED event will be triggered, and any registered listeners will be called. In the above example, the added listener is the onDisplayCapabilitiesChanged function. To allow the callback to do something useful, information about the event is passed as an argument to the listener function. Each event will pass it's own data structure describing the event, so check the documentation to see what information gets provided.

Media Player

It is common to add event listeners to the media player, to receive notifications on state changes (e.g. a transition from play to paused). Let's look at how this is set up:

// create the media player
var mediaPlayer = toi.mediaService.createPlayerInstance();

mediaPlayer.addEventListener(toi.consts.ToiMediaPlayerBase.ON_STATE_CHANGED,
                             onStateChanged);


function onStateChanged(evt)
{
  var msg = "Media player changed state to : ";
  switch(evt.state) {
    case toi.consts.ToiMediaPlayerBase.STATE_IDLE:
       msg += "STATE_IDLE";
       break;
    case toi.consts.ToiMediaPlayerBase.STATE_PLAYING:
       msg += "STATE_PLAYING";
       break;
    ...
  }
  alert(msg);
}

The documentation for ToiMediaPlayer does not list any events. This is because it inherits from ToiMediaPlayerBase, and it is there that the events are documented. There are many useful events listed here, including ON_STATE_CHANGED, ON_DATA_AVAILABLE and ON_STREAM_INFO_CHANGED. Take a look at the documentation for different events to see how they differ, when they are triggered, and why they may be useful to you.