UI Interface

Interface that accesses overlay features.

6 mins to read

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.

As of SDK 1.5, country codes are deprecated values in all User Info calls.

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.

The UI Interface is a work in progress, and currently only supports the friends list page, which is part of the larger Social Overlay; future versions of the EOS SDK will expand support for other pages across multiple overlays.

Showing or Hiding an Overlay

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

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SHOWFRIENDS_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Account ID of the user whose friend list is being shown.

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_HIDEFRIENDS_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Account ID of the user whose friend list is being shown.

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

These operations could change the overall visibility status of the overlay system, but they will not necessarily do so every time. For example, showing the friends list page could make the Overlay system become visible if it was previously invisible, but the system could have been visible already if it was already displaying the friends list or another page. Similarly, hiding a page could result in the entire overlay system becoming invisible if that was the last page being displayed, but this will not always be the case. See the section on Detecting the Overlay's Current Visibility Status for a reliable way to know whether the Overlay system is visible at any given time.

Blocking and Reporting

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SHOWBLOCKPLAYER_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Online Services Account ID of the player requesting to block another player.
EOS_EpicAccountId TargetUserIdThe Epic Online Services Account ID of the player to be blocked.

Configure the EOS_UI_ShowReportPlayerOptions parameter as follows:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SHOWREPORTPLAYER_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Online Services Account ID of the player requesting the report.
EOS_EpicAccountId TargetUserIdThe Epic Online Services Account ID of the reported player.

Detecting Visibility Status

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.

Overlay System Visibility Status

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_ADDNOTIFYDISPLAYSETTINGSUPDATED_API_LATEST.

Your callback will run during either the current Platform Interface tick or the next one. By tracking the values you receive during this callback, you can know the latest visibility status of the overlay system at all times.

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.

Individual Page Visibility Status

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_GETFRIENDSVISIBLE_API_LATEST.
EOS_EpicAccountId LocalUserIdThe Epic Account ID of the user whose overlay is being checked.

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

Pausing the Social Overlay

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_PAUSESOCIALOVERLAY_API_LATEST
EOS_Bool bIsPausedThe desired bIsPaused state of the overlay.

Getting and Setting Hotkeys

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:

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_GETTOGGLEFRIENDSKEY_API_LATEST.

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

PropertyValue
int32_t ApiVersionAPI Version: Set this to EOS_UI_SETTOGGLEFRIENDSKEY_API_LATEST.
EOS_UI_EKeyCombination KeyCombinationThe new key combination which will be used to toggle the friends overlay. The combination can be any set of modifiers and one key. A value of EOS_UIK_None will cause the key to revert to the default.