Pengontrol navigasi UI

Halaman ini menjelaskan dasar-dasar pemrograman untuk perangkat navigasi UI menggunakan Windows.Gaming.Input.UINavigationController dan API terkait untuk Platform Windows Universal (UWP).

Dengan membaca halaman ini, Anda akan mempelajari:

• Cara mengumpulkan daftar perangkat navigasi antarmuka pengguna yang terhubung dan penggunanya
• Cara mendeteksi bahwa perangkat navigasi telah ditambahkan atau dihapus
• Cara membaca input dari satu atau beberapa perangkat navigasi UI
• Bagaimana gamepad dan tongkat arkade berulah sebagai perangkat navigasi

Gambaran umum pengontrol navigasi UI

Hampir semua game memiliki setidaknya beberapa antarmuka pengguna yang terpisah dari gameplay, bahkan jika hanya menu pregame atau dialog dalam game. Pemain harus dapat menavigasi UI ini menggunakan perangkat input mana pun yang mereka pilih, tetapi membebani pengembang untuk menambahkan dukungan khusus untuk setiap jenis perangkat input dan juga dapat memperkenalkan inkonsistensi antara game dan perangkat input yang membingungkan pemain. Untuk alasan ini, API UINavigationController dibuat.

Pengontrol navigasi UI adalah perangkat input logis yang ada untuk menyediakan kosakata perintah Navigasi UI umum yang dapat didukung oleh berbagai perangkat input fisik . Pengontrol navigasi UI hanyalah cara yang berbeda untuk melihat perangkat input fisik; kami menggunakan perangkat navigasi untuk merujuk ke perangkat input fisik apa pun yang dilihat sebagai pengontrol navigasi. Dengan memprogram perangkat navigasi daripada perangkat input tertentu, pengembang menghindari beban mendukung perangkat input yang berbeda dan mencapai konsistensi secara default.

Karena jumlah dan berbagai kontrol yang didukung oleh setiap jenis perangkat input bisa sangat berbeda dan karena perangkat input tertentu mungkin ingin mendukung serangkaian perintah navigasi yang lebih kaya, antarmuka pengontrol navigasi membagi kosakata perintah menjadi set yang diperlukan yang berisi perintah yang paling umum dan penting, dan set opsional yang berisi perintah yang nyaman tetapi tidak penting. Semua perangkat navigasi mendukung setiap perintah dalam set yang diperlukan dan dapat mendukung semua, beberapa, atau tidak ada perintah dalam set opsional.

Set yang diperlukan

Perangkat navigasi harus mendukung semua perintah navigasi dalam set yang diperlukan; ini adalah perintah arah (atas, bawah, kiri, dan kanan), lihat, menu, terima, dan batalkan perintah.

Perintah arah ditujukan untuk navigasi fokus XY utama antara elemen UI tunggal. Perintah tampilan dan menu ditujukan untuk menampilkan informasi gameplay (sering kali sesaat, kadang-kadang modal) dan untuk beralih antara konteks gameplay dan menu. Perintah terima dan batalkan masing-masing ditujukan untuk respons afirmatif (ya) dan negatif (tidak).

Tabel berikut ini meringkas perintah ini dan penggunaan yang dimaksudkan, dengan contoh. | Perintah | Penggunaan yang dimaksudkan | -------:| --------------- | Naik | Navigasi fokus XY ke atas | Turun | Navigasi fokus XY ke bawah | Kiri | Navigasi fokus XY ke kiri | Kanan | Navigasi fokus XY ke kanan | Lihat | Menampilkan info gameplay (papan skor, statistik permainan, tujuan, peta dunia atau area) | Menu | Menu utama / Jeda (pengaturan, status, peralatan, inventaris, jeda) | Terima | Respons afirmatif (terima, lanjutkan, konfirmasi, mulai, ya) | Batalkan | Respons negatif (tolak, balik, tolak, hentikan, tidak)

Set opsional

Perangkat navigasi juga dapat mendukung semua, beberapa, atau tidak ada perintah navigasi dalam set opsional; ini adalah perintah halaman (atas, bawah, kiri, dan kanan), menggulir (atas, bawah, kiri, dan kanan), dan perintah kontekstual (konteks 1-4).

Perintah kontekstual secara eksplisit ditujukan untuk perintah khusus aplikasi dan pintasan navigasi. Perintah halaman dan pengguliran ditujukan untuk navigasi cepat antara halaman atau grup elemen UI dan untuk navigasi menenangkan dalam elemen UI.

Tabel berikut ini meringkas perintah ini dan penggunaan yang dimaksudkan. | Perintah | Penggunaan yang dimaksudkan | -----------:| ------------ | PageUp | Lompat ke atas (ke halaman atau grup vertikal atas/sebelumnya) | PageDown | Lompat ke bawah (ke halaman atau grup vertikal bawah/berikutnya) | PageLeft | Lompat ke kiri (ke kiri/halaman horizontal atau grup sebelumnya) | PageRight | Lompat ke kanan (ke kanan/berikutnya halaman atau grup horizontal) | ScrollUp | Gulir ke atas (dalam elemen UI yang berfokus atau grup yang dapat digulir) | Gulir Ke Bawah | Gulir ke bawah (dalam elemen UI yang berfokus atau grup yang dapat digulir) | ScrollLeft | Gulir ke kiri (dalam elemen UI yang berfokus atau grup yang dapat digulir) | ScrollRight | Gulir ke kanan (dalam elemen UI terfokus atau grup yang dapat digulir) | Konteks1 | Tindakan konteks utama | Konteks2 | Tindakan konteks sekunder | Konteks3 | Tindakan konteks ketiga | Konteks4 | Tindakan konteks keempat

Catatan Meskipun game bebas merespons perintah apa pun dengan fungsi aktual yang berbeda dari penggunaan yang dimaksudkan, perilaku mengejutkan harus dihindari. Secara khusus, jangan mengubah fungsi aktual perintah jika Anda memerlukan penggunaan yang dimaksudkan, coba tetapkan fungsi baru ke perintah yang paling masuk akal, dan tetapkan fungsi mitra ke perintah mitra seperti PageUp/PageDown. Terakhir, pertimbangkan perintah mana yang didukung oleh setiap jenis perangkat input dan kontrol mana yang dipetakan, memastikan bahwa perintah penting dapat diakses dari setiap perangkat.

Gamepad, tongkat arkade, dan navigasi roda balap

Semua perangkat input yang didukung oleh namespace layanan Windows.Gaming.Input adalah perangkat navigasi UI.

Tabel berikut ini meringkas bagaimana kumpulan perintah navigasi yang diperlukan dipetakan ke berbagai perangkat input.

Perintah navigasi	Input gamepad	Input tongkat arkade	Input Racing Wheel
Naik	Jempol kiri ke atas/D-pad ke atas	Tetap di atas	D-pad ke atas
Tidak berfungsi	Thumbstick kiri ke bawah/ D-pad ke bawah	Tetap di bawah	D-pad ke bawah
Left	Thumbstick kiri/ D-pad kiri	Lengket ke kiri	D-pad kiri
Right	Thumbstick kiri kanan/ D-pad kanan	Lengket ke kanan	D-pad kanan
Tampilan	Tombol Tampilan	Tombol Tampilan	Tombol Tampilan
Menu	Tombol Menu	Tombol Menu	Tombol Menu
Terima	Tombol	Tombol Tindakan 1	Tombol
Batalkan	Tombol B	Tombol Tindakan 2	Tombol B

Tabel berikut ini meringkas bagaimana sekumpulan perintah navigasi opsional dipetakan ke berbagai perangkat input.

Perintah navigasi	Input gamepad	Input tongkat arkade	Input Racing Wheel
PageUp	Pemicu kiri	tidak didukung	Bervariasi
PageDown	Pemicu yang tepat	tidak didukung	Bervariasi
PageLeft	Bumper kiri	tidak didukung	Bervariasi
PageRight	Bumper kanan	tidak didukung	Bervariasi
Gulir Ke	Jempol kanan ke atas	tidak didukung	Bervariasi
Gulir Ke Bawah	Thumbstick kanan ke bawah	tidak didukung	Bervariasi
ScrollLeft	Thumbstick kanan kiri	tidak didukung	Bervariasi
ScrollRight	Thumbstick kanan	tidak didukung	Bervariasi
Konteks1	Tombol X	tidak didukung	Tombol X (umumnya)
Konteks2	Tombol Y	tidak didukung	Tombol Y (umumnya)
Konteks3	Tekan thumbstick kiri	tidak didukung	Bervariasi
Konteks4	Tekan thumbstick kanan	tidak didukung	Bervariasi

Mendeteksi dan melacak pengontrol navigasi UI

Meskipun pengontrol navigasi UI adalah perangkat input logis, pengontrol tersebut adalah representasi dari perangkat fisik dan dikelola oleh sistem dengan cara yang sama. Anda tidak perlu membuat atau menginisialisasinya; sistem menyediakan daftar pengontrol navigasi UI yang terhubung dan peristiwa untuk memberi tahu Anda ketika pengontrol Navigasi UI ditambahkan atau dihapus.

Daftar pengontrol navigasi UI

Kelas UINavigationController menyediakan properti statis, UINavigationControllers, yang merupakan daftar baca-saja perangkat navigasi UI yang saat ini terhubung. Karena Anda mungkin hanya tertarik pada beberapa perangkat navigasi yang terhubung, sebaiknya Anda mempertahankan koleksi Anda sendiri alih-alih mengaksesnya melalui UINavigationControllers properti .

Contoh berikut menyalin semua pengontrol navigasi UI yang tersambung ke dalam koleksi baru.

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);
}

Menambahkan dan menghapus pengontrol navigasi UI

Ketika pengontrol navigasi UI ditambahkan atau dihapus UINavigationControllerAdded dan peristiwa UINavigationControllerRemoved dinaikkan . Anda dapat mendaftarkan penanganan aktivitas untuk peristiwa ini untuk melacak perangkat navigasi yang saat ini terhubung.

Contoh berikut mulai melacak perangkat navigasi UI yang telah ditambahkan.

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);
}

Contoh berikut berhenti melacak tongkat arkade yang telah dihapus.

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

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

Pengguna dan headset

Setiap perangkat navigasi dapat dikaitkan dengan akun pengguna untuk menautkan identitas mereka ke input mereka, dan dapat memiliki headset yang terpasang untuk memfasilitasi fitur obrolan suara atau navigasi. Untuk mempelajari selengkapnya tentang bekerja dengan pengguna dan headset, lihat Melacak pengguna dan perangkat dan Headset mereka.

Membaca pengontrol navigasi UI

Setelah mengidentifikasi perangkat navigasi UI yang Anda minati, Anda siap untuk mengumpulkan input dari perangkat tersebut. Namun, tidak seperti beberapa jenis input lain yang mungkin biasa Anda gunakan, perangkat navigasi tidak berkomunikasi perubahan status dengan menaikkan peristiwa. Sebagai gantinya, Anda mengambil pembacaan rutin tentang status mereka saat ini dengan polling mereka.

Polling pengontrol navigasi UI

Polling menangkap rekam jepret perangkat navigasi pada titik waktu yang tepat. Pendekatan pengumpulan input ini cocok untuk sebagian besar game karena logika mereka biasanya berjalan dalam perulangan deterministik daripada digerakkan oleh peristiwa; biasanya juga lebih sederhana untuk menginterpretasikan perintah permainan dari input yang dikumpulkan sekaligus daripada dari banyak input tunggal yang dikumpulkan dari waktu ke waktu.

Anda melakukan polling perangkat navigasi dengan memanggil UINavigationController.GetCurrentReading; fungsi ini mengembalikan UINavigationReading yang berisi status perangkat navigasi.

auto navigationController = myNavigationControllers[0];

UINavigationReading reading = navigationController->GetCurrentReading();

Membaca tombol

Setiap tombol navigasi UI menyediakan pembacaan boolean yang sesuai dengan apakah tombol ditekan (turun), atau dilepaskan (ke atas). Untuk efisiensi, pembacaan tombol tidak direpresentasikan sebagai nilai boolean individual; sebaliknya mereka semua dikemas ke dalam salah satu dari dua ladang bit yang diwakili oleh enumerasi RequiredUINavigationButtons dan OptionalUINavigationButtons .

Tombol milik set yang diperlukan dibaca dari RequiredButtons properti struktur UINavigationReading ; tombol milik set opsional dibaca dari OptionalButtons properti . Karena properti ini adalah bitfield, masking bitwise digunakan untuk mengisolasi nilai tombol yang Anda minati. Tombol ditekan (ke bawah) ketika bit yang sesuai diatur; jika tidak, dirilis (naik).

Contoh berikut menentukan apakah tombol Terima dalam set yang diperlukan ditekan.

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

Contoh berikut menentukan apakah tombol Terima dalam set yang diperlukan dirilis.

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

Pastikan untuk menggunakan OptionalButtons properti dan OptionalUINavigationButtons enumerasi saat membaca tombol dalam set opsional.

Contoh berikut menentukan apakah tombol Konteks 1 dalam set opsional ditekan.

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

Terkadang Anda mungkin ingin menentukan kapan tombol beralih dari ditekan ke dilepaskan atau dilepaskan untuk ditekan, apakah beberapa tombol ditekan atau dilepaskan, atau jika sekumpulan tombol disusun dengan cara tertentu--beberapa ditekan, beberapa tidak. Untuk informasi tentang cara mendeteksi kondisi ini, lihat Mendeteksi transisi tombol dan Mendeteksi pengaturan tombol yang kompleks.

Jalankan sampel pengontrol navigasi UI

Sampel InputInterfacingUWP (github) menunjukkan bagaimana perangkat input yang berbeda berulah sebagai pengontrol navigasi UI.

Lihat juga

Windows.Gaming.Input.GamepadWindows.Gaming.Input.ArcadeStickWindows.Gaming.Input.RacingWheelWindows.Gaming.Input.IGameController