CommonUI は スレート/UMG フレームワークの拡張機能です。CommonUI は入力を送信するメソッドを実装しますが、スレートの既存の入力システムの基礎となるロジックに依然として依存します。
このガイドの各セクションには、CommonUI のさまざまな部分とベース スレート/UMG 入力システムとのインタラクションの調整に利用できるヒントやメソッドが記載されています。
入力コンフィグでアプリケーションの UI 入力処理を変更する
状況によっては、現在アクティブなウィジェットに基づいてアプリケーションの入力処理方法を変えたい場合があります。たとえば、ソーシャル サイドバーやポーズ メニューが開いているときには、ゲーム ワールド内でプレイヤーを移動させたくない場合などです。こういった状況に対応するために、CommonUI では アクティベート可能なウィジェット のための任意の 入力コンフィグ をサポートしています。
アプリケーションで入力コンフィグを使用することは必須ではなく、これを使用するかどうかにかかわらず、CommonUI の他の機能のメリットを得ることは可能です。
ウィジェットで入力コンフィグを使用する
入力コンフィグは、「UIActionBindingHandle.h
」にある FUIInputConfig
構造体によって表されます。それぞれの入力コンフィグでは、マウス キャプチャ オプション、移動と外観の各軸の処理、さらに CommonUI が使用する全体的な入力モードを含む複数の入力方法のステートがトラックされます。
アクティベート可能なウィジェットを有効にすると、UCommonActivatableWidget::GetDesiredInputConfig
を使って入力コンフィグが取得されます。この関数はデフォルトでヌルの入力コンフィグを返しますが、使用したいロジックでこれをオーバーライドすることができます。この関数でヌルの入力コンフィグが返されると、CommonUI は最後に使用した有効な入力コンフィグにフォールバックします。
アクティベート可能なウィジェットで指定された入力コンフィグがない場合、CommonUI ではフォールバックとしてデフォルトの入力コンフィグをデフォルトで適用します。ただし、この動作は UCommonInputSettings
クラスの bEnableDefaultInputConfig
変数を使って無効にすることができます。
ウィジェットが無効になると、CommonUI では以前に使用した入力コンフィグをリストアすることで、現在のウィジェットをサポートするために、適切な入力コンフィグがないことで処理が滞ることを回避します。この実装ロジックは FActivatableTreeRoot::ApplyLeafmostNodeConfig
関数にあります。
UI のすべてのウィジェットを無効にした場合、CommonUI は最後に無効になったウィジェットの入力コンフィグをデフォルトで使用します。UI のすべてのウィジェットを無効にする必要がある場合は、ソフトロックを回避するために、最後に無効になったウィジェットによって妥当な入力処理ステートが再び適用されることを確認してください。
推奨される使用方法
入力コンフィグを使用する際は、**UI で標準的な入力コンフィギュレーション メソッドを使用しないでください。** UCommonUIActionRouterBase::ApplyInputConfig
仮想関数のデフォルトの実装では、設定プロセスの一環として次の標準的な UE コンフィギュレーション メソッドを呼び出します。
-
APlayerController::SetIgnoreMoveInput
-
UGameViewportClient::SetMouseCaptureMode
-
UGameViewportClient::SetHideCursorDuringCapture
このため、CommonUI の入力コンフィグとこれらの関数への他の呼び出しを一緒に使用すると、互いにオーバーライドしあうことで入力ステートの管理に支障をきたす可能性があります。
入力コンフィグの管理を簡素化するために、ウィジェットの列挙型変数値に応じて一般的に使用される入力コンフィグを割り当てる、デフォルトの実装を作成できます。この例については、Lyra サンプル プロジェクト を参照してください。このプロジェクトでは、ウィジェットごとに固定された非動的な入力コンフィグのみを必要とするアプリケーションに役立つ実装が提供されています。
入力処理ステートのリファレンス
FUIInputConfig
では一連の複数の入力ステートをトラックします。UCommonActivatableWidget::GetDesiredInputConfig
で入力コンフィグを設定すると、ウィジェットにフォーカスがある場合の入力処理の完全なコンフィギュレーションが整います。これらのステートは、以下の変数を使ってトラックされます。
パラメータ | 型 | 説明 |
---|---|---|
InputMode |
列挙型 / ECommonInputMode |
CommonUI の内部入力モードを設定します。 |
MouseCaptureMode |
列挙型 / EMouseCaptureMode |
CommonUI のマウス キャプチャ モードを設定します。 |
bHideCursorDuringViewportCapture |
ブール型 | true の場合は、マウス キャプチャ時にビューポートによってマウス カーソルが非表示になります。 |
bIgnoreMoveInput |
ブール型 | true の場合は、プレイヤー コントローラーによって移動の入力が無視されます。 |
bIgnoreLookInput |
ブール型 | true の場合は、プレイヤー コントローラーによって外観の入力が無視されます。 |
次の表には、入力モード (ECommonInputMode
) を設定する際に使用可能なモードがまとめられています。
入力モード | 説明 |
---|---|
Menu | UI のみが入力を受け取ります。 |
Game | ゲームのみが入力を受け取ります。 |
All | UI とゲームの両方が入力を受け取ります。 |
次の表には、マウス キャプチャ モード (EMouseCaptureMode
) を設定する際に使用可能なモードがまとめられています。
マウス キャプチャ モード | 説明 |
---|---|
No Capture | マウスをまったくキャプチャしません。 |
CapturePermanently | ビューポートがクリックされたときに永続的にマウスをキャプチャし、キャプチャをトリガーした最初のマウス押下を消費することで、マウス押下がプレイヤー入力によって処理されないようにします。 |
CapturePermanently_IncludingInitialMouseDown | CapturePermanently とほぼ同じですが、キャプチャをトリガーしたマウス押下はプレイヤー入力で処理されます。 |
CaptureDuringMouseDown | マウス ボタンが押されたときにマウスをキャプチャし、マウス ボタンが放されたときに解放します。 |
CaptureDuringRightMouseDown | マウスの右ボタンが押されたときのみにキャプチャします。他のマウス ボタンではキャプチャは開始されません。 |
FReply を使って入力に対するウィジェットの反応を変更する
FReply
は、入力デバイスの処理済み/未処理の状態をトラックします。スレートのほとんどの入力ハンドラは FReply::Handled
か FReply::Unhandled
のいずれかの結果を返します。
FReply::Handled
は、入力が他のウィジェットや入力システムに 送信されるべきではない ことを全般的に示します。FReply::Unhandled
は、入力が何らかの方法で使用された場合であっても、追加の処理に向けて入力が他のウィジェットや入力システムに 送信されるべきである ことを示します。
次は、よく使用される SWidget
入力イベントの一部です。
FReply OnKeyUp(const FGeometry& MyGeometry, const FKeyEvent& InKeyEvent);
FReply OnAnalogValueChanged(const FGeometry& MyGeometry, const FAnalogInputEvent& InAnalogInputEvent);
FReply OnMouseMove(const FGeometry& MyGeometry, const FPointerEvent& MouseEvent);
void OnMouseEnter(const FGeometry& MyGeometry, const FPointerEvent& MouseEvent);
これらの関数の多く (ただしすべてではない) は FReply
を返します。これらのリプライはブループリントで設定またはオーバーライドできるため、特定の型の入力の処理を停止または許可する必要がある場合は、目的の結果を得るために、特定の FReply
が返されるようにすることができます。ただし、ほとんどの場合、適切に設計されたウィジェット (または一連のウィジェット) にはデフォルトの FReply
の結果で十分です。カスタム仕様の FReply
を扱うことが問題となるのは、スレートでウィジェットを使用する場合です。

FReply 入力ルーティングを描いたチャートです。入力はプラットフォーム独自の入力イベントで開始され、スレート アプリケーションに送信されます。スレート アプリケーションではそれをウィジェットに送信します。ウィジェットでは FReply を使って、入力が Handled (処理済み) か Unhandled (未処理) かを判断します。入力が Handled になるか、すべてのウィジェットがチェックされるまで、この処理が繰り返されます。
FReply 設定
FReply
は入力イベントの Handled/Unhandled (処理済み/未処理) の状態をトラックしますが、以下のメンバーなどを使って、FReply
内で追加のデータをトラックすることもできます。
パラメータ | 説明 |
---|---|
CaptureMouse | すべてのマウス イベントを特定のウィジェットに送信するようシステムに要求します。 |
ClearUserFocus | ユーザー フォーカスをクリアするようシステムに要求します。 |
ReleaseMouseCapture | マウス キャプチャを解放するようシステムに要求します。 |
SetUserFocus | 指定したウィジェットにユーザーのフォーカスを設定するようシステムに要求します。 |
SetNavigation | 指定した目的地へのナビゲーションを試行するようシステムに要求します。 |
上記のリストは完全なリストではなく、どういったメソッドが利用可能であるかを紹介するだけのものにすぎません。完全なリストについては、公式の C++ API の FReply
を参照してください。
FReply::CaptureMouse
や FReply::SetUserFocus
など、これらの一部の関数では、ターゲット ウィジェットを含む追加の引数を受け取ります。
UMG またはスレートでの作業経験があれば、これらのメソッドに見覚えがあるかもしれませんが、これらは FReply
名前空間にあるため、スレートによって FReply
が処理される際に生じる動作を変更できることを意味しています。これらのメソッドを FReply
で呼び出すことで、同等のメソッドを FReply
外で呼び出すことでは簡単にレプリケートできない可能性のある、やや異なる動作を生成することができます。
FReply を設定すべき状況
FReply
を使用すべき状況の例として、キーの押下でウィジェットを設定またはクリアする必要がある状況を考えてください。通常は、キー押下ハンドラの FSlateApplication
で関連する関数を直接呼び出すことで、ウィジェットのフォーカスを変更することができます。
このアプローチは、特に入力ルーティングを使用する場合など、すべてのシナリオで機能するわけではありません。これは、入力が現在のウィジェットでまだ処理中であるにもかかわらず、フォーカスを変更またはクリアしようとするためです。この入力フローでは、目的の動作にはつながらない可能性があります。
代わりにスレートを使って入力を完全に処理し、入力イベント リプライまたは FReply
を使ってこれらのような変更を処理します。
元来、FReply
API で制御または公開されるステートでは、FReply
を使って設定されることのみを意図していました。過度な制限があることでこれが変更されたため、このワークフローは推奨されるガイドラインと捉えることができます。ただし、これが望ましいワークフローであるため、その使用を強く推奨します。
UI のナビゲーションをカスタマイズする
このセクションでは、CommonUI のナビゲーションをカスタマイズするためのガイドラインとオプションについて説明します。
ナビゲーション コンフィグ
ナビゲーション コンフィグは CommonUI に直接関連するわけではありませんが、ナビゲーション コンフィグを理解することで、入力処理に関する理解を深めることができます。
スレートでは、CommonUI が有効かどうかにかかわらずカーディナル ナビゲーションがサポートされます。ナビゲーション コンフィグ、もしくは FNavigationConfig
を使用することで、基本方位にマッピングするキーを定義します。
- Left (左)
- Right (右)
- Up (上)
- Down (下)
- Next (次)
- Previous (前)
スレートでカーディナル ナビゲーションを使用するうえで、手動でのナビゲーションのコンフィギュレーションは必須ではありません。
ナビゲーション コンフィグを設定するには FSlateApplication::SetNavigationConfig
を呼び出します。通常、この関数は、FNavigationConfig
から派生したカスタム仕様のナビゲーション コンフィグを使って呼び出します。たとえば、ユーザーに WASD キーを使って UI とやり取りさせたい場合は、これがその起点となります。
FSlateUser::SetUserNavigationConfig
を呼び出すことで、ナビゲーション コンフィグをユーザーごとに設定することもできます。
ナビゲーションを手動で制御する
ナビゲーション イベントが発生した際の処理を手動で設定するには、UMG でウィジェットを選択して、[Details (詳細)] パネル の [Navigation (ナビゲーション)] セクションに移動します。このセクションには、それぞれの基本方位のオプションが含まれています。

各オプションの説明は次のとおりです。
ナビゲーション制御オプション | 説明 |
---|---|
Escape (エスケープ) | 当該の方向への動きを継続することを許可し、次のナビゲート可能なウィジェットを自動的に探します。 |
Explicit (明示的) | 特定のウィジェットに移動します。 |
Wrap (ラップ) | このコンテナ内の動きをラップして、ナビゲーションの試行がエスケープされた場合に動きを反対側から循環させます。 |
Stop (停止) | この方向の動きを停止します。 |
Custom (カスタム) | ユーザー コードで処理されるカスタム仕様のナビゲーションです。 |
CustomBoundary (カスタム境界) | 境界をヒットした場合にユーザー コードで処理されるカスタム仕様のナビゲーションです。 |
次は、[Explicit] が適したオプションであるユースケースの例です。

この例では、上と下のボタンが垂直方向でオーバーラップせず、左のボタンにフォーカスがあります。オーバーラップがないため、Right (右) にナビゲートすると、Unreal では最も右側にあるボタンにフォーカスします。Right を上のボタンにナビゲートさせたい場合は、[Navigation] の設定をそのように設定できます。

Explicit ナビゲーションを TopButton ウィジェットに設定することで、ユーザーが Right を押すと、そのウィジェットが代わりにフォーカスされるようになります。
ウィジェットを Explicit ナビゲーションのターゲットとして設定するには、それを手動で指定する必要があります。こうすることで、ナビゲーション動作の長期間にわたる保全性を確保することができます。
アクティベート可能なウィジェットとアクション バインディング
このセクションでは、UI におけるアクティベート可能なウィジェットと、結合された入力アクションの動作をカスタマイズする方法について説明します。
アクティベート可能なウィジェットのアクティベーション時のフォーカスを設定する
アクティベート可能なウィジェットを有効にするたびに UCommonActivatableWidget::GetDesiredFocusTarget
関数が呼び出されて、CommonUI でユーザーの入力をフォーカスすべきウィジェットが選択されます。
GetDesiredFocusTarget
のカスタム仕様バージョンを実装していないと、ウィジェットが有効/無効になる際に、何にフォーカスすべきかを CommonUI が判断しづらくなる場合があります。このため、アクティベート可能なウィジェットには、この関数を常に実装することを強く推奨します。
Lyra サンプル プロジェクト では、それぞれの Activatable Widget クラスに、目的のフォーカス ターゲットを取得するために使用するメソッドを判断するカスタム仕様の列挙型変数が含まれています。デフォルトのフォーカスを判断するために固定の非動的メソッドを使用するほとんどのメニューについても、同じような実装が推奨されます。
トリガーする入力アクションがアクティベートされた際に変更する
アクション バインディング用に FBindUIActionArgs
を作成する際に、FBindUIActionArgs::KeyEvent
をイベントをトリガーするアクションのタイプに設定します。たとえば IE_Released
などとします。
CommonUI コンソール変数のリファレンス
CommonUI の機能を設定したり、デバッグ情報を取得したりする際は、次のコンソール変数の表を参考にしてください。
CVar | 説明 |
---|---|
CommonUI.bDumpInputTypeChangeCallstack | true に設定すると、入力のタイプが変更された場合に CommonUI によってコール スタックがダンプされます。これは、入力のタイプが頻繁に変更されるように見える場合のデバッグに役立ちます。 |
CommonInput.ShowKeys | 現在の入力デバイスのキーの表示/非表示を切り替えます。 |
CommonInput.EnableGamepadPlatformCursor | ゲームパッドでの入力時にカーソルを有効にするかどうかを切り替えます。 |
UseTransparentButtonStyleAsDefault | true に設定すると、CommonButtonBase にある SButton のデフォルトの Button Style が、バックグラウンドが透明でパディングのない NoBorder に設定されます。 |
Mobile.EnableUITextScaling | モバイル UI テキスト スケーリングが有効になります。 |
ActionBar.IgnoreOptOut | true に設定すると、バインディングが設定されているかどうかにかかわらず、Bound Action Bar によってバインディングが表示されます。 |
CommonUI.AlwaysShowCursor | true に設定すると、現在の入力コンフィグにかかわらず、CommonUI によって常にマウス カーソルが表示されます。 |
CommonUI.VideoPlayer.PreviewStepSize | CommonVideoPlayer のタイム ステップのサイズです。 |