Markup del testo formattato

Usa il markup nei componenti Label e nei nodi di testo GUI per applicare stili visivi ed effetti annidati ed esaminare link e sprite da Lua.

go.set("#label", "text", "Score: <color=#69D2E7>1200</color>")

In alternativa, definisci sul font uno stile di oggetto riutilizzabile con nome e selezionalo da un link:

local fontpath = "/fonts/ui.fontc"
font.set_style(fontpath, "menu_link", "<color=#69D2E7>")
go.set("#label", "text", "Open <link style=menu_link src=inventory>inventory</link>")

Riferimento dei tag

Tag	Scopo	Esempio
color	Imposta il colore di riempimento dei glifi.
size	Modifica la dimensione dei glifi nella composizione e nel layout.
gradient	Applica un gradiente di colore statico o animato.
ul	Sottolinea il testo.
strike	Barra il testo.
outline	Imposta spessore e colore del contorno dei glifi.
shadow	Aggiunge un’ombra al testo.
shake	Applica uno spostamento casuale animato.
wave	Muove il testo lungo un’onda sinusoidale animata.
sprite	Aggiunge un oggetto sprite in linea.
link	Aggiunge un oggetto link interattivo.

Sintassi

I nomi dei tag e degli attributi distinguono tra maiuscole e minuscole. Un tag con apertura e chiusura si applica al testo UTF-32 visibile che contiene. Gli oggetti sprite usano tag a chiusura automatica.

<color=#69D2E7>colored text</color>
<ul pattern=dashed>underlined text</ul>
<outline size=2 color=#000000>outlined text</outline>
<shadow x=2 y=-2 color=#00000080>shadowed text</shadow>
<sprite src=images/icon.png width=2em/>

Attributi

Gli attributi possono essere scritti senza virgolette se non contengono spazi oppure racchiusi tra virgolette singole o doppie. color e size supportano sia un primo valore abbreviato sia la forma con nome value.

<color=#FF8800>Orange</color>
<color value="#FF8800">Orange</color>
<size='120%'>Larger</size>

Annidamento

I tag devono essere chiusi nell’ordine inverso rispetto a quello di apertura. I valori degli stili interni sovrascrivono la stessa proprietà di uno stile esterno. Le proprietà diverse si combinano. Gli effetti delle porzioni di testo rimangono attivi in modo indipendente: i gradienti annidati moltiplicano i colori e gli effetti di posizione annidati sommano i propri spostamenti.

<color=#FFCC00>
    Gold <outline size=2 color=#000000>with a black outline</outline>
</color>

Entità

Usa &, ', >, < e " per i caratteri riservati nel testo visibile. Le entità numeriche non sono attualmente supportate.

Tag

I tag del testo formattato applicano uno stile a una porzione di testo racchiusa al loro interno oppure descrivono un oggetto che puoi esaminare da Lua. I tag di stile usano un tag di chiusura corrispondente. L’oggetto sprite è a chiusura automatica, mentre link racchiude il testo del collegamento.

color

Imposta il colore di riempimento dei glifi. I colori usano #RRGGBB o #RRGGBBAA. Il prefisso cancelletto è obbligatorio; 0xFF0000 e FF0000 non sono validi. Il risultato moltiplica il colore di base dell’etichetta o del renderer.

<color=#00FF00>Opaque green</color>
<color=#00FF0080>Half-alpha green</color>

size

Modifica la dimensione dei glifi nella composizione e nel layout, non soltanto la scala dei vertici. I valori relativi usano sempre la dimensione di base del font del layout. Non si moltiplicano con un tag size esterno.

<size=24px>Exactly 24 pixels</size>
<size=120%>120% of the layout base size</size>
<size=2em>Twice the layout base size</size>

gradient

Un gradiente accetta esattamente un insieme completo di attributi. Combinare insiemi diversi oppure omettere un membro non è valido.

Quando fit è omesso, fit=span distribuisce il gradiente sull’intero testo racchiuso nel tag. fit=glyph campiona ogni posizione del testo composto in modo indipendente. L’attributo facoltativo hz specifica il numero di cicli completi di animazione dello scorrimento al secondo; il suo valore predefinito di zero mantiene statico il gradiente. La rampa di colori speculare e ripetuta scorre in modo continuo e ricomincia senza salti di colore. direction=forward è il valore predefinito; usa direction=reverse per invertire lo scorrimento.

<gradient left=#FF00FF right=#FFFFFF>Horizontal Gradient</gradient>

<gradient hz=0.25 fit=glyph bottom=#182848 top=#4B6CB7>Animated vertical glyphs</gradient>

<gradient hz=0.25 direction=reverse left=#FF0000 right=#0000FF>Reverse flow</gradient>

<gradient hz=0.25 direction=reverse fit=span left=#FF0000 right=#0000FF>One animated span color</gradient>

<gradient fit=glyph tl=#FF0000 tr=#00FF00 bl=#0000FF br=#FFFFFF>
    Four corners
</gradient>

Quattro angoli

Animato

I colori del gradiente moltiplicano il colore di riempimento corrente. Un gradiente all’interno di color=#808080 non può quindi produrre un canale più luminoso di quel moltiplicatore di base.

ul

Disegna una sottolineatura usando le metriche di sottolineatura del font, quando disponibili. Il tag non ha un colore indipendente: la linea eredita il colore di riempimento effettivo, inclusi i gradienti orizzontali, verticali e a quattro angoli.

<ul>Solid underline</ul>
<ul pattern=dashed>Dashed underline</ul>
<ul><gradient left=#FF00FF right=#FFFFFF>Gradient line</gradient></ul>

strike

Disegna una linea che barra il testo racchiuso nel tag. Accetta gli stessi valori di pattern di ul e ne eredita allo stesso modo il colore di riempimento effettivo.

<strike>No longer available</strike>
<strike pattern=dashed>Dashed strikethrough</strike>

outline

Imposta lo spessore del contorno, il suo colore o entrambi. È richiesto almeno un attributo. Uno spessore pari a zero disabilita esplicitamente il contorno per la porzione di testo.

<outline size=3 color=#000000>Black outline</outline>
<outline color=#FF0000>Keep inherited width, change color</outline>
<outline size=0>Disable inherited outline</outline>

shadow

Aggiunge un’ombra dai bordi netti al testo racchiuso nel tag. È richiesto almeno un attributo. Gli attributi omessi da un tag annidato conservano il valore dell’ombra esterna; quelli omessi dal tag più esterno conservano il valore di base dell’ombra del font.

<shadow x=6 y=-6 blur=4 color=#000000A0>Shadow</shadow>
<shadow x=-2>Override only the horizontal offset</shadow>

shake

Applica uno spostamento casuale animato deterministico senza modificare gli a capo o i limiti del layout. L’effetto tiene traccia del tempo internamente; gli script non devono modificare il testo dell’etichetta a ogni fotogramma dell’animazione.

<shake>Default shake</shake>
<shake hz=12 amplitude=0.8 fit=glyph>Glyph shake</shake>
<shake hz=12 amplitude=0.8 fit=span>Rigid span shake</shake>

wave

Muove i caratteri verso l’alto e il basso lungo un’onda sinusoidale animata senza modificare gli a capo o i limiti del layout. Il layout accumula il tempo di animazione quando viene aggiornato.

<wave>Animated character wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph>Travelling wave</wave>
<wave amplitude=4 hz=3 wavelength=8 fit=glyph direction=reverse>Reverse travelling wave</wave>
<wave amplitude=4 hz=1 fit=span>Whole span moves together</wave>

sprite

Aggiunge un oggetto sprite a chiusura automatica nella posizione corrente del testo visibile. I suoi attributi vengono conservati come metadati per label.get_layout_objects() e gui.get_layout_objects().

A <sprite src=engine/engine/content/builtins/assets/images/logo/logo_256.png/> logo
<sprite src=images/banner.png width=4em height=2em/>
<sprite src=images/icons.atlas animation=coin width=2em/>

Le dimensioni accettano valori positivi in unità di layout senza suffisso, px, em o %. Sia em sia % usano la dimensione di base del font del layout del testo.

Ogni dimensione mancante assume indipendentemente il valore predefinito 1em. Omettendole entrambe si ottiene un oggetto 1em × 1em; specificare soltanto la larghezza non ricava automaticamente l’altezza dalle proporzioni della risorsa.

link

Descrive un intervallo di testo visibile come oggetto link. Il testo racchiuso viene disposto normalmente e riceve per impostazione predefinita lo stile con nome link. I componenti Label e GUI selezionano link:hover e link:active in risposta all’input senza ricomporre il testo. Consulta Messaggi di interazione per i messaggi prodotti dall’input sui link.

<ul><link id=website src=https://www.defold.com>www.defold.com</link></ul>
<link id=inventory style=menu_link action=open_inventory item=sword>Iron sword</link>

Il componente tiene traccia dello stato del puntatore per ogni link. Applica link:hover mentre il puntatore è sopra il link e link:active mentre il pulsante del puntatore è premuto. Quando nessuno dei due stati è attivo, il componente ripristina lo stile indicato dall’attributo style del link, oppure link se l’attributo è assente.

Messaggi di interazione

L’interazione con i link usa il normale sistema di input di Defold. Aggiungi un binding Mouse Trigger per MOUSE_BUTTON_LEFT, che abilita anche l’input a tocco singolo, e acquisisci il focus dell’input nello script dell’oggetto di gioco o nello script GUI:

function init(self)
    msg.post(".", "acquire_input_focus")
end

Consulta Focus dell’input e Input da mouse e tocco per i dettagli della configurazione.

Quando un componente etichetta o GUI riceve input dal puntatore, i link producono i messaggi seguenti. I messaggi delle etichette vengono inviati all’oggetto di gioco a cui appartengono; i messaggi GUI vengono inviati allo script GUI.

Ogni messaggio contiene questi campi:

function on_message(self, message_id, message)
    if message_id == hash("text_object_clicked") then
        assert(message.type == hash("link"))
        print(message.id, message.src)
    end
end

Stili con nome

Ogni collezione di font contiene stili di oggetto con nome che influiscono soltanto sul rendering. Un link usa lo stile indicato dal suo attributo style, oppure link se l’attributo è assente. Non esiste un tag generico <style> per le porzioni di testo.

Defold fornisce i seguenti valori predefiniti:

Definisci uno stile con una stringa di testo contenente tag di apertura. I tag vengono chiusi implicitamente nell’ordine inverso, quindi non sono consentiti tag di chiusura né testo visibile.

font.set_style("/fonts/ui.fontc", "link",
    "<color=#2673ff><outline color=#000000 size=1>")

font.set_style("/fonts/ui.fontc", "link:hover",
    "<color=#66b3ff><shake amplitude=0.2 hz=20>")

I tag vengono applicati da sinistra a destra, come se fossero annidati attorno al testo dell’oggetto. Uno stile di oggetto selezionato dal chiamante viene applicato dopo lo stile predefinito. Quando più tag impostano la stessa proprietà di rendering, il valore applicato per ultimo sovrascrive quelli precedenti. Gli effetti vengono aggiunti nell’ordine da sinistra a destra.

API degli oggetti di layout

Usa label.get_layout_objects() o gui.get_layout_objects() per recuperare gli oggetti sprite e link dal testo già disposto nel layout.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Entrambe le funzioni restituiscono un array appena creato che contiene gli oggetti di layout correnti nell’ordine del sorgente. Restituiscono un array vuoto quando il testo non contiene tag di oggetto. Poiché gli oggetti e i loro attributi vengono copiati in Lua a ogni chiamata, conserva il risultato in cache e ripeti la richiesta dopo aver modificato il testo o un’altra proprietà che ne cambia il layout.

Campi degli oggetti restituiti

Esempio Lua

local text = [[
Read the <link src=https://defold.com/manuals/ id=manual>manual</link>
or inspect <sprite src=images/info.png width=2em/> for more information.
]]

go.set("#label", "text", text)

local objects = label.get_layout_objects("#label")
for _, object in ipairs(objects) do
    if object.type == "link" then
        print("link", object.attributes.src)
        print("visible range", object.text_offset, object.text_length)
        print("position", object.x, object.y)
    elseif object.type == "sprite" then
        print("sprite", object.x, object.y, object.width, object.height)
        pprint(object.attributes)
    end
end

local gui_objects = gui.get_layout_objects(gui.get_node("rich_text"))

Combinazioni utili

Contorno colorato con un gradiente orizzontale

<outline size=2 color=#101820>
    <gradient left=#FEE715 right=#FF6F61>Gradient title</gradient>
</outline>

Il gradiente moltiplica soltanto il colore di riempimento; il contorno mantiene il proprio colore.

Far tremare una frase e applicare un gradiente a una parola

<shake hz=20 amplitude=0.5>
    This <gradient left=#FF00FF right=#FFFFFF>whole</gradient> text shakes!
</shake>

L’effetto di posizione esterno si applica a ogni glifo. L’effetto di colore annidato si applica soltanto a “whole”.

Sovrascrivere una proprietà senza perdere le altre

<color=#FFFFFF><outline size=2 color=#000000>
    Normal <color=#FF4040>warning</color> normal
</outline></color>

Il colore interno cambia il riempimento mantenendo lo spessore e il colore del contorno ereditati.