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.

Creating the Content Overlay

To create a content overlay:

  1. Create a new composition.
  2. In the You.i Properties Panel, ensure that the composition has the type Regular Container.
  3. Check the custom class option and set it as CYIContentOverlay or add the comment usesCustomClass:true; class:CYIContentOverlay;.

Creating a Cross-Platform Solution

For cross-platform apps, developers can create the content overlay when the scene is loaded, and add it as follows:

#include <cloud/YiCloud.h>
#include <cloud/view/YiContentOverlay.h>
auto pViewTemplate = CYIViewTemplate::GetViewTemplate("MyProject_MyContentOverlay");
if (pViewTemplate){
  auto pContentOverlay = std::make_unique<CYIContentOverlay>();
  pContentOverlay->BuildFromTemplate(pSceneManager, pViewTemplate);
  pMyScene->AddChild(std::move(pContentOverlay), 0);

Configure the Content Overlay

Use the following CYIContentOverlay properties to configure a content overlay.

CYIContentOverlay Property Type Default Value Definition
SetInitiallyFocusedNode 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 specified, the focus is not automatically set, and the app is then responsible for setting the correct focus in the overlay.
SetInOutAnimationNames CYIString - The ID of the animations that are played when the view is shown and hidden on the Roku client.
SetCloseKey CYIString 'back' The device key string that triggers the overlay to close. Supported values:
‘back’ - Uses the standard back key on the controller.

' ' (empty string) - Disables the close button feature.
SetIdleTimerDuration 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/view/YiContentOverlay.h>
pContentOverlayView->SetInOutAnimationNames("Drawer-In", "Drawer-Out");


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.

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();


   return true;
 return false;

Properties of the Data API

| Property | Type | Notes | | ———- | —- | —– | | guid | uint64_t | Maps the You.i Platform GUID from a scene node. If multiple overlays are configured on the client, use this prop to distinguish which overlay the message came from. | | state | string | The new state of the overlay. 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. |