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 UI 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 ber perilaku sebagai perangkat navigasi
Gambaran umum pengontrol navigasi UI
Hampir semua game memiliki setidaknya beberapa antarmuka pengguna yang terpisah dari gameplay, bahkan jika itu 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 , UINavigationController API 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 pemrograman terhadap perangkat navigasi daripada perangkat input tertentu, pengembang menghindari beban mendukung perangkat input yang berbeda dan mencapai konsistensi secara default.
Karena jumlah dan variasi 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 gameplay dan konteks menu, masing-masing. Perintah terima dan batal 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 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, inventarsi, jeda) | Terima | Respons afirmatif (terima, lanjutkan, konfirmasi, mulai, ya) | Batal | 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 kontekstual (konteks 1-4).
Perintah kontekstual secara eksplisit ditujukan untuk perintah khusus aplikasi dan pintasan navigasi. Perintah paging dan scrolling ditujukan untuk navigasi cepat antara halaman atau grup elemen UI dan untuk navigasi halus dalam elemen UI.
Tabel berikut ini meringkas perintah ini dan penggunaan yang dimaksudkan. | Perintah | Penggunaan yang dimaksudkan | -----------:| ------------ | PageUp | Melompat ke atas (ke halaman atau grup vertikal atas/sebelumnya) | PageDown | Melompat ke bawah (ke halaman atau grup vertikal bawah/berikutnya) | PageLeft | Melompat ke kiri (ke kiri/halaman atau grup horizontal sebelumnya) | PageRight | Melompat ke kanan (ke kanan/halaman atau grup horizontal berikutnya) | ScrollUp | Gulir ke atas (dalam elemen UI yang berfokus atau grup yang dapat digulirkan) | Gulir Ke Bawah | Gulir ke bawah (dalam elemen UI terfokus atau grup yang dapat digulirkan) | ScrollLeft | Gulir ke kiri (dalam elemen UI yang berfokus atau grup yang dapat digulirkan) | ScrollRight | Gulir ke kanan (dalam elemen UI terfokus atau grup yang dapat digulirkan) | 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 ubah 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 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 |
|---|---|---|---|
| Tombol atas | 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 | Tempelkan ke bawah | D-pad ke bawah |
| Left | Kiri thumbstick kiri / D-pad kiri | Lengket ke kiri | D-pad kiri |
| Hak | 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 kumpulan 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 kanan | tidak didukung | Bervariasi |
| PageLeft | Bumper kiri | tidak didukung | Bervariasi |
| PageRight | Bumper kanan | tidak didukung | Bervariasi |
| ScrollUp | 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 antarmuka pengguna dan peristiwa yang terhubung 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 Pertahankan 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 tersambung.
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 serta perangkat dan Headset mereka.
Membaca pengontrol navigasi UI
Setelah mengidentifikasi perangkat navigasi UI yang Anda minati, Anda siap untuk mengumpulkan input darinya. Namun, tidak seperti beberapa jenis input lain yang mungkin biasa Anda gunakan, perangkat navigasi tidak mengkomunikasikan perubahan status dengan menaikkan peristiwa. Sebagai gantinya, Anda mengambil pembacaan rutin tentang status mereka saat ini dengan melakukan polling .
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 didorong oleh peristiwa; biasanya juga lebih sederhana untuk menafsirkan 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 bitfield 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 bitfields, 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 satu set tombol diatur 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 berperilaku sebagai pengontrol navigasi UI.
Lihat juga
Windows.Gaming.Input.GamepadWindows.Gaming.Input.ArcadeStickWindows.Gaming.Input.RacingWheelWindows.Gaming.Input.IGameController
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk