UI ナビゲーション コントローラーUI navigation controller

このページでは、Windows.Gaming.Input.UINavigationController とユニバーサル Windows プラットフォーム (UWP) 用の関連 API を使った UI ナビゲーション デバイス向けプログラミングの基礎について説明します。This page describes the basics of programming for UI navigation devices using Windows.Gaming.Input.UINavigationController and related APIs for the Universal Windows Platform (UWP).

ここでは、次の項目について紹介します。By reading this page, you'll learn:

  • 接続されている UI ナビゲーション デバイスとそのユーザーの一覧を収集する方法How to gather a list of connected UI navigation devices and their users
  • ナビゲーション デバイスが追加または削除されたことを検出する方法How to detect that a navigation device has been added or removed
  • 1 つ以上の UI ナビゲーション デバイスの入力を読み取る方法How to read input from one or more UI navigation devices
  • ゲームパッドやアーケード スティックがナビゲーション デバイスとして動作するしくみHow gamepads and arcade sticks behave as navigation devices

UI ナビゲーション コントローラーの概要UI navigation controller overview

それが単なるゲーム開始前のメニューであれ、ゲーム内のダイアログであれ、ほぼすべてのゲームに、ゲームプレイと切り離されたユーザー インターフェイスが少なくとも何かしらは用意されています。Almost all games have at least some user interface that's separate from gameplay, even if its just pregame menus or in-game dialogs. プレイヤーは、どのような入力デバイスを選んでも、その入力デバイスを使ってこのような UI を操作できる必要があります。しかし、各種入力デバイス固有のサポートを追加することは開発者にとって負担になります。また、それによりゲームと入力デバイス間で不整合が生じ、プレイヤーの混乱を招く可能性もあります。Players need to be able to navigate this UI using whichever input device they've chosen, but it burdens developers to add specific support for each kind of input device and can also introduce inconsistencies between games and input devices that confuse players. こうした理由から、UINavigationController API が作成されました。For these reasons the UINavigationController API was created.

UI ナビゲーション コントローラーは_論理_入力デバイスであり、さまざまな_物理_入力デバイスでサポートできる一般的な UI ナビゲーション コマンドのボキャブラリを提供するために存在しています。UI navigation controllers are logical input devices that exist to provide a vocabulary of common UI Navigation commands that can be supported by a variety of physical input devices. _UI ナビゲーション コントローラー_は物理入力デバイスを確認する別の方法に過ぎません。ナビゲーション コントローラーとして表示されている任意の物理入力デバイスを参照するには_ナビゲーション デバイス_を使用します。A UI navigation controller is just a different way of looking at a physical input device; we use navigation device to refer to any physical input device being viewed as a navigation controller. 特定の入力デバイスではなく、ナビゲーション デバイスを対象にプログラミングすることで、開発者はさまざまな入力デバイスをサポートする負担を回避しながら既定の状態で整合性を実現できます。By programming against a navigation device rather than specific input devices, developers avoid the burden of supporting different input devices and achieve consistency by default.

各種入力デバイスでサポートされているコントロールの数と種類は大きく異なる可能性があり、特定の入力デバイスではナビゲーション コマンドをさらに豊富にサポートすることが推奨されるため、ナビゲーション コントローラー インターフェイスではコマンドのボキャブラリを、最も一般的で不可欠なコマンドを含む_必須セット_と、便利だが不可欠ではないコマンドを含む_オプション セット_に分けています。Because the number and variety of controls supported by each kind of input device can be so different and because certain input devices might want to support a richer set of navigation commands, the navigation controller interface divides the vocabulary of commands into a required set containing the most common and essential commands, and an optional set containing convenient but nonessential commands. ナビゲーション デバイスはいずれも_必須セット_のすべてのコマンドをサポートしていますが、_オプション セット_については、そのコマンドをすべてサポートしている場合もあれば、その一部だけをサポートしている場合もあり、まったくサポートしていない場合もあります。All navigation devices support every command in the required set and may support all, some, or none of the commands in the optional set.

必須セットRequired set

ナビゲーション デバイスは_必須セット_内のナビゲーション コマンドをすべてサポートする必要があります。これには、方向 (UP、Down、Left、Right)、View、Menu、Accept、および Cancel のコマンドが該当します。Navigation devices must support all navigation commands in the required set; these are the directional (up, down, left, and right), view, menu, accept, and cancel commands.

方向コマンドは、単一の UI 要素間におけるプライマリ XY フォーカス ナビゲーションを目的としています。The directional commands are intended for primary XY-focus navigation between single UI elements. View コマンドおよび Menu コマンドは、ゲームプレイ情報を (多くの場合は一時的に、場合によってはモーダルに) 表示することと、ゲームプレイとメニューのコンテキストを切り替えることをそれぞれ目的としています。The view and menu commands are intended for displaying gameplay information (often momentary, sometimes modally) and for switching between gameplay and menu contexts, respectively. Accept および Cancel コマンドは、肯定的 (はい) および否定的 (いいえ) に応答することをそれぞれ意図しています。The accept and cancel commands are intended for affirmative (yes) and negative (no) responses, respectively.

次の表は、これらのコマンドとその使用目的を例と共にまとめたものです。The following table summarizes these commands and their intended uses, with examples. | コマンドCommand | 使用目的Intended use | -------:| --------------- | UpUp | XY フォーカス ナビゲーションの上XY-focus navigation up | DownDown | XY フォーカス ナビゲーションの下XY-focus navigation down | LeftLeft | XY フォーカス ナビゲーションの左XY-focus navigation left | Right | XY フォーカス ナビゲーションの右XY-focus navigation right | ビューView | ゲームプレイの情報を表示 (スコアボード、ゲーム統計、目標、世界やマップ領域)Display gameplay info (scoreboard, game stats, objectives, world or area map) | MenuMenu | プライマリ メニューまたは一時停止 (設定、状態、装備、道具、一時停止)Primary menu / Pause (settings, status, equipment, inventory, pause) | OKAccept | 肯定的な応答 (同意する、進む、確認する、開始する、はい)Affirmative response (accept, advance, confirm, start, yes) | CancelCancel | 否定的な応答 (拒否する、後退する、断る、停止する、いいえ)Negative response (reject, reverse, decline, stop, no)

オプション セットOptional set

ナビゲーション デバイスは、_オプション セット_のナビゲーション コマンドをすべてサポートする場合あれば、一部のみサポートしたり、まったくサポートしなかったりする場合もあります。これらには、ページング (上、下、左、および右)、スクロール (上、下、左、および右)、コンテキスト依存 (コンテキスト 1 ~ 4) のコマンドが該当します。Navigation devices may also support all, some, or none of the navigation commands in the optional set; these are the paging (up, down, left, and right), scrolling (up, down, left, and right), and contextual (context 1-4) commands.

コンテキスト依存のコマンドは、アプリケーション固有のコマンドやナビゲーション ショートカットとしての使用を明確に意図しています。The contextual commands are explicitly intended for application-specific commands and navigation shortcuts. ページング コマンドとスクロール コマンドは、UI 要素のページやグループ間ですばやく移動することと、UI 要素内で細かく移動することをそれぞれ目的としています。The paging and scrolling commands are intended for quick navigation between pages or groups of UI elements and for fine-grained navigation within UI elements, respectively.

次の表は、これらのコマンドとその使用目的をまとめたものです。The following table summarizes these commands and their intended uses. | コマンドCommand | 使用目的Intended use | -----------:| ------------ | PageUpPageUp | 上方向にジャンプ (上側または垂直方向の前のページやグループに対して)Jump upward (to upper/previous vertical page or group) | PageDownPageDown | 下方向にジャンプ (下側または垂直方向の次のページやグループに対して)Jump downward (to lower/next vertical page or group) | PageLeftPageLeft | 左方向にジャンプ (左側または水平方向の前のページやグループに対して)Jump left (to leftward/previous horizontal page or group) | PageRightPageRight | 右方向にジャンプ (右側または水平方向の次のページやグループに対して)Jump right (to rightward/next horizontal page or group) | ScrollUpScrollUp | 上方向にスクロール (フォーカスが置かれた UI 要素またはスクロール可能なグループ内)Scroll up (within focused UI element or scrollable group) | ScrollDownScrollDown | 下方向にスクロール (フォーカスが置かれた UI 要素またはスクロール可能なグループ内)Scroll down (within focused UI element or scrollable group) | ScrollLeftScrollLeft | 左方向にスクロール (フォーカスが置かれた UI 要素またはスクロール可能なグループ内)Scroll left (within focused UI element or scrollable group) | ScrollRightScrollRight | 右方向にスクロール (フォーカスが置かれた UI 要素またはスクロール可能なグループ内)Scroll right (within focused UI element or scrollable group) | Context1Context1 | 最初のコンテキスト アクションPrimary context action | Context2Context2 | 2 番目のコンテキスト アクションSecondary context action | Context3Context3 | 3 番目のコンテキスト アクションThird context action | Context4Context4 | 4 番目のコンテキスト アクションFourth context action

注: ゲームは、実際の機能が使用目的と異なっているコマンドに対して自由に応答できますが、予期しない動作は避ける必要があります。Note Although a game is free to respond to any command with an actual function that is different than its intended use, surprising behavior should be avoided. 特に、目的の用途を必要とする場合はコマンドの実際の機能を変更しないでください。また、斬新な機能は最も合理的なコマンドに割り当てるようにして、対を成す機能は PageUp/PageDown のような対を成すコマンドに割り当てるようにしてください。In particular, don't change the actual function of a command if you need its intended use, try to assign novel functions to the command that makes the most sense, and assign counterpart functions to counterpart commands such as PageUp/PageDown. 最後に、各種入力デバイスでどのコマンドがサポートされ、そうしたコマンドがどのコントロールにマッピングされるかを考慮して、どのデバイスからでも重要なコマンドにアクセスできるようにしてください。Finally, consider which commands are supported by each kind of input device and which controls they are mapped to, making sure that critical commands are accessible from every device.

ゲームパッド、アーケード スティック、およびレース ホイールのナビゲーションGamepad, arcade stick, and racing wheel navigation

Windows.Gaming.Input 名前空間でサポートされている入力デバイスはすべて UI ナビゲーション デバイスです。All input devices supported by the Windows.Gaming.Input namespace are UI navigation devices.

次の表は、_必須セット_のナビゲーション コマンドをさまざまな入力デバイスにマッピングする方法をまとめたものです。The following table summarizes how the required set of navigation commands map to various input devices.

ナビゲーション コマンドNavigation command ゲームパッド入力Gamepad input アーケード スティック入力Arcade stick input レース ホイール入力Racing Wheel input
UpUp 左スティックを上/方向パッドを上Left thumbstick up / D-pad up スティックを上Stick up 方向パッドを上D-pad up
DownDown 左スティックを下/方向パッドを下Left thumbstick down / D-pad down スティックを下Stick down 方向パッドを下D-pad down
LeftLeft 左スティックを左/方向パッドを左Left thumbstick left / D-pad left スティックを左Stick left 方向パッドを左D-pad left
Right 左スティックを右/方向パッドを右Left thumbstick right / D-pad right スティックを右Stick right 方向パッドを右D-pad right
ビューView 表示ボタンView button 表示ボタンView button 表示ボタンView button
MenuMenu メニュー ボタンMenu button メニュー ボタンMenu button メニュー ボタンMenu button
OKAccept A ボタンA button アクション 1 ボタンAction 1 button A ボタンA button
CancelCancel B ボタンB button アクション 2 ボタンAction 2 button B ボタンB button

次の表は、_オプション セット_のナビゲーション コマンドをさまざまな入力デバイスにマッピングする方法をまとめたものです。The following table summarizes how the optional set of navigation commands map to various input devices.

ナビゲーション コマンドNavigation command ゲームパッド入力Gamepad input アーケード スティック入力Arcade stick input レース ホイール入力Racing Wheel input
PageUpPageUp 左トリガーLeft trigger サポートされていませんnot supported 異なりますvaries
PageDownPageDown 右トリガーRight trigger サポートされていませんnot supported 異なりますvaries
PageLeftPageLeft L ボタンLeft bumper サポートされていませんnot supported 異なりますvaries
PageRightPageRight R ボタンRight bumper サポートされていませんnot supported 異なりますvaries
ScrollUpScrollUp 右スティックを上Right thumbstick up サポートされていませんnot supported 異なりますvaries
ScrollDownScrollDown 右スティックを下Right thumbstick down サポートされていませんnot supported 異なりますvaries
ScrollLeftScrollLeft 右スティックを左Right thumbstick left サポートされていませんnot supported 異なりますvaries
ScrollRightScrollRight 右スティックを右Right thumbstick right サポートされていませんnot supported 異なりますvaries
Context1Context1 X ボタンX button サポートされていませんnot supported X ボタン (一般的な場合)X button (commonly)
Context2Context2 Y ボタンY button サポートされていませんnot supported Y ボタン (一般的な場合)Y button (commonly)
Context3Context3 左スティックを押すLeft thumbstick press サポートされていませんnot supported 異なりますvaries
Context4Context4 右スティックを押すRight thumbstick press サポートされていませんnot supported 異なりますvaries

UI ナビゲーション コントローラーの検出と追跡Detect and track UI navigation controllers

UI ナビゲーション コントローラーは論理入力デバイスですが、これらは物理デバイスを表しており、物理デバイスと同じようにシステムで管理されます。Although UI navigation controllers are logical input devices, they are a representation of a physical device and are managed by the system in the same way. UI ナビゲーション コントローラーを自分で作成したり初期化したりする必要はありません。接続されている UI ナビゲーション コントローラーとイベントの一覧はシステムによって提供され、ナビゲーション コントローラーが追加または削除されると通知されます。You don't have to create or initialize them; the system provides a list of connected UI navigation controllers and events to notify you when a UI Navigation controller is added or removed.

UI ナビゲーション コントローラーの一覧The UI navigation controllers list

UINavigationController クラスには静的プロパティである UINavigationControllers が用意されています。これは、現在接続されている UI ナビゲーション デバイスの読み取り専用リストです。The UINavigationController class provides a static property, UINavigationControllers, which is a read-only list of UI navigation devices that are currently connected. 接続されているナビゲーション デバイスの一部にのみ関心を持つ場合もあるため、UINavigationControllers プロパティを利用してデバイスにアクセスするのではなく、独自のコレクションを保持しておくことをお勧めします。Because you might only be interested in some of the connected navigation devices, its recommended that you maintain your own collection instead of accessing them through the UINavigationControllers property.

次の例では、接続されているすべての UI ナビゲーション コントローラーを新しいコレクションにコピーします。The following example copies all connected UI navigation controllers into a new collection.

auto myNavigationControllers = ref new Vector<UINavigationController^>();

for (auto device : UINavigationController::UINavigationControllers)
{
    // This code assumes that you're interested in all navigation controllers.
    myNavigationControllers->Append(device);
}

UI ナビゲーション コントローラーの追加と削除Adding and removing UI navigation controllers

UI ナビゲーション コントローラーが追加または削除されると、UINavigationControllerAdded イベントおよび UINavigationControllerRemoved イベントが発生します。When a UI navigation controller is added or removed the UINavigationControllerAdded and UINavigationControllerRemoved events are raised. これらのイベントのイベント ハンドラーを登録することで、現在接続されているナビゲーション デバイスを追跡できます。You can register an event handler for these events to keep track of the navigation devices that are currently connected.

次の例では、追加された UI ナビゲーション デバイスの追跡を開始します。The following example starts tracking a UI navigation device that's been added.

UINavigationController::UINavigationControllerAdded += ref new EventHandler<UINavigationController^>(Platform::Object^, UINavigationController^ args)
{
    // This code assumes that you're interested in all new navigation controllers.
    myNavigationControllers->Append(args);
}

次の例では、削除されたアーケード スティックの追跡を停止します。The following example stops tracking an arcade stick that's been removed.

UINavigationController::UINavigationControllerRemoved += ref new EventHandler<UINavigationController^>(Platform::Object^, UINavigationController^ args)
{
    unsigned int indexRemoved;

    if(myNavigationControllers->IndexOf(args, &indexRemoved))
    {
        myNavigationControllers->RemoveAt(indexRemoved);
    }
}

ユーザーとヘッドセットUsers and headsets

各ナビゲーション デバイスは、ユーザー アカウントと関連付けることでユーザーの ID をその入力にリンクできます。また、ボイス チャットやナビゲーションの機能を円滑化するためにヘッドセットをアタッチすることもできます。Each navigation device can be associated with a user account to link their identity to their input, and can have a headset attached to facilitate voice chat or navigation features. ユーザーとの連携およびヘッドセット操作について詳しくは、ユーザーおよびそのデバイスの追跡と、ヘッドセットに関するページをご覧ください。To learn more about working with users and headsets, see Tracking users and their devices and Headset.

UI ナビゲーション コントローラーの読み取りReading the UI navigation controller

関心のある UI ナビゲーション デバイスを特定したら、その入力を収集する準備ができました。After you identify the UI navigation device that you're interested in, you're ready to gather input from it. ただし、なじみのある一部の他の種類の入力とは違い、ナビゲーション デバイスはイベントを発生することによって状態の変化を伝えるわけではありません。However, unlike some other kinds of input that you might be used to, navigation devices don't communicate state-change by raising events. 代わりに、イベントを_ポーリング_することで現在の状態を定期的に読み取ります。Instead, you take regular readings of their current state by polling them.

UI ナビゲーション コントローラーのポーリングPolling the UI navigation controller

ポーリングでは、明確な時点におけるナビゲーション デバイスのスナップショットをキャプチャします。Polling captures a snapshot of the navigation device at a precise point in time. 入力を収集するこのアプローチはほとんどのゲームに最適です。ゲームのロジックはイベント駆動型ではなく、確定的なループの中で実行されることが一般的なためです。また通常は、徐々に集めた多数の単一の入力によるコマンドを解釈するより、一度に集めた入力によるゲーム コマンドを解釈する方が簡単になります。This approach to input gathering is a good fit for most games because their logic typically runs in a deterministic loop rather than being event-driven; its also typically simpler to interpret game commands from input gathered all at once than it is from many single inputs gathered over time.

ナビゲーション デバイスをポーリングするには、UINavigationController.GetCurrentReading を呼び出します。この関数はナビゲーション デバイスの状態が格納された UINavigationReading を返します。You poll a navigation device by calling UINavigationController.GetCurrentReading; this function returns a UINavigationReading that contains the state of the navigation device.

auto navigationController = myNavigationControllers[0];

UINavigationReading reading = navigationController->GetCurrentReading();

ボタンの読み取りReading the buttons

各 UI ナビゲーション ボタンは、ボタンが押されているか (ダウン)、離されているか (アップ) に対応するブール型の読み取り値を渡します。Each of the UI navigation buttons provide a boolean reading that corresponds to whether its pressed (down), or released (up). 効率を上げるために、ボタンの読み取り値は個々のブール値としては表されません。代わりに、読み取り値はすべて、RequiredUINavigationButtons 列挙型および OptionalUINavigationButtons 列挙型で表される 2 つのビットフィールドのいずれかにパックされます。For efficiency, button readings aren't represented as individual boolean values; instead they're all packed into one of two bitfields represented by the RequiredUINavigationButtons and OptionalUINavigationButtons enumerations.

_必須セット_に属するボタンは UINavigationReading 構造体の RequiredButtons プロパティから読み取ります。_オプション セット_に属するボタンは OptionalButtons から読み取ります。The buttons belonging to the required set are read from the RequiredButtons property of the UINavigationReading structure; the buttons belonging to the optional set are read from the OptionalButtons property. これらのプロパティはビットフィールドであるため、ビット演算子マスクを使用して目的のボタンの値を分離します。Because these properties are bitfields, bitwise masking is used to isolate the value of the button that you're interested in. 対応するビットが設定されているときはボタンが押されており (ダウン)、それ以外の場合はボタンが離されています (アップ)。The button is pressed (down) when the corresponding bit is set; otherwise its released (up).

次の例では、_必須セット_の Accept ボタンが押されているかどうかを判別します。The following example determines whether the Accept button in the required set is pressed.

if (RequiredUINavigationButtons::Accept == (reading.RequiredButtons & RequiredUINavigationButtons::Accept))
{
    // Accept is pressed
}

次の例では、_必須セット_の Accept ボタンが離されているかどうかを判別します。The following example determines whether the Accept button in the required set is released.

if (RequiredUINavigationButtons::None == (reading.RequiredButtons & RequiredUINavigationButtons::Accept))
{
    // Accept is released (not pressed)
}

_オプション セット_のボタンを読み取る場合は必ず OptionalButtons プロパティおよび OptionalUINavigationButtons 列挙型を使用してください。Be sure to use the OptionalButtons property and OptionalUINavigationButtons enumeration when reading buttons in the optional set.

次の例では、_オプション セット_の Context1 ボタンが押されているかどうかを判別します。The following example determines whether the Context 1 button in the optional set is pressed.

if (OptionalUINavigationButtons::Context1 == (reading.OptionalButtons & OptionalUINavigationButtons::Context1))
{
    // Context 1 is pressed
}

場合によっては、ボタンが押された状態から離された状態への移行またはその逆方向への移行のタイミング、複数のボタンが押されているか離されているかの状態、または一連のボタンが特定のパターンの状態になっているかどうか (一部が押されていて、一部が押されていない) を特定する必要があります。Sometimes you might want to determine when a button transitions from pressed to released or released to pressed, whether multiple buttons are pressed or released, or if a set of buttons are arranged in a particular way--some pressed, some not. これらの状態を検出する方法について詳しくは、「Detecting button transitions (ボタンの移行の検出)」および「Detecting complex button arrangements (複雑なボタンのパターンの検出)」をご覧ください。For information on how to detect these conditions, see Detecting button transitions and Detecting complex button arrangements.

UI ナビゲーション コントローラーのサンプルを実行Run the UI navigation controller sample

InputInterfacingUWP サンプル (GitHub) は、さまざまな入力デバイスが UI ナビゲーション コントローラーとしてどのように動作するかを示します。The InputInterfacingUWP sample (github) demonstrates how the different input devices behave as UI navigation controllers.

関連項目See also

Windows.Gaming.Input.Gamepad Windows.Gaming.Input.ArcadeStick Windows.Gaming.Input.RacingWheel Windows.Gaming.Input.IGameControllerWindows.Gaming.Input.Gamepad Windows.Gaming.Input.ArcadeStick Windows.Gaming.Input.RacingWheel Windows.Gaming.Input.IGameController