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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_SHOWFRIENDS_API_LATEST. |
EOS_EpicAccountId LocalUserId | The 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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_HIDEFRIENDS_API_LATEST. |
EOS_EpicAccountId LocalUserId | The 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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_SHOWBLOCKPLAYER_API_LATEST. |
EOS_EpicAccountId LocalUserId | The Epic Online Services Account ID of the player requesting to block another player. |
EOS_EpicAccountId TargetUserId | The Epic Online Services Account ID of the player to be blocked. |
Configure the EOS_UI_ShowReportPlayerOptions
parameter as follows:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_SHOWREPORTPLAYER_API_LATEST. |
EOS_EpicAccountId LocalUserId | The Epic Online Services Account ID of the player requesting the report. |
EOS_EpicAccountId TargetUserId | The 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:
Property | Value |
---|---|
int32_t ApiVersion | API 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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_GETFRIENDSVISIBLE_API_LATEST. |
EOS_EpicAccountId LocalUserId | The 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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_PAUSESOCIALOVERLAY_API_LATEST |
EOS_Bool bIsPaused | The 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:
Property | Value |
---|---|
int32_t ApiVersion | API 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:
Property | Value |
---|---|
int32_t ApiVersion | API Version: Set this to EOS_UI_SETTOGGLEFRIENDSKEY_API_LATEST. |
EOS_UI_EKeyCombination KeyCombination | The 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. |