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

ToiSecondaryApplication

Class Summary

Extends:
  • ToiEventTarget

A ToiSecondaryApplication object represents an installed user-facing application. A ToiSecondaryApplication object can be retrieved via ToiApplicationService#getSecondaryApplications and 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.

  • Methods
  • Members
  • Types
  • Events

Method Summary

getName ( )  → name

Return the unique identifier of a secondary application. Use this information to discern which object to perform operations on.
getProperties ( )  → Array.<ToiApplicationService.ToiApplicationProperty>

Returns the properties of the secondary application.
getState ( )  → state

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.
hasInputFocus ( )  → hasInputFocus

This method returns whether the secondary application has input focus or not.
hide ( callbacks )  → operation

Makes the application attempt to enter the ToiSecondaryApplication.STATE_HIDDEN state. This is only possible if it is in the ToiSecondaryApplication.STATE_VISIBLE or ToiSecondaryApplication.STATE_HIDDEN states. The operation will be considered completed and successful when ToiSecondaryApplication.STATE_HIDDEN is reached and, if this is not possible, the operation will be considered as failed.
setInputFocus ( )

Makes the application receive user input. After this function is called, the primary application will only receive input events it has subscribed to. This is only possible if the application is in the ToiSecondaryApplication.STATE_VISIBLE state.
setProperty ( name , value )

Set the value of an existing writable property.
show ( callbacks )  → operation

Makes the application attempt to enter the ToiSecondaryApplication.STATE_VISIBLE state. This is only possible if it is already in the ToiSecondaryApplication.STATE_HIDDEN or ToiSecondaryApplication.STATE_VISIBLE states.
start ( callbacks , parameters )  → operation

Makes the application attempt to enter the ToiSecondaryApplication.STATE_HIDDEN state via ToiSecondaryApplication.STATE_LOADING. This is not possible if it is already in the ToiSecondaryApplication.STATE_VISIBLE.
stop ( callbacks )  → operation

Makes the application enter the ToiSecondaryApplication.STATE_STOPPED state. This operation cannot 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

ToiState (Type: enum)

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

Events

  • ON_INPUT_FOCUS_CHANGED
  • ON_START_REQUESTED
  • ON_STATE_CHANGED
  • ON_STOP_REQUESTED

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 ( )  → name

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

Returns:

Return the name of the secondary application.

Type: string
getProperties ( )  → Array.<ToiApplicationService.ToiApplicationProperty>

Returns the properties of the secondary application.

Returns:

The properties of the secondary application.

Type: Array.<ToiApplicationService.ToiApplicationProperty>
getState ( )  → state

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.

Returns:

The current state of the secondary application.

Type: ToiSecondaryApplication.ToiState
hasInputFocus ( )  → hasInputFocus

This method returns whether the secondary application has input focus or not.

Returns:

Whether the secondary application has input focus.

Type: boolean
hide ( callbacks )  → operation

Makes the application attempt to enter the ToiSecondaryApplication.STATE_HIDDEN state. This is only possible if it is in the ToiSecondaryApplication.STATE_VISIBLE or ToiSecondaryApplication.STATE_HIDDEN states. The operation will be considered completed and successful when ToiSecondaryApplication.STATE_HIDDEN is reached and, if this is not possible, the operation will be considered as failed.

Parameters:

Name Type Description
callbacks AsyncCallback

Object with callback functions for the asynchronous operation. No result is produced by this method, so callbacks.onResult() will not be invoked.

Throws:

ToiInvalidArgumentException

Raised if the operationId is invalid.
ToiInvalidPreconditionException

Raised if the application is not in ToiSecondaryApplication.STATE_VISIBLE or ToiSecondaryApplication.STATE_HIDDEN.

Returns:

operation The asynchronous operation created by the function.

Type: ToiAsynchronousOperation
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 primary application will only receive input events it has subscribed to. This is only possible if the application is in the ToiSecondaryApplication.STATE_VISIBLE state.

Throws:

ToiInvalidPreconditionException

Raised if the application is not in ToiSecondaryApplication.STATE_VISIBLE.
setProperty ( name , value )

Set the value of an existing writable property.

Parameters:

Name Type Description
name string

Property name.
value string

Property value.

Throws:

ToiInvalidArgumentException

Raised if the property can't be set because it doesn't exist or is not writable.
show ( callbacks )  → operation

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

Parameters:

Name Type Description
callbacks AsyncCallback

Object with callback functions for the asynchronous operation. No result is produced by this method, so callbacks.onResult() will not be invoked.

Throws:

ToiInvalidArgumentException

Raised if the operationId is invalid.
ToiInvalidPreconditionException

Raised if the application is not in ToiSecondaryApplication.STATE_HIDDEN or ToiSecondaryApplication.STATE_VISIBLE.

Returns:

operation The asynchronous operation created by the function.

Type: ToiAsynchronousOperation
start ( callbacks , parameters )  → operation

Makes the application attempt to enter the ToiSecondaryApplication.STATE_HIDDEN state via ToiSecondaryApplication.STATE_LOADING. This is not possible if it is already in the ToiSecondaryApplication.STATE_VISIBLE.

Parameters:

Name Type Description
callbacks AsyncCallback

Object with callback functions for the asynchronous operation. No result is produced by this method, so callbacks.onResult() will not be invoked.
parameters
[optional] 		Array.<string>

Parameters 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 parameters.

Throws:

ToiInvalidArgumentException

Raised if the operationId is invalid.
ToiInvalidPreconditionException

Raised if the application is in STATE_VISIBLE.

Returns:

operation The asynchronous operation created by the function.

Type: ToiAsynchronousOperation
stop ( callbacks )  → operation

Makes the application enter the ToiSecondaryApplication.STATE_STOPPED state. This operation cannot fail.

Parameters:

Name Type Description
callbacks AsyncCallback

Object with callback functions for the asynchronous operation. No result is produced by this method, so callbacks.onResult() will not be invoked.

Throws:

ToiInvalidArgumentException

Raised if the operationId is invalid.

Returns:

operation The asynchronous operation created by the function.

Type: ToiAsynchronousOperation
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 W3C key identifier of the key to subscribe to.

Throws:

ToiInvalidArgumentException

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 W3C keyidentifier of the key to stop subscribing to.

Throws:

ToiInvalidArgumentException

Raised if the key is not a valid keyIdentifier.

Members

ON_INPUT_FOCUS_CHANGED (Type: ToiSecondaryApplicationInputFocusChangedEvent) (value = 253) (static, constant)

This is an Event identifier for ToiSecondaryApplicationInputFocusChangedEvent.

This notification will be triggered when a secondary application has changed input focus.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.ON_INPUT_FOCUS_CHANGED.
ON_START_REQUESTED (Type: ToiSecondaryApplicationStartRequestedEvent) (value = 251) (static, constant)

This is an Event identifier for ToiSecondaryApplicationStartRequestedEvent.

This notification will be triggered when there is an external request to start the secondary application.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.ON_START_REQUESTED.
ON_STATE_CHANGED (Type: ToiSecondaryApplicationStateChangedEvent) (value = 250) (static, constant)

This is an Event identifier for ToiSecondaryApplicationStateChangedEvent.

This notification will be triggered when a secondary application has changed state.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.ON_STATE_CHANGED.
ON_STOP_REQUESTED (Type: ToiSecondaryApplicationStopRequestedEvent) (value = 252) (static, constant)

This is an Event identifier for ToiSecondaryApplicationStopRequestedEvent.

This notification will be triggered when there is an external request to stop the secondary application.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.ON_STOP_REQUESTED.
STATE_HIDDEN (Type: ToiSecondaryApplication.ToiState) (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 also be accessed from toi.consts.ToiSecondaryApplication.STATE_HIDDEN.
STATE_LOADING (Type: ToiSecondaryApplication.ToiState) (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 ToiSecondaryApplicationStateChangedEvent event.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.STATE_LOADING.
STATE_STOPPED (Type: ToiSecondaryApplication.ToiState) (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 ToiInvalidPreconditionException.

This constant can also be accessed from toi.consts.ToiSecondaryApplication.STATE_STOPPED.
STATE_VISIBLE (Type: ToiSecondaryApplication.ToiState) (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 also be accessed from toi.consts.ToiSecondaryApplication.STATE_VISIBLE.

Events

ON_INPUT_FOCUS_CHANGED ( )

This is an Event identifier for ToiSecondaryApplicationInputFocusChangedEvent.

Value: 253

ON_START_REQUESTED ( )

This is an Event identifier for ToiSecondaryApplicationStartRequestedEvent.

Value: 251

ON_STATE_CHANGED ( )

This is an Event identifier for ToiSecondaryApplicationStateChangedEvent.

Value: 250

ON_STOP_REQUESTED ( )

This is an Event identifier for ToiSecondaryApplicationStopRequestedEvent.

Value: 252

5.1.1.p8

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