Controller per la navigazione dell'interfaccia utente

Questa pagina descrive le nozioni di base della programmazione per i dispositivi per la navigazione dell'interfaccia utente che utilizzano Windows.Gaming.Input.UINavigationController e le API correlate per la piattaforma UWP (Universal Windows Platform).

Leggendo questa pagina, si apprenderà quanto segue:

• Come raccogliere un elenco di dispositivi per la navigazione dell'interfaccia utente collegati e dei relativi utenti
• Come rilevare che un dispositivo per la navigazione è stato aggiunto o rimosso
• Come leggere l'input da uno o più dispositivi per la navigazione dell'interfaccia utente
• Come si comportano gamepad e levette Arcade come dispositivi per la navigazione

Panoramica dei controller per la navigazione dell'interfaccia utente

Quasi tutti i giochi hanno almeno un'interfaccia utente separata dal gameplay, anche se solo semplici menu pre-game o dialoghi in-game. I giocatori devono essere in grado di navigare in questa interfaccia utente mediante un qualsiasi dispositivo di input scelto; per questo motivo agli sviluppatori viene richiesto di aggiungere un supporto specifico per ogni tipo di dispositivo di input, con il rischio che potrebbero anche introdurre incoerenze tra giochi e dispositivi di input che confondono i giocatori. Per questi motivi è stata creata l'API UINavigationController.

I controller per la navigazione dell'interfaccia utente sono dispositivi di input logici che hanno lo scopo di fornire un vocabolario di comandi comuni per la navigazione dell'interfaccia utente e che possono essere supportati da una varietà di dispositivi di input fisici. Un controller per la navigazione dell'interfaccia utente è solo un modo diverso di vedere un dispositivo di input fisico. Utilizziamo un dispositivo di navigazione per fare riferimento a un qualsiasi dispositivo di input fisico visualizzato come controller di navigazione. Programmando in base a un dispositivo di navigazione generico anziché a dispositivi di input specifici, gli sviluppatori evitano il carico di supporto di dispositivi di input diversi e ottengono coerenza per impostazione predefinita.

Poiché il numero e la varietà di controlli supportati da ogni tipo di dispositivo di input possono essere molto diversi e poiché alcuni dispositivi di input potrebbero voler supportare una serie più completa di comandi di navigazione, l'interfaccia del controller di navigazione divide il vocabolario dei comandi in un set necessario contenente i comandi più comuni ed essenziali e un set opzionale contenente comandi pratici ma non essenziali. Tutti i dispositivi di navigazione supportano ogni comando nel set necessario e potrebbero supportare tutti, alcuni o nessuno dei comandi presenti nel set opzionale.

Set necessario

I dispositivi di navigazione devono supportare tutti i comandi di navigazione presenti nel set necessario. Si tratta dei comandi direzionali (su, giù, sinistra e destra), visualizza, menu, accetta e annulla.

I comandi direzionali sono destinati per la navigazione a focus XY primaria tra singoli elementi dell'interfaccia utente. I comandi visualizza e menu sono destinati a visualizzare informazioni sul gioco (spesso momentanee, a volte modali) e per passare rispettivamente tra gioco e contesti dei menu. I comandi accetta e annulla sono destinati rispettivamente alle risposte affermative (sì) e negative (no).

La tabella seguente riepiloga questi comandi e i relativi usi previsti, con esempi. | Comando | Uso previsto | -------:| --------------- | Su | Navigazione a focus XY verso l'alto | Giù | Navigazione a focus XY verso il basso | Sinistra | Navigazione a focus XY verso sinistra | Destra | Navigazione a focus XY verso destra | Visualizza | Visualizzazione delle informazioni di gioco (tabellone, statistiche del gioco, obiettivi, mappa del mondo o dell'area) | Menu | Menu principale/Pausa (impostazioni, stato, attrezzature, inventario, pausa) | Accetta | Risposta affermativa (accettare, avanzare, confermare, avvio, sì) | Annulla | Risposta negativa (rifiutare, retrocedere, declinare, arresto, no)

Set opzionale

I dispositivi di navigazione possono anche supportare tutti, alcuni o nessuno dei comandi di navigazione presenti nel set opzionale. Questi sono i comandi di paging (su, giù, sinistra e destra), scorrimento (su, giù, sinistra e destra) e contestuali (Context 1-4).

I comandi contestuali sono destinati in modo esplicito a comandi specifici dell'applicazione e a scorciatoie di navigazione. I comandi di paging e scorrimento sono destinati rispettivamente a una navigazione rapida tra pagine o gruppi di elementi dell'interfaccia utente e per la navigazione con granularità fine all'interno degli elementi dell'interfaccia utente.

La tabella seguente riepiloga questi comandi e i relativi usi previsti. | Comando | Uso previsto | -----------:| ------------ | PageUp | Salto verso l'alto (fino alla pagina o al gruppo verticale superiore/precedente) | PageDown | Salto verso il basso (fino alla pagina o al gruppo verticale inferiore/successivo) | PageLeft | Salto verso sinistra (fino alla pagina o al gruppo orizzontale a sinistra/precedente) | PageRight | Salto verso destra (fino alla pagina o al gruppo orizzontale a destra/successivo) | ScrollUp | Scorrimento verso l'alto (all'interno di un elemento dell'interfaccia utente selezionato o gruppo scrollabile) | ScrollDown | Scorrimento verso il basso (all'interno di un elemento dell'interfaccia utente selezionato o gruppo scrollabile) | ScrollLeft | Scorrimento verso sinistra (all'interno di un elemento dell'interfaccia utente selezionato o gruppo scrollabile) | ScrollRight | Scorrimento verso destra (all'interno di un elemento dell'interfaccia utente selezionato o gruppo scrollabile) | Context1 | Azione contesto principale | Context2 | Azione contesto secondario | Context3 | Azione terzo contesto | Context4 | Azione quarto contesto

Nota Anche se un gioco è libero di rispondere a qualsiasi comando con una funzione effettiva diversa dall'uso previsto, è consigliabile evitare un comportamento sorprendente. In particolare, evitare di modificare la funzione effettiva di un comando se è necessario il suo uso previsto, provare ad assegnare nuove funzioni al comando che abbia più senso e assegnare funzioni equivalenti a comandi equivalenti quali PageUp/PageDown. Infine, considerare quali sono i comandi supportati da ogni tipo di dispositivo di input e a quali controlli sono mappati, accertandosi che i comandi critici siano accessibili da ogni dispositivo.

Navigazione con gamepad, levetta Arcade e volante da corsa

Tutti i dispositivi di input supportati dallo spazio dei nomi Windows.Gaming.Input sono dispositivi di navigazione dell'interfaccia utente.

Nella tabella seguente viene riepilogato il mapping del set necessario di comandi di navigazione nei vari dispositivi di input.

Nella tabella seguente viene riepilogato il mapping del set opzionale di comandi di navigazione nei vari dispositivi di input.

Rilevamento e tracciamento dei controller per navigazione dell'interfaccia utente

Anche se i controller dper navigazione dell'interfaccia utente sono dispositivi di input logici, sono una rappresentazione di un dispositivo fisico e sono gestiti dal sistema nello stesso modo. Non è necessario crearli o inizializzarli; il sistema fornisce un elenco di controller ed eventi per la navigazione dell'interfaccia utente collegati per notificare quando viene aggiunto o rimosso un controller per navigazione dell'interfaccia utente.

Elenco dei controller per la navigazione dell'interfaccia utente

La classe UINavigationController fornisce una proprietà statica, UINavigationControllers, che è un elenco di sola lettura dei dispositivi per la navigazione dell'interfaccia utente correntemente collegati. Poiché si potrebbe essere interessati solo ad alcuni dei dispositivi di navigazione collegati, è consigliabile mantenere la propria raccolta anziché accedervi attraverso la proprietà UINavigationControllers.

Nell'esempio seguente tutti i controller per la navigazione dell'interfaccia utente collegati vengono copiati in una nuova raccolta.

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

Aggiunta e rimozione di controller per la navigazione dell'interfaccia utente

Quando viene aggiunto o rimosso un controller per la navigazione dell'interfaccia utente, vengono generati gli eventi UINavigationControllerAdded e UINavigationControllerRemoved. È possibile registrare un gestore eventi per questi eventi per tenere traccia dei dispositivi per la navigazione correntemente collegati.

L'esempio seguente avvia il rilevamento di un dispositivo per la navigazione dell'interfaccia utente aggiunto.

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

Nell'esempio seguente viene interrotto il rilevamento di una levetta Arcade rimossa.

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

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

Utenti e cuffie

Ogni dispositivo di navigazione può essere associato a un account utente per collegare la propria identità all'input e può avere una cuffia collegata per agevolare la chat vocale o le funzionalità di navigazione. Per maggiori informazioni sull'uso con utenti e cuffie, vedere Tracciamento degli utenti e dei relativi dispositivi e Cuffie.

Lettura del controller per la navigazione dell'interfaccia utente

Dopo aver identificato il dispositivo di navigazione dell'interfaccia utente a cui si è interessati, si è pronti a raccogliere l'input da esso proveniente. Tuttavia, a differenza di altri tipi di input a cui si potrebbe essere abituati, i dispositivi per la navigazione non comunicano il cambiamento di stato generando eventi. È invece possibile eseguire letture regolari dei loro stati correnti tramite polling.

Polling del controller per la navigazione dell'interfaccia utente

Il polling acquisisce un'istantanea del dispositivo per la navigazione in un momento preciso. Questo approccio alla raccolta degli input è ottimale per la maggior parte dei giochi in quanto la loro logica viene in genere eseguita in un ciclo deterministico anziché essere guidata dagli eventi; è anche in genere più semplice interpretare i comandi di gioco dagli input raccolti contemporaneamente piuttosto che da molti input singoli raccolti nel tempo.

Il polling di un dispositivo per la navigazione si esegue chiamando UINavigationController.GetCurrentReading; questa funzione restituisce un UINavigationReading che contiene lo stato del dispositivo per la navigazione.

auto navigationController = myNavigationControllers[0];

UINavigationReading reading = navigationController->GetCurrentReading();

Lettura dei pulsanti

Ognuno dei pulsanti di navigazione dell'interfaccia utente fornisce una lettura booleana che corrisponde al fatto che sia premuto (giù) o rilasciato (su) o meno. Per ragioni di efficienza, le letture dei pulsanti non sono rappresentate come singoli valori booleani; sono invece tutti compressi in uno o due campi di bit rappresentati dalle enumerazioni RequiredUINavigationButtons e OptionalUINavigationButtons.

I pulsanti appartenenti al set necessario vengono letti dalla proprietà RequiredButtons della struttura UINavigationReading. I pulsanti appartenenti al set opzionale vengono letti dalla proprietà OptionalButtons. Poiché queste proprietà sono campi di bit, viene utilizzata la mascheratura bitwise per isolare il valore del pulsante a cui si è interessati. Il pulsante viene premuto (giù) quando è impostato il bit corrispondente; altrimenti viene rilasciato (su).

Nell'esempio seguente viene determinato se viene premuto il pulsante Accetta nel set necessario.

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

Nell'esempio seguente viene determinato se viene rilasciato il pulsante Accetta nel set necessario.

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

Accertarsi di utilizzare la proprietà OptionalButtons e l'enumerazione OptionalUINavigationButtons durante la lettura dei pulsanti nel set opzionale.

Nell'esempio seguente viene determinato se viene premuto il pulsante Context 1 nel set opzionale.

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

A volte si potrebbe voler determinare quando un pulsante passa da premuto a rilasciato o da rilasciato a premuto, se più pulsanti vengono premuti o rilasciati o se una serie di pulsanti è disposta in un modo particolare, es. alcuni premuti e altri no. Per informazioni su come rilevare tali condizioni, vedere Rilevamento di transizioni di pulsanti e Rilevamento di disposizioni complesse di pulsanti.

Eseguire l'esempio del controller per la navigazione dell'interfaccia utente

L'esempio InputInterfacingUWP (github) illustra il comportamento dei diversi dispositivi di input come controller per la navigazione dell'interfaccia utente.

Vedere anche

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