Marcado de texto enriquecido

Usa marcado en los componentes Label y los nodos de texto GUI para aplicar estilos visuales y efectos anidados, y consultar enlaces y sprites desde Lua.

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

También puedes definir en la fuente un estilo de objeto reutilizable con nombre y seleccionarlo desde un enlace:

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

Referencia de etiquetas

Etiqueta	Propósito	Ejemplo
color	Define el color de relleno del glifo.
size	Cambia la conformación de los glifos y el tamaño del layout.
gradient	Aplica un degradado de color estático o animado.
ul	Subraya el texto.
strike	Tacha el texto.
outline	Define el grosor y el color del contorno del glifo.
shadow	Agrega una sombra al texto.
shake	Aplica un desplazamiento aleatorio animado.
wave	Mueve el texto con una onda sinusoidal animada.
sprite	Agrega un objeto sprite integrado en el texto.
link	Agrega un objeto de enlace interactivo.

Sintaxis

Los nombres de etiquetas y atributos distinguen entre mayúsculas y minúsculas. Una etiqueta con apertura y cierre se aplica al texto UTF-32 visible en su interior. Los objetos sprite usan etiquetas de cierre automático.

<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

Los atributos pueden escribirse sin comillas cuando no contienen espacios en blanco, o entre comillas simples o dobles. color y size admiten un primer valor abreviado además de la forma con el nombre value.

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

Anidamiento

Las etiquetas deben cerrarse en orden inverso al de apertura. Los valores de un estilo interno sobrescriben la misma propiedad de un estilo externo. Las propiedades distintas se combinan. Los efectos de los fragmentos permanecen activos de forma independiente, por lo que los degradados anidados multiplican los colores y los efectos de posición anidados suman sus desplazamientos.

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

Entidades

Usa &, ', >, < y " para los caracteres reservados en el texto visible. Actualmente no se admiten entidades numéricas.

Etiquetas

Las etiquetas de texto enriquecido aplican estilos al fragmento de texto que encierran o describen un objeto que se puede consultar desde Lua. Las etiquetas de estilo usan una etiqueta de cierre correspondiente. El objeto sprite tiene cierre automático, mientras que link encierra el texto de su enlace.

color

Define el color de relleno del glifo. Los colores usan #RRGGBB o #RRGGBBAA. El prefijo de almohadilla es obligatorio; 0xFF0000 y FF0000 no son válidos. El resultado multiplica el color base del label o del renderizador.

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

size

Cambia la conformación de los glifos y el tamaño del layout, no solo la escala de los vértices. Los valores relativos siempre usan el tamaño base de fuente del layout. No se acumulan con una etiqueta size que los encierre.

<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 degradado acepta exactamente un conjunto completo de atributos. Mezclar conjuntos u omitir un miembro no es válido.

Si se omite fit, fit=span distribuye el degradado por todo el texto etiquetado. fit=glyph muestrea cada posición del texto conformado de forma independiente. El atributo opcional hz especifica los ciclos completos de animación de flujo por segundo; su valor predeterminado de cero mantiene el degradado estático. La rampa de color repetida y reflejada fluye continuamente y vuelve a comenzar sin saltos de color. direction=forward es el valor predeterminado; usa direction=reverse para invertir el flujo.

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

Cuatro esquinas

Animado

Los colores del degradado multiplican el color de relleno actual. Por tanto, un degradado dentro de color=#808080 no puede producir un canal más brillante que ese multiplicador base.

ul

Dibuja un subrayado usando las métricas de subrayado de la fuente cuando están disponibles. La etiqueta no tiene un color independiente: la línea hereda el color de relleno efectivo, incluidos los degradados horizontales, verticales y de cuatro esquinas.

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

strike

Dibuja una línea que tacha el texto encerrado. Acepta los mismos valores de pattern que ul y también hereda el color de relleno efectivo.

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

outline

Define el grosor del contorno, su color o ambos. Se requiere al menos un atributo. Un grosor de cero desactiva explícitamente el contorno del fragmento.

<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

Agrega una sombra dura al texto encerrado. Se requiere al menos un atributo. Los atributos omitidos por una etiqueta anidada conservan el valor de la sombra que la encierra; los atributos omitidos por la etiqueta más externa conservan el valor de sombra base de la fuente.

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

shake

Aplica un desplazamiento aleatorio animado y determinista sin cambiar los saltos de línea ni los límites del layout. El efecto controla el tiempo internamente; los scripts no necesitan modificar el texto del label en cada frame de animación.

<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

Mueve los caracteres hacia arriba y hacia abajo con una onda sinusoidal animada sin cambiar los saltos de línea ni los límites del layout. El layout acumula el tiempo de animación al actualizarse.

<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

Agrega un objeto sprite de cierre automático en la posición actual del texto visible. Sus atributos se conservan como metadatos para label.get_layout_objects() y 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/>

Las dimensiones aceptan unidades de layout positivas sin sufijo, px, em o %. Tanto em como % usan el tamaño base de fuente del layout de texto.

Cada dimensión omitida toma de forma independiente el valor predeterminado 1em. Omitir ambas produce un objeto de 1em × 1em; especificar solo el ancho no calcula automáticamente el alto a partir de la relación de aspecto del recurso.

link

Describe un rango de texto visible como un objeto de enlace. El texto encerrado se dispone normalmente y recibe de forma predeterminada el estilo con nombre link. Los componentes Label y GUI seleccionan link:hover y link:active en respuesta al input sin volver a conformar el texto. Consulta mensajes de interacción para conocer los mensajes generados por el input de enlaces.

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

El componente sigue el estado del puntero de cada enlace. Aplica link:hover mientras el puntero está sobre el enlace y link:active mientras permanece presionado. Cuando no se aplica ninguno de estos estados, el componente restaura el estilo indicado por el atributo style del enlace, o link si el atributo no está presente.

Mensajes de interacción

La interacción con enlaces usa el sistema de input normal de Defold. Agrega una vinculación Mouse Trigger para MOUSE_BUTTON_LEFT, que también activa el input de un solo toque, y adquiere el foco de input en el script del objeto de juego o en el script GUI:

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

Consulta foco de input e input de mouse y táctil para conocer los detalles de configuración.

Cuando un componente Label o GUI recibe input del puntero, los enlaces generan los siguientes mensajes. Los mensajes de Label se envían al objeto de juego al que pertenece; los mensajes de GUI se envían al script GUI.

Cada mensaje contiene estos 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 con nombre

Cada colección de fuentes contiene estilos de objeto con nombre que solo afectan al renderizado. Un enlace usa el estilo indicado por su atributo style, o link si el atributo no está presente. No existe una etiqueta general <style> para fragmentos.

Defold proporciona los siguientes valores predeterminados:

Define un estilo con una cadena de texto que contenga etiquetas de apertura. Las etiquetas se cierran implícitamente en orden inverso, por lo que no se permiten etiquetas de cierre ni texto visible.

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

Las etiquetas se aplican de izquierda a derecha, como si estuvieran anidadas alrededor del texto del objeto. Un estilo de objeto seleccionado por quien llama se aplica después del estilo predeterminado. Cuando varias etiquetas definen la misma propiedad de renderizado, el valor aplicado después sobrescribe los anteriores. Los efectos se agregan en orden de izquierda a derecha.

API de objetos de layout

Usa label.get_layout_objects() o gui.get_layout_objects() para obtener los objetos sprite y link del texto dispuesto.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Ambas funciones devuelven un array nuevo que contiene los objetos de layout actuales en el orden del código fuente. Devuelven un array vacío cuando el texto no contiene etiquetas de objeto. Como los objetos y sus atributos se copian a Lua en cada llamada, guarda el resultado en caché y vuelve a consultarlo después de cambiar el texto u otra propiedad que cambie su layout.

Campos del objeto devuelto

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

Combinaciones útiles

Contorno de color con un degradado horizontal

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

El degradado multiplica solo el color de relleno; el contorno conserva su propio color.

Hacer vibrar una frase y aplicar un degradado a una palabra

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

El efecto de posición externo se aplica a todos los glifos. El efecto de color anidado se aplica solo a “whole”.

Sobrescribir una propiedad sin perder las demás

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

El color interno cambia el relleno mientras conserva el grosor y el color del contorno heredados.