Roku Video Content Overlay

The video content overlay coordinates with the Cloud server to export dynamic view layouts for sub-elements. The content overlay works with the Disconnect on Inactivity feature to allow apps to safely disconnect and reconnect later, when the user input requires the app to reconnect to the server.

The video content overlay is a conditionally exported component. When initially exported, the overlay only includes the overlay container object. Once the overlay container gains focus, or the app sets the overlay state to active, an export is triggered by the Cloud server to include all the overlays’ descendant nodes. When the focus leaves the overlay component focus hierarchy, or the user presses the Close key, then the overlay transitions to the hide state. The Cloud server triggers an export that clears the overlay from the scene. You can configure some of the functionality in the content overlay configuration properties.

Configure the Content Overlay

To set up a content overlay, you need to create a content overlay configuration and then pass the configuration into the ConfigureContentOverlay function of the Cloud interface.

CYIContentOverlay::Configuration

A group of properties used to configure and build a content overlay.

CYIContentOverlay Configuration Properties Type Default Value Definition
m_pContentOverlayNode CYISceneView - The root node of the content overlay. All overlay elements should be children of this node. We recommend that your focus in and focus out animations are applied to this element.
m_pInitialFocusNode CYISceneView - The node that sets the initial focus when the content overlay is animated in. Does not support setting subfocus for a list item. If not set, then the focus is not automatically set. The app is then responsible for setting the correct focus in the overlay.
m_inAnimation CYIString - The ID of the animation that is played when the view is shown on the Roku client.
m_outAnimation CYIString - The ID of the animation that is played when the view is hidden on the Roku client
m_closeKey CYIString 'back' The device key string that triggers the overlay to close. Supported values are: ‘back’ - uses the standard back key on the controller. ' ' - empty string. This disables the close button feature.
m_idleTimerDuration Int 5 seconds The time to wait for user input before closing the overlay automatically, in seconds. A setting of 0 means the overlay does not close automatically.

Configuration Example

#include <cloud/YiCloud.h>
#include <cloud/overlay/YiContentOverlay.h>
...
CYIContentOverlay::Configuration config(pContentOverlayView, pListView, "Drawer-In", "Drawer-Out");
CYICloud::GetInterface().ConfigureContentOverlay(config);

Focus

For focus-based exports to work, the root scene view that you define for the content overlay must have the focusable parameter set to true. It’s also recommended that you manually set up your initial focus relationship for the overlay to ensure that it gains focus. For example, the following code snippet sets focusable to true and sets the next focus.

pContentOverlayView->SetFocusable(true);
m_pVideoSurfaceView->SetNextFocus(pContentOverlayView, CYIFocus::Direction::Down);

State Changes

To get notification in your app when the content overlay state changes, register for the “overlayStateChange” client data message that contains the Global Unique Identifier (GUID) of the view and the new state as shown in the code snippet below. The state change message is mapped to the client overlay state. For example, if you have defined an animation in your app, the state change message is sent once the animation for that state has completed.

#include <utility/YiRapidJSONUtility.h>
#include <cloud/YiCloud.h>
...
m_evtListenerId = CYICloud::GetInterface().RegisterDataListener("overlayStateChange", [](CYIString eventId, const yi::rapidjson::Document *pEvent) {
  auto pEvtData = pEvent->FindMember("data");
  auto pItrGuid = pEvtData->value.FindMember("guid");
  uint64_t guid = pItrGuid->value.GetUint64();

  // Validate that the message is for the correct overlay 
  if (guid == m_pOverlayView->GetUniqueID())
  {
   auto pItrState = pEvtData->value.FindMember("state");
   CYIString state = pItrState->value.GetString();

   // CUSTOM APP LOGIC HERE

   return true;
  }
 return false;
});

Properties of the Data API

Properties Type Notes
"guid" uint64_t This maps the You.i Engine One GUID from a scene node. If there are multiple overlays setup on the client, this should be used to distinguish which overlay the message came from.
"state" string The new state of the overlay. This corresponds to the state of the client. show: The overlay has been shown on the client and the in animation has completed. hide: The overlay has been hidden on the client and the out animation has completed.