UI Interface

Epic Online Services (EOS) supports product-independent overlay windows through its Overlay system; these overlays give users product-independent access to various features. The UI Interface manages interactions with the overlays by providing status updates, showing or hiding the overlays, and adjusting display and hotkey preferences.

To access the UI Interface, acquire an EOS_HUI handle through the Platform Interface function, EOS_Platform_GetUIInterface. All UI Interface functions require this handle as their first parameter. You must ensure that the EOS_HPlatform handle is ticking for callbacks to trigger when operations complete.

Each overlay behaves independently of the product, and in a uniform manner with all other EOS products. The UI Interface does not directly control the overlays, and cannot read data from them or write data to them, but it can command them to show or hide themselves, detect whether a given overlay is currently visible, and get or set the user hotkey that shows or hides an overlay.

To show the friends list page, call EOS_UI_ShowFriends with an EOS_UI_ShowFriendsOptions data structure initialized as follows:

Upon completion, your callback function (of type EOS_UI_OnShowFriendsCallback) will receive a call that includes an EOS_UI_ShowFriendsCallbackInfo data structure.

To hide the friends list page, call EOS_UI_HideFriends with an EOS_UI_HideFriendsOptions structure that contains the following information:

When the operation finishes, EOS will run your callback function (of type EOS_UI_OnHideFriendsCallback), passing it a parameter of type EOS_UI_HideFriendsCallbackInfo.

EOS_UI_ShowBlockPlayer and EOS_UI_ShowReportPlayer trigger your game to display the Overlay with a report-or-block dialog box. Players use the dialog box to confirm they want to report or block their target player or to cancel the report or block action.

Make sure that it's clear in your game to players that they are triggering a social function when using EOS_UI_ShowReportPlayer and it's not part of your game. For example: A "REPORT" button available to members in a RTCP voice chat room.

Configure the EOS_UI_ShowBlockPlayerOptions parameter as follows:

Configure the EOS_UI_ShowReportPlayerOptions parameter as follows:

The UI Interface provides two levels of visibility status information.

The first is for the overlay system itself. When at least one page in one overlay is showing, the system as a whole is considered visible. This information can be very useful when making certain high-level decisions, such as where to route input, or when to pause simulation.

The second level is for individual pages. This is helpful to know whether or not the code should issue commands to open or close pages, or to determine if players are able to see information that they might need.

The EOS SDK enables developers to register a callback function for reporting of the overlay system's overall visibility status. To register your callback (of type EOS_UI_OnDisplaySettingsUpdatedCallback), call EOS_UI_AddNotifyDisplaySettingsUpdated when you load the EOS SDK, and pass in a properly-initialized EOS_UI_AddNotifyDisplaySettingsUpdatedOptions data structure:

During shutdown, remove your callback with the EOS_UI_RemoveNotifyDisplaySettingsUpdated and the EOS_NotificationId that was returned by EOS_UI_AddNotifyDisplaySettingsUpdated when you originally registered it.

Each page that the UI Interface can show or hide has its own function to report its visibility status. For the friends list page, call EOS_UI_GetFriendsVisible with an EOS_UI_GetFriendsVisibleOptions initialized as follows:

EOS_UI_GetFriendsVisible returns an EOS_Bool indicating whether the page is visible or not.

The Social Overlay processes notifications as they arrive. To pause this behavior use EOS_UI_PauseSocialOverlay. This is useful during cutscenes or loading. EOS_UI_IsSocialOverlayPaused can be used to retrieve the previously set pause state.

Configure the EOS_UI_PauseSocialOverlayOptions parameter as follows:

Users can use hotkeys to show or hide overlay pages. Hotkeys act as toggles, so the hotkey that shows a page will also hide that page.

To define a hotkey, you must pick a main key and one or more modifier keys. The main key can be F1 through F12, Space, Backspace, Escape, or Tab. Modifier keys include Shift, Control, and Alt.

To describe a hotkey, use an EOS_UI_EKeyCombination. You can build a key combination with bitwise OR operations, and verify that it is acceptable as a hotkey with EOS_UI_IsValidKeyCombination, as in the following sample code:

The UI Interface provides functions to check the current hotkey for a given page, set it to a new value, or reset it to the system default (with EOS_UI_EKeyCombination::EOS_UIK_None).

Call EOS_UI_GetToggleFriendsKey to get the current hotkey for the friends list page. Configure the EOS_UI_GetToggleFriendsKeyOptions parameter as follows:

To set (or reset) the hotkey for the friends list page, use EOS_UI_SetToggleFriendsKeyOptions with an EOS_UI_SetToggleFriendsKeyOptions initialized as follows: