Marcação de texto formatado

Use marcação em componentes Label e nós de texto de GUI para aplicar estilos visuais e efeitos aninhados e inspecionar links e sprites com Lua.

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

Como alternativa, defina na fonte um estilo de objeto nomeado e reutilizável e selecione-o em um 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>")

Referência de tags

Tag	Finalidade	Exemplo
color	Define a cor de preenchimento do glifo.
size	Altera a modelagem dos glifos e o tamanho do layout.
gradient	Aplica um gradiente de cores estático ou animado.
ul	Sublinha o texto.
strike	Risca o texto.
outline	Define a largura e a cor do contorno do glifo.
shadow	Adiciona uma sombra ao texto.
shake	Aplica um deslocamento aleatório animado.
wave	Move o texto em uma onda senoidal animada.
sprite	Adiciona um objeto sprite no meio do texto.
link	Adiciona um objeto de link interativo.

Sintaxe

Os nomes de tags e atributos diferenciam maiúsculas de minúsculas. Uma tag com abertura e fechamento se aplica ao texto UTF-32 visível dentro dela. Objetos sprite usam tags que se fecham sozinhas.

<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/>

Atributos

Atributos podem ser escritos sem aspas quando não contêm espaços em branco, ou entre aspas simples ou duplas. color e size aceitam um primeiro valor abreviado, além da forma nomeada value.

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

Aninhamento

As tags devem ser fechadas na ordem inversa à de abertura. Os valores de um estilo interno sobrescrevem a mesma propriedade de um estilo externo. Propriedades diferentes se combinam. Os efeitos de cada trecho permanecem ativos de forma independente; portanto, gradientes aninhados multiplicam as cores e efeitos de posição aninhados somam seus deslocamentos.

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

Entidades

Use &, ', >, < e " para caracteres reservados no texto visível. Entidades numéricas ainda não são aceitas.

Tags

Tags de texto formatado aplicam estilos a um trecho de texto delimitado ou descrevem um objeto que pode ser inspecionado com Lua. Tags de estilo usam uma tag de fechamento correspondente. O objeto sprite se fecha sozinho, enquanto link delimita o texto do link.

color

Define a cor de preenchimento do glifo. As cores usam #RRGGBB ou #RRGGBBAA. O prefixo de cerquilha é obrigatório; 0xFF0000 e FF0000 são inválidos. O resultado multiplica a cor base do label ou do renderizador.

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

size

Altera a modelagem dos glifos e o tamanho do layout, não apenas a escala dos vértices. Valores relativos sempre usam o tamanho base da fonte do layout. Eles não se acumulam com uma tag size externa.

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

gradient

Um gradiente aceita exatamente um conjunto completo de atributos. Misturar conjuntos ou omitir um membro é inválido.

Quando fit é omitido, fit=span distribui o gradiente por todo o texto delimitado pela tag. fit=glyph amostra cada posição de texto modelado de forma independente. O atributo opcional hz especifica os ciclos completos de animação de fluxo por segundo; seu padrão zero mantém o gradiente estático. A rampa de cores espelhada e repetida flui continuamente e reinicia sem saltos de cor. direction=forward é o padrão; use direction=reverse para inverter o fluxo.

<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>

Quatro cantos

Animado

As cores do gradiente multiplicam a cor de preenchimento atual. Portanto, um gradiente dentro de color=#808080 não pode produzir um canal mais brilhante que esse multiplicador base.

ul

Desenha um sublinhado usando as métricas de sublinhado da fonte quando disponíveis. A tag não tem uma cor independente: a linha herda a cor de preenchimento efetiva, incluindo gradientes horizontais, verticais e de quatro cantos.

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

strike

Desenha uma linha sobre o texto delimitado. Aceita os mesmos valores de pattern que ul e também herda a cor de preenchimento efetiva.

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

outline

Define a largura do contorno, sua cor ou ambas. Pelo menos um atributo é obrigatório. Uma largura zero desativa explicitamente o contorno do trecho.

<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

Adiciona uma sombra de bordas nítidas ao texto delimitado. Pelo menos um atributo é obrigatório. Atributos omitidos por uma tag aninhada mantêm o valor da sombra externa; atributos omitidos pela tag mais externa mantêm o valor base da sombra da fonte.

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

shake

Aplica um deslocamento aleatório animado e determinístico sem alterar a quebra de linhas nem os limites do layout. O efeito controla o tempo internamente; os scripts não precisam modificar o texto do label a cada frame da animação.

<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

Move os caracteres para cima e para baixo em uma onda senoidal animada sem alterar a quebra de linhas nem os limites do layout. O layout acumula o tempo de animação quando é atualizado.

<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

Adiciona um objeto sprite com fechamento próprio na posição atual do texto visível. Seus atributos são preservados como metadados para 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/>

As dimensões aceitam valores positivos em unidades de layout sem sufixo, px, em ou %. Tanto em quanto % usam o tamanho base da fonte do layout de texto.

Cada dimensão ausente assume 1em de forma independente. Omitir ambas produz um objeto de 1em × 1em; especificar somente a largura não calcula a altura automaticamente a partir da proporção do recurso.

link

Descreve um intervalo de texto visível como um objeto de link. O texto delimitado é disposto normalmente e recebe o estilo nomeado link por padrão. Componentes Label e GUI selecionam link:hover e link:active em resposta à entrada, sem remodelar o texto. Consulte mensagens de interação para saber quais mensagens são produzidas pela entrada nos links.

<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>

O componente acompanha o estado do ponteiro em cada link. Aplica link:hover enquanto o ponteiro está sobre o link e link:active enquanto o botão está pressionado. Quando nenhum dos estados se aplica, o componente restaura o estilo nomeado pelo atributo style do link, ou link quando o atributo está ausente.

Mensagens de interação

A interação com links usa o sistema normal de entrada do Defold. Adicione uma associação Mouse Trigger para MOUSE_BUTTON_LEFT, que também ativa a entrada por toque único, e adquira o foco de entrada no script do objeto de jogo ou no script de GUI:

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

Consulte foco de entrada e entrada de mouse e toque para saber como configurar.

Quando um componente Label ou GUI recebe entrada do ponteiro, os links produzem as mensagens a seguir. As mensagens de Label são enviadas ao objeto de jogo que o contém; as mensagens de GUI são enviadas ao script de GUI.

Cada mensagem contém estes campos:

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

Estilos nomeados

Cada coleção de fontes contém estilos de objeto nomeados que afetam apenas a renderização. Um link usa o estilo nomeado pelo atributo style, ou link quando o atributo está ausente. Não existe uma tag geral <style> para trechos de texto.

O Defold fornece os seguintes padrões:

Defina um estilo com uma string de texto contendo tags de abertura. As tags são fechadas implicitamente na ordem inversa; portanto, tags de fechamento e texto visível não são permitidos.

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>")

As tags são aplicadas da esquerda para a direita, como se estivessem aninhadas ao redor do texto do objeto. Um estilo de objeto selecionado pelo código chamador é aplicado após o estilo padrão. Quando várias tags definem a mesma propriedade de renderização, o valor aplicado depois sobrescreve os anteriores. Os efeitos são acrescentados na ordem da esquerda para a direita.

API de objetos de layout

Use label.get_layout_objects() ou gui.get_layout_objects() para obter os objetos sprite e link do texto já disposto.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Ambas as funções retornam um array recém-criado contendo os objetos atuais do layout na ordem do texto-fonte. Retornam um array vazio quando o texto não contém tags de objeto. Como os objetos e seus atributos são copiados para Lua a cada chamada, mantenha o resultado em cache e consulte novamente após alterar o texto ou outra propriedade que mude seu layout.

Campos do objeto retornado

Exemplo em 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"))

Combinações úteis

Contorno colorido com gradiente horizontal

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

O gradiente multiplica apenas a cor de preenchimento; o contorno mantém sua própria cor.

Tremer uma frase e aplicar gradiente a uma palavra

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

O efeito de posição externo se aplica a cada glifo. O efeito de cor aninhado se aplica somente a “whole”.

Sobrescrever uma propriedade sem perder as outras

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

A cor interna altera o preenchimento, preservando a largura e a cor do contorno herdadas.