UI インターフェース

オーバーレイ機能にアクセスするインターフェース

Epic Online Services では、オーバーレイ システムを介して製品に依存しないオーバーレイ ウィンドウをサポートします。これらのオーバーレイにより、ユーザーは製品に依存することなくさまざまな機能にアクセスすることができます。UI インターフェース はステータスの更新情報の提供、オーバーレイの表示または非表示、表示とホットキー設定の調整によりオーバーレイとのインタラクションを管理します。

SDK 1.5 以降、国コードはすべてのユーザー情報呼び出しで非推奨の値になっています。

UI インターフェースにアクセスするには、Platform (プラットフォーム) インターフェース 関数の EOS_Platform_GetUIInterfaceEOS_HUI ハンドルを取得します。すべての UI インターフェースの関数は、1 つ目のパラメータとしてこのハンドルを使用する必要があります。操作の完了時にコールバックがトリガーするように、EOS_HPlatform ハンドルがティックしていることを必ず確認してください。

各オーバーレイは製品とは無関係に、他のすべての EOS 製品と同じように動作します。UI インターフェースはオーバーレイを直接管理しません。また、オーバーレイからデータを読み取ったり、書き込んだりすることはできませんが、オーバーレイを表示または非表示にしたり、指定したオーバーレイが現在表示されているかどうかを検出したり、オーバーレイを表示または非表示にするユーザー ホットキーの取得や設定を指示することができます。

UI インターフェースは開発途中のため、現時点ではより大きな ソーシャル オーバーレイ の一部であるフレンド リストのページのみサポートしています。EOS SDK の将来のバージョンでは、複数のオーバーレイに渡る他のページのサポートを拡張する予定です。

オーバーレイを表示または非表示にする

フレンド リスト ページを表示するには、次のように初期化された EOS_UI_ShowFriendsOptions データ構造体を指定して EOS_UI_ShowFriends を呼び出します。

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.

完了すると、EOS_UI_OnShowFriendsCallback 型のコールバック関数は EOS_UI_ShowFriendsCallbackInfo データ構造体を含む呼び出しを受け取ります。

フレンド リスト ページを非表示にするには、次の情報が格納されている EOS_UI_HideFriendsOptions 構造体を指定して EOS_UI_HideFriends を呼び出します。

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.

操作が完了すると、EOSは EOS_UI_OnHideFriendsCallback 型のコールバック関数を実行し、EOS_UI_HideFriendsCallbackInfo 型のパラメータを渡します。

これらの操作により、オーバーレイ システム全体の可視性ステータスが変更されることがありますが、毎回変更されるわけではありません。たとえばオーバーレイ システムが非表示だった場合、フレンド リスト ページを表示するとオーバーレイ システムが表示されることがありますが、すでにフレンド リストや他のページが表示されている場合、システムはすでに表示されている可能性があります。同様に、ページを非表示にすると、それが最後に表示されていたページの場合はオーバーレイ システム全体が非表示になることがありますが、常にそうなるというわけではありません。オーバーレイ システムが表示されているかどうかをいつでも確認できる確実な方法についての詳細は、「オーバーレイの現在の可視性ステータスを検出する」セクションを参照してください。

可視性ステータスを検出する

UI インターフェースでは、可視性ステータスの情報について 2 つのレベルが提供されています。

1 つ目はオーバーレイ システム全体用です。1 つのオーバーレイで少なくとも 1 つのページが表示されていると、システム全体が表示されているとみなされます。この情報は、入力をルートする場所やシミュレーションを停止するタイミングなど、特定の高レベルの決定を行う場合に非常に有用です。

2 つ目のレベルは個別のページ用です。ページを開いたり閉じたりするためにコードがコマンドを発行する必要があるかどうかを確認する場合や、プレイヤーが必要な情報を表示できるかどうかを決定する場合に役立ちます。

オーバーレイ システムの可視性ステータス

EOS SDK により、デベロッパーはオーバーレイ システムの全体的な可視性ステータスを報告するためのコールバック関数を登録することができます。EOS_UI_OnDisplaySettingsUpdatedCallback 型のコールバックを登録するには、EOS SDK のロード時に EOS_UI_AddNotifyDisplaySettingsUpdated を呼び出し、適切に初期化された EOS_UI_AddNotifyDisplaySettingsUpdatedOptions データ構造体を渡します。

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_ADDNOTIFYDISPLAYSETTINGSUPDATED_API_LATEST.

コールバックは、現在の Platform インターフェース ティックまたは次のティックの間に実行されます。このコールバック中に受け取った値を追跡することにより、常にオーバーレイ システムの最新の可視性ステータスを確認することができます。

シャットダウン中に、EOS_UI_RemoveNotifyDisplaySettingsUpdated と、最初に登録した時に EOS_UI_AddNotifyDisplaySettingsUpdated によって返された EOS_NotificationId を使用してコールバックを削除します。

各ページの可視性ステータス

UI インターフェースが表示または非表示にできるページにはそれぞれ、可視性ステータスを報告するための独自の関数があります。フレンド リスト ページの場合は、次のように初期化された EOS_UI_GetFriendsVisibleOptions を指定して EOS_UI_GetFriendsVisible を呼び出します。

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 はページが表示されているかどうかを示す EOS_Bool を返します。

ホットキーを取得および設定する

ユーザーはホットキーを使用してオーバーレイ ページを表示または非表示にすることができます。ホットキーはトグルとして機能するため、ページを表示するホットキーでそのページを非表示にもできます。

ホットキーを定義するには、メイン キーと 1 つ以上のモディファイア キーを選択する必要があります。メイン キーには F1 キーから F12 キーまで、Space (スペース) キー、Backspace (バックスペース) キー、Esc キー、または Tab キーを指定することができます。モディファイア キーには Shift キー、Ctrl キー、および Alt キーが含まれます。

ホットキーの説明には、EOS_UI_EKeyCombination を使用します。次のサンプル コードのように、ビットごとの OR 演算を使用してキーの組み合わせをビルドし、EOS_UI_IsValidKeyCombination を使用してホットキーとして許容されるかどうかを検証します。

// 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.
}

UI インターフェースでは指定したページの現在のホットキーを確認する関数を提供し、新しい値に設定したり、EOS_UI_EKeyCombination::EOS_UIK_None を使用してシステムのデフォルト値にリセットしたりすることができます。

EOS_UI_GetToggleFriendsKey を呼び出し、フレンド リスト ページの現在のホットキーを取得します。EOS_UI_GetToggleFriendsKeyOptions パラメータを次のように設定します。

Property

Value

int32_t ApiVersion

API Version: Set this to EOS_UI_GETTOGGLEFRIENDSKEY_API_LATEST.

フレンド リスト ページのホットキーを設定またはリセットするには、次のように初期化された EOS_UI_SetToggleFriendsKeyOptions を指定して EOS_UI_SetToggleFriendsKeyOptions を使用します。

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.