UI Interface

Interface that accesses overlay features

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.

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 Online Services 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 Online Services 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.

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 Online Services Account ID of the user whose overlay is being updated.

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

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:

// Set ProposedHotKey to Alt-Shift-Tab.
EOS_UI_EKeyCombination ProposedHotKey = EOS_UI_EKeyCombination::EOS_UIK_Alt | EOS_UI_EKeyCombination::EOS_UIK_Shift | EOS_UI_EKeyCombination::EOS_UIK_Tab;

// Ask the UI Interface if ProposedHotKey is acceptable.
if (EOS_UI_IsValidKeyCombination(ProposedHotKey) == EOS_TRUE)
{
    // ProposedHotKey is valid.
}

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.