• Quick Start
  • Booting
  • Platform
  • Portals
  • References
    • API Reference TOI3
    • IIP Reference
  • Resources
ARRIS Enterprises, Inc. Confidential Information

ToiSecondaryApplication

Class Summary

Extends:
  • ToiEventTarget

This interface is a TECHNICAL PREVIEW, it may change.
Please note that the state behaviour is not finished. It is very likely that behavioural changes will be implemented in the future. Use this interface at your own risk and be prepared for breaking changes.
A ToiSecondaryApplication object represents an installed user-facing application. A ToiSecondaryApplication object can be used to control or query an application for information.
Only applications that are intended for direct user control are represented as ToiSecondaryApplication objects. These applications may be Linux programs, web pages or other things, but they should implement the concepts of being displayed to the user and accepting user input. They can be viewed as alternative modes of operation to the main UI, which itself is not a ToiSecondaryApplication.
ToiSecondaryApplication objects do not have a persistent internal state and can be freely copied or deleted.

  • Methods
  • Members
  • Types
  • Events

Method Summary

getName ( )

Return the unique identifier of a ToiSecondaryApplication. Use this information to discern which object to perform operations on.
getState ( )

Returns the current state of the application. Valid return values are:
ToiSecondaryApplication.STATE_STOPPED: The application is not running
ToiSecondaryApplication.STATE_LOADING: The application is loading and will be running shortly
ToiSecondaryApplication.STATE_VISIBLE: The application is running and visible
ToiSecondaryApplication.STATE_HIDDEN: The application is running but is hidden
hide ( )

Makes the application attempt to enter the STATE_HIDDEN state. This is only possible if it is already in the STATE_VISIBLE state.
setInputFocus ( )

Makes the application receive user input. After this function is called, the main UI will not receive input events unless they have been subscribed to. This is only possible if the application is in the STATE_VISIBLE state.
show ( argument )

Makes the application attempt to enter the STATE_VISIBLE state. This is only possible if it is already in the STATE_HIDDEN or STATE_VISIBLE states.
If it is already in the STATE_VISIBLE state, the application will receive the argument but not change its state. Please note that this behaviour is likely to change in the future.
start ( )

Makes the application attempt to enter the STATE_LOADING state. This is only possible if it is already in the STATE_STOPPED state. The application will transit to STATE_HIDDEN after loading successfully.
stop ( )

Makes the application enter the STATE_STOPPED state. This operation can not fail.
subscribeKey ( key )

Subscribe to key presses sent to this application. If the subscribed key is pressed while this application has input focus, the main UI will receive it as well.
unsubscribeKey ( key )

Stop subscribing to key presses sent to this application.

Inherited Methods

addEventListener ( type , listener )

This method registers an event listener for a specific event. Multiple listeners can be added for the same event. Events are broadcast to all registered listeners.
removeEventListener ( type , listener )

This method removes an event listener for a specific event.

Type Definitions

ToiApplicationState (Type: enum)

The the different states a secondary application can be in.
  • STATE_HIDDEN
  • STATE_LOADING
  • STATE_STOPPED
  • STATE_VISIBLE

Events

  • ON_STATE_CHANGED

Methods

addEventListener ( type , listener )

This method registers an event listener for a specific event. Multiple listeners can be added for the same event. Events are broadcast to all registered listeners.

Inherited From:

  • ToiEventTarget#addEventListener

Parameters:

Name Type Description
type number

The event type of the event to subscribe to.
listener ToiEventListener

The JavaScript function that will receive events.

Throws:

ToiInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the application calls addEventListener with the same combination of type and listener twice.
getName ( )

Return the unique identifier of a ToiSecondaryApplication. Use this information to discern which object to perform operations on.

Returns:

Return the name of the secondary application.

Type: string
getState ( )

Returns the current state of the application. Valid return values are:
ToiSecondaryApplication.STATE_STOPPED: The application is not running
ToiSecondaryApplication.STATE_LOADING: The application is loading and will be running shortly
ToiSecondaryApplication.STATE_VISIBLE: The application is running and visible
ToiSecondaryApplication.STATE_HIDDEN: The application is running but is hidden

hide ( )

Makes the application attempt to enter the STATE_HIDDEN state. This is only possible if it is already in the STATE_VISIBLE state.

Throws:

ToiInvalidPreconditionException Raised if the application is not in STATE_VISIBLE.
removeEventListener ( type , listener )

This method removes an event listener for a specific event.

Inherited From:

  • ToiEventTarget#removeEventListener

Parameters:

Name Type Description
type number

The event type of the event to remove the listener from.
listener ToiEventListener

The JavaScript function that was previously added as an event listener.

Throws:

ToiInvalidArgumentException Raised if the event type is not supported by this object or if the listener is not a valid JavaScript function. This exception is also raised if the listener has not previously been added.
setInputFocus ( )

Makes the application receive user input. After this function is called, the main UI will not receive input events unless they have been subscribed to. This is only possible if the application is in the STATE_VISIBLE state.

Throws:

ToiInvalidPreconditionException Raised if the application is not in STATE_VISIBLE.
show ( argument )

Makes the application attempt to enter the STATE_VISIBLE state. This is only possible if it is already in the STATE_HIDDEN or STATE_VISIBLE states.
If it is already in the STATE_VISIBLE state, the application will receive the argument but not change its state. Please note that this behaviour is likely to change in the future.

Parameters:

Name Type Description
argument
[optional] 		string

An argument to pass to the application, such as the URL of a webpage. It is up to the application to define and document how it handles arguments to show().

Throws:

ToiInvalidPreconditionException Raised if the application is not in STATE_HIDDEN or STATE_VISIBLE.
start ( )

Makes the application attempt to enter the STATE_LOADING state. This is only possible if it is already in the STATE_STOPPED state. The application will transit to STATE_HIDDEN after loading successfully.

Throws:

ToiInvalidPreconditionException Raised if the application is not in STATE_STOPPED.
stop ( )

Makes the application enter the STATE_STOPPED state. This operation can not fail.

subscribeKey ( key )

Subscribe to key presses sent to this application. If the subscribed key is pressed while this application has input focus, the main UI will receive it as well.

Parameters:

Name Type Description
key string

The keyidentifier of the key to subscribe to.

Throws:

TToiInvalidArgumentException Raised if the key is not a valid keyIdentifier.
unsubscribeKey ( key )

Stop subscribing to key presses sent to this application.

Parameters:

Name Type Description
key string

The keyidentifier of the key to stop subscribing to.

Throws:

TToiInvalidArgumentException Raised if the key is not a valid keyIdentifier.

Members

ON_STATE_CHANGED (Type: ToiSecondaryApplicationStateChangedEvent) (value = 250) (static, constant)

This is an Event identifier for ToiSecondaryApplicationStateChangedEvent.

This method is called when a subscribed secondary application has changed state.

This constant can be also be accessed from toi.consts.ToiSecondaryApplication.ON_STATE_CHANGED.
STATE_HIDDEN (Type: ToiSecondaryApplication.ToiApplicationState) (value = 2) (static, constant)

In STATE_HIDDEN the application is running but not visible. When in this state, the application can not be displayed, but it may be performing background tasks. In general, it can be assumed that an application in STATE_HIDDEN is less demanding on system resources than when it is in STATE_VISIBLE. An application in this state can be made visible or stopped.

This constant can be also be accessed from toi.consts.ToiSecondaryApplication.STATE_HIDDEN.
STATE_LOADING (Type: ToiSecondaryApplication.ToiApplicationState) (value = 1) (static, constant)

In STATE_LOADING the application is in its warmup phase. When in this state, the application can not be displayed or interacted with. The only allowed operation is to stop it. After some time, the application will transition to STATE_HIDDEN. This will be signalled to listeners who are subscribed to the application object with the ToiSecondaryApplication.ON_STATE_CHANGED event.

This constant can be also be accessed from toi.consts.ToiSecondaryApplication.STATE_LOADING.
STATE_STOPPED (Type: ToiSecondaryApplication.ToiApplicationState) (value = 0) (static, constant)

In STATE_STOPPED the application is not running. When in this state, the application can not be displayed or interacted with by the user. Functions that require an application to be running will fail with a \ref TToiInvalidPrecondition exception.

This constant can be also be accessed from toi.consts.ToiSecondaryApplication.STATE_STOPPED.
STATE_VISIBLE (Type: ToiSecondaryApplication.ToiApplicationState) (value = 3) (static, constant)

In STATE_VISIBLE, the application is running and is displaying graphics. When in this state, the application can be displayed below the main UI, which means it is up to the main UI to make itself transparent or invisible in order to make the secondary application appear. An application in this state can be made invisible or stopped.

This constant can be also be accessed from toi.consts.ToiSecondaryApplication.STATE_VISIBLE.

5.0.1

Copyright (c) 2016 ARRIS Enterprises, LLC. All Rights Reserved. ARRIS Enterprises, LLC. Confidential Information.