Balisage de texte enrichi

Utilisez le balisage dans les composants Label et les nœuds de texte GUI pour appliquer des styles visuels et des effets imbriqués, et inspecter les liens et les sprites depuis Lua.

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

Vous pouvez aussi définir sur la police un style d’objet nommé réutilisable et le sélectionner depuis un lien :

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

Référence des balises

Balise	Fonction	Exemple
color	Définit la couleur de remplissage des glyphes.
size	Modifie la taille utilisée pour la mise en forme des glyphes et la mise en page.
gradient	Applique un dégradé de couleurs statique ou animé.
ul	Souligne le texte.
strike	Barre le texte.
outline	Définit la largeur et la couleur du contour des glyphes.
shadow	Ajoute une ombre au texte.
shake	Applique un décalage aléatoire animé.
wave	Anime le texte selon une onde sinusoïdale.
sprite	Ajoute un objet sprite intégré au texte.
link	Ajoute un objet lien interactif.

Syntaxe

Les noms de balises et d’attributs sont sensibles à la casse. Une paire de balises s’applique au texte UTF-32 visible qu’elle contient. Les objets sprite utilisent des balises autofermantes.

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

Attributs

Les valeurs d’attributs peuvent être écrites sans guillemets lorsqu’elles ne contiennent aucun espace, ou entourées de guillemets simples ou doubles. color et size acceptent une première valeur abrégée ainsi que la forme nommée value.

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

Imbrication

Les balises doivent se fermer dans l’ordre inverse de leur ouverture. Les valeurs d’un style intérieur remplacent les mêmes propriétés d’un style extérieur. Les propriétés différentes se combinent. Les effets de chaque portion de texte restent actifs indépendamment : les dégradés imbriqués multiplient donc les couleurs et les effets de position imbriqués additionnent leurs décalages.

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

Entités

Utilisez &, ', >, < et " pour les caractères réservés dans le texte visible. Les entités numériques ne sont pas prises en charge actuellement.

Balises

Les balises de texte enrichi appliquent un style à la portion de texte qu’elles entourent ou décrivent un objet qui peut être inspecté depuis Lua. Les balises de style utilisent une balise de fermeture correspondante. L’objet sprite est autofermant, tandis que link entoure le texte du lien.

color

Définit la couleur de remplissage des glyphes. Les couleurs utilisent #RRGGBB ou #RRGGBBAA. Le préfixe dièse est obligatoire ; 0xFF0000 et FF0000 ne sont pas valides. Le résultat multiplie la couleur de base du label ou du moteur de rendu.

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

size

Modifie la taille utilisée pour la mise en forme des glyphes et la mise en page, et pas seulement l’échelle des sommets. Les valeurs relatives utilisent toujours la taille de base de la police de la mise en page. Elles ne se cumulent pas avec une balise size extérieure.

<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 dégradé accepte exactement un ensemble complet d’attributs. Mélanger des ensembles ou omettre l’un de leurs membres n’est pas valide.

Lorsque fit est omis, fit=span répartit le dégradé sur tout le texte entouré par la balise. fit=glyph échantillonne indépendamment chaque position de texte après mise en forme. L’attribut facultatif hz définit le nombre de cycles complets d’animation du défilement par seconde ; sa valeur par défaut de zéro conserve un dégradé statique. La rampe de couleurs répétée en miroir défile en continu et boucle sans saut de couleur. direction=forward est la valeur par défaut ; utilisez direction=reverse pour inverser le défilement.

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

Quatre coins

Animé

Les couleurs du dégradé multiplient la couleur de remplissage actuelle. Un dégradé à l’intérieur de color=#808080 ne peut donc produire aucun canal plus lumineux que ce multiplicateur de base.

ul

Trace un soulignement en utilisant les métriques de soulignement de la police lorsqu’elles sont disponibles. La balise n’a pas de couleur indépendante : la ligne hérite de la couleur de remplissage effective, y compris les dégradés horizontaux, verticaux et à quatre coins.

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

strike

Trace une ligne à travers le texte entouré par la balise. Accepte les mêmes valeurs de pattern que ul et hérite également de la couleur de remplissage effective.

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

outline

Définit la largeur du contour, sa couleur ou les deux. Au moins un attribut est obligatoire. Une largeur nulle désactive explicitement le contour pour la portion de texte.

<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

Ajoute une ombre nette au texte entouré par la balise. Au moins un attribut est obligatoire. Les attributs omis par une balise imbriquée conservent la valeur de l’ombre extérieure ; ceux omis par la balise la plus extérieure conservent la valeur de base de l’ombre de la police.

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

shake

Applique un décalage aléatoire animé déterministe sans modifier les sauts de ligne ni les limites de la mise en page. L’effet gère le temps en interne ; les scripts n’ont pas besoin de modifier le texte du label à chaque image de l’animation.

<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

Déplace les caractères de haut en bas selon une onde sinusoïdale animée sans modifier les sauts de ligne ni les limites de la mise en page. La mise en page accumule le temps d’animation lors de ses mises à jour.

<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

Ajoute un objet sprite autofermant à la position actuelle dans le texte visible. Ses attributs sont préservés comme métadonnées pour label.get_layout_objects() et 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/>

Les dimensions acceptent des unités de mise en page positives sans suffixe, px, em ou %. em et % utilisent tous deux la taille de base de la police de la mise en page du texte.

Chaque dimension manquante vaut indépendamment 1em par défaut. Omettre les deux produit un objet de 1em × 1em ; préciser uniquement la largeur ne déduit pas automatiquement la hauteur à partir du rapport largeur/hauteur d’une ressource.

link

Décrit une plage de texte visible comme un objet lien. Le texte entouré par la balise est mis en page normalement et reçoit par défaut le style nommé link. Les composants Label et GUI sélectionnent link:hover et link:active en réponse aux entrées, sans refaire la mise en forme des glyphes. Consultez Messages d’interaction pour les messages produits par les entrées sur les liens.

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

Le composant suit l’état du pointeur pour chaque lien. Il applique link:hover lorsque le pointeur survole le lien et link:active lorsque le pointeur est pressé. Lorsqu’aucun de ces états ne s’applique, le composant restaure le style nommé par l’attribut style du lien, ou link lorsque cet attribut est absent.

Messages d’interaction

Les interactions avec les liens utilisent le système d’entrée habituel de Defold. Ajoutez une liaison Mouse Trigger pour MOUSE_BUTTON_LEFT, ce qui active également les entrées tactiles à un doigt, et acquérez le focus d’entrée dans le script de l’objet de jeu ou le script GUI :

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

Consultez Focus d’entrée et Entrées de la souris et tactiles pour les détails de configuration.

Lorsqu’un composant Label ou GUI reçoit des entrées du pointeur, les liens produisent les messages suivants. Les messages des labels sont envoyés à l’objet de jeu auquel ils appartiennent ; les messages GUI sont envoyés au script GUI.

Chaque message contient ces champs :

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

Styles nommés

Chaque collection de polices contient des styles d’objets nommés qui agissent uniquement sur le rendu. Un lien utilise le style nommé par son attribut style, ou link lorsque cet attribut est absent. Il n’existe pas de balise générique <style> pour les portions de texte.

Defold fournit les valeurs par défaut suivantes :

Définissez un style avec une chaîne de texte contenant des balises d’ouverture. Les balises sont implicitement fermées dans l’ordre inverse ; les balises de fermeture et le texte visible ne sont donc pas autorisés.

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

Les balises sont appliquées de gauche à droite, comme si elles étaient imbriquées autour du texte de l’objet. Un style d’objet sélectionné par l’appelant est appliqué après le style par défaut. Lorsque plusieurs balises définissent la même propriété de rendu, la valeur appliquée en dernier remplace les précédentes. Les effets sont ajoutés de gauche à droite.

API des objets de mise en page

Utilisez label.get_layout_objects() ou gui.get_layout_objects() pour récupérer les objets sprite et link du texte mis en page.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Les deux fonctions renvoient un tableau nouvellement créé contenant les objets de mise en page actuels dans l’ordre de la source. Elles renvoient un tableau vide lorsque le texte ne contient aucune balise d’objet. Comme les objets et leurs attributs sont copiés dans Lua à chaque appel, mettez le résultat en cache et interrogez à nouveau après avoir modifié le texte ou une autre propriété qui change sa mise en page.

Champs des objets renvoyés

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

Combinaisons utiles

Contour coloré avec un dégradé horizontal

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

Le dégradé multiplie uniquement la couleur de remplissage ; le contour conserve sa propre couleur.

Faire trembler une phrase et appliquer un dégradé à un mot

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

L’effet de position extérieur s’applique à chaque glyphe. L’effet de couleur imbriqué s’applique uniquement à « whole ».

Remplacer une propriété sans perdre les autres

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

La couleur intérieure modifie le remplissage tout en conservant la largeur et la couleur de contour héritées.