Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Introduzione al GUI skinning

È fondamentale che un gioco offra ai suoi giocatori un'interfaccia utente chiara, informativa e visivamente gradevole. Sebbene i nodi Control abbiano un aspetto già di per sé abbastanza funzionale, c'è sempre spazio per originalità e specifici aggiustamenti. A questo scopo, il motore Godot include un sistema di skinning (o tematizzazione) dell'interfaccia grafica, che consente di personalizzare l'aspetto di ogni controllo, inclusi i controlli personalizzati.

Ecco un esempio di questo sistema in azione: un gioco con un'interfaccia grafica radicalmente che è radicalmente diversa dal tema predefinito del motore:

Una schermata "Preparati!" in Tank Kings, gentilmente concesso da Winterpixel Games

Oltre a dare un aspetto unico al tuo gioco, questo sistema permette agli sviluppatori di offrire agli utenti finali opzioni di personalizzazione, incluse le impostazioni di accessibilità. I temi dell'interfaccia utente sono applicati a cascata (ovvero si propagano dai controlli genitore a quelli figlio), il che significa che le impostazioni dei font o le regolazioni per gli utenti daltonici si possono applicare in un unico punto e influenzare l'intero albero dell'interfaccia. Naturalmente, questo sistema può servire anche per scopi di gioco: il tuo gioco con eroi può cambiare stile in base al personaggio selezionato, oppure puoi dare uno stile diverso alle fazioni nel tuo progetto a squadre.

Le basi dei temi

Il sistema di skinning è gestito dalla risorsa Theme. Ogni progetto Godot ha un tema predefinito intrinseco che contiene le impostazioni utilizzate dai nodi di controllo integrati. È ciò che da ai controlli il loro aspetto distintivo fin da subito. Un tema, tuttavia, descrive solo la configurazione, ed è comunque compito di ogni singolo controllo utilizzare tale configurazione nel modo in cui si voglia visualizzare. Questo è importante da ricordare quando si implementano i propri controlli personalizzati.

Nota

Anche l'editor Godot stesso dipende dal tema predefinito. Ma non ha lo stesso aspetto di un progetto Godot, perché applica un tema personalizzato a quello predefinito. In principio, funziona esattamente come in un gioco, come spiegato in seguito.

Elementi del tema

La configurazione memorizzata in un tema è composta da elementi del tema. Ogni elemento ha un nome univoco e deve essere uno dei seguenti tipi di dati:

• Color

  Un valore color, spesso utilizzato per font e sfondi. I colori possono anche servire per la modulazione di controlli e icone.

• Costante

  Un valore intero, che può servire per proprietà numeriche dei controlli (ad esempio la separazione degli elementi in un BoxContainer) o per flag booleani (ad esempio il disegno di linee di relazione in un Tree).

• Font

  Una risorsa font, utilizzata dai controlli che visualizzano il testo. I font contengono gran parte delle impostazioni di rendering del testo, ad eccezione di dimensione e colore. Inoltre, l'allineamento e la direzione del testo sono controllati da controlli individuali.

• Dimensione di font

  Un valore intero, che serve insieme a un font per determinare la dimensione alla quale deve essere visualizzato il testo.

• Icona

  Una risorsa texture, che normalmente serve per visualizzare un'icona (ad esempio su un Button).

• StyleBox

  Una risorsa StyleBox, una raccolta di opzioni di configurazione che definiscono il modo in cui un pannello dell'interfaccia si dovrebbe visualizzare. Non si limita al controllo Panel, poiché gli stylebox sono utilizzati da molti controlli per i loro sfondi e sovrapposizioni.

  Controlli diversi applicheranno gli StyleBox diversamente. In particolare, gli stylebox focus sono disegnati come una sovrapposizione ad altri stylebox (come normal o pressed) per consentire allo stylebox di base di rimanere visibile. Ciò significa che lo stylebox di focus si dovrebbe progettare come un riquadro con contorno o semitrasparente, in modo che il suo sfondo rimanga visibile.

Tipi del tema

Per facilitare l'organizzazione dei suoi elementi, ogni tema è suddiviso in tipi e ogni elemento deve appartenere a un singolo tipo. In altre parole, ogni elemento del tema è definito dal suo nome, dal suo tipo di dati e dal suo tipo di tema. Questa combinazione deve essere univoca all'interno del tema. Ad esempio, non possono esserci due elementi di colore denominati font_color in un tipo denominato Label, ma può esserci un altro elemento font_color in un tipo LineEdit.

Il tema predefinito di Godot include diversi tipi di tema già definiti, uno per ogni nodo controllo integrato che utilizza UI skinning. L'esempio precedente contiene elementi del tema effettivamente presenti nel tema predefinito. È possibile fare riferimento alla sezione Proprietà del tema nel riferimento alla classe di ciascun controllo per vedere quali elementi sono disponibili per esso e per le sue classi figlio.

Nota

Le classi figlie possono utilizzare gli elementi del tema definiti per la classe padre (Button e i suoi derivati ne sono un buon esempio). Infatti, ogni controllo può utilizzare qualsiasi elemento del tema di qualsiasi tipo, se necessario (ma per chiarezza e prevedibilità cerchiamo di evitarlo nel motore).

È importante ricordare che per le classi figlio questo processo è automatizzato. Ogni volta che un controllo integrato richiede un elemento del tema, può omettere il tipo del tema e sarà utilizzato il nome della sua classe. Inoltre, saranno utilizzati a loro volta anche i nomi delle classi padre. Questo consente alle modifiche apportate alla classe padre, come Button, di influire su tutte le classi derivate senza doverle personalizzare singolarmente.

È inoltre possibile definire i propri tipi del tema e personalizzare sia i controlli integrati sia controlli personalizzati. Poiché i controlli integrati non conoscono i tipi del tema personalizzati, è necessario utilizzare script per accedervi. Tutti i nodi di controllo hanno diversi metodi che consentono di recuperare gli elementi del tema dal tema a essi applicato. Questi metodi accettano il tipo del tema come uno degli argomenti.

GDScriptC#

var accent_color = get_theme_color("accent_color", "MyType")
label.add_theme_color_override("font_color", accent_color)

Per offrire più opportunità di personalizzazione, i tipi si possono anche connettere tra loro come variazioni di tipo. Questo è un altro caso d'uso per i tipi del tema personalizzati. Ad esempio, un tema può contenere un tipo Header che può essere segnato come una variazione del tipo base Label. Un singolo controllo Label si può quindi configurare per utilizzare la variazione Header per il suo tipo, e ogni volta che un elemento del tema è richiesto da un tema, questa variazione sarà utilizzata prima di qualsiasi altro tipo. Ciò consente di memorizzare diverse preimpostazioni di elementi del tema per la stessa classe del nodo controllo in una sola risorsa Theme.

Avvertimento

Solo le variazioni disponibili nel tema predefinito o definite nel tema personalizzato del progetto sono visualizzate come opzioni nel pannello Ispettore. È comunque possibile inserire manualmente il nome di una variazione definita fuori queste due posizioni, ma si consiglia di mantenere tutte le variazioni nel tema del progetto.

Per ulteriori informazioni su come creare e utilizzare le variazioni di tipi del tema, consulta l'articolo dedicato.

Personalizzazione di un controllo

Ogni nodo controllo si può personalizzare direttamente senza l'utilizzo di temi. Questa operazione è detta sostituzione locale. Ogni proprietà del tema presente nel riferimento alla classe del controllo si può sovrascrivere direttamente sul controllo stesso, attraverso il pannello Ispettore o gli script. Questo consente di apportare modifiche granulari a una parte specifica dell'interfaccia utente, senza influire su altri elementi del progetto, inclusi gli elementi figlio di questo controllo.

Le sostituzioni locali sono meno utili per l'aspetto visivo dell'interfaccia utente, soprattutto se si desidera coerenza. Però sono essenziali per i nodi di layout. Nodi come BoxContainer e GridContainer utilizzano costanti del tema per definire la separazione tra i loro elementi figlio, mentre MarginContainer memorizza i margini personalizzabili nei propri elementi del tema.

Ogni volta che un controllo ha una sostituzione di un elemento del tema locale, questo è il valore che utilizza. I valori forniti dal tema sono ignorati.

Customizing a project

Inizialmente, ogni progetto adotta il tema predefinito fornito da Godot. Il tema predefinito è fisso e non può essere modificato, ma è possibile sovrascrivere i suoi elementi con un tema personalizzato. I temi personalizzati si possono applicare in due modi: come impostazione del progetto e come proprietà di un nodo in tutto l'albero dei nodi controllo.

Ci sono due impostazioni del progetto che si possono regolare per influenzare l'intero progetto: GUI > Tema > Personalizzato consente di impostare un tema personalizzato per l'intero progetto, e GUI > Tema > Font personalizzato fa lo stesso per il font di riserva predefinito. Quando un nodo controllo richiede un elemento del tema, viene prima verificato il tema personalizzato del progetto, se presente. Solo se non contiene l'elemento, viene verificato il tema predefinito.

Ciò consente di configurare l'aspetto predefinito di ogni controllo in Godot con una singola risorsa tema, ma è possibile andare più a fondo. Ogni nodo controllo ha anche una proprietà theme, che consente di impostare un tema personalizzato per il ramo di nodi che inizia con quel controllo. Ciò significa che il controllo e tutti i suoi figli, e i loro figli a loro volta, verificheranno prima quella risorsa tema personalizzata prima di ricorrere al progetto e ai temi predefiniti.

Nota

Anziché cambiare l'impostazione del progetto, è possibile impostare la risorsa tema personalizzato sul nodo controllo radice dell'intero ramo dell'interfaccia utente, ottenendo quasi lo stesso effetto. Mentre nel progetto in esecuzione il comportamento sarà quello previsto, le singole scene continueranno ad apparire con il tema predefinito se viste in anteprima o eseguite direttamente. Per risolvere, si potrebbe impostare la stessa risorsa del tema sul controllo radice di ciascuna singola scena.

Ad esempio, è possibile avere uno stile specifico per i pulsanti nel tema del progetto, ma desiderare un aspetto diverso per i pulsanti all'interno di un popup. È possibile impostare una risorsa tema personalizzata per il controllo radice del popup e definire uno stile diverso per i pulsanti all'interno di tale risorsa. Finché la catena di nodi controllo tra la radice del popup e i pulsanti è ininterrotta, questi pulsanti utilizzeranno gli stili definiti nella risorsa tema più vicina. Tutti gli altri controlli continueranno a essere stilizzati utilizzando il tema dell'intero progetto e il tema predefinito.

Riassumendo, per un controllo qualunque, la ricerca di un elemento del tema sarebbe qualcosa del genere:

1. Verifica la presenza di sostituzioni locali dello stesso tipo di dati e nome.

2. Utilizzando la variazione di tipo del controllo, il nome della classe e i nomi delle classi padre:

   1. Verifica ogni controllo a partire da se stesso e verifica se ha una proprietà del tema impostata;

   2. Se sì, verifica il tema per l'elemento corrispondente con lo stesso nome, dati e tipo di tema;

   3. Se non è presente alcun tema personalizzato o non ha l'elemento, passa al controllo padre;

   4. Ripeti i passaggi a-c, fino a raggiungere la radice dell'albero o un nodo non controllo.

3. Utilizzando la variazione di tipo del controllo, il nome della classe e i nomi delle classi padre, verifica il tema dell'intero progetto, se presente.

4. Utilizzando la variazione di tipo del controllo, il nome della classe e i nomi delle classi padre, verifica il tema predefinito.

Anche se l'elemento non esiste in alcun tema, sarà restituito un valore predefinito corrispondente per quel tipo di dati.

Oltre i controlli

Naturalmente, i temi sono una risorsa ideale per memorizzare la configurazione di qualcosa di visivo. Sebbene il supporto per i temi sia integrato nei nodi controllo, anche altri nodi possono utilizzarli, proprio come qualsiasi altra risorsa.

Un esempio di utilizzo dei temi per qualcosa che va oltre i controlli può essere la modulazione di sprite per le stesse unità in squadre diverse in un gioco di strategia. Una risorsa tema può definire una raccolta di colori e gli sprite (grazie a qualche script) possono usare quei colori per disegnare la texture. Il vantaggio principale è che è possibile creare temi diversi utilizzando gli stessi elementi del tema per le squadre rossa, blu e verde, e scambiarli con un singolo cambio di risorsa.