Rich-Text-Markup

Verwende Markup in Beschriftungskomponenten (Label components) und GUI-Textknoten (GUI text nodes), um verschachtelte visuelle Stile und Effekte anzuwenden und Links und Sprites in Lua zu untersuchen.

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

Alternativ kannst du einen wiederverwendbaren benannten Objektstil für die Schriftressource definieren und ihn in einem Link auswählen:

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

Tag-Referenz

Tag	Zweck	Beispiel
color	Legt die Füllfarbe der Glyphen fest.
size	Ändert die Glyphenformung und die Layoutgröße.
gradient	Wendet einen statischen oder animierten Farbverlauf an.
ul	Unterstreicht Text.
strike	Streicht Text durch.
outline	Legt die Breite und Farbe der Glyphenkontur fest.
shadow	Fügt Text einen Schatten hinzu.
shake	Wendet einen animierten zufälligen Versatz an.
wave	Bewegt Text in einer animierten Sinuswelle.
sprite	Fügt ein Sprite-Objekt in den Textfluss ein.
link	Fügt ein interaktives Link-Objekt hinzu.

Syntax

Bei Tags und Attributnamen wird zwischen Groß- und Kleinschreibung unterschieden. Ein Tag-Paar wirkt auf den darin enthaltenen sichtbaren UTF-32-Text. Sprite-Objekte verwenden selbstschließende Tags.

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

Attribute

Attributwerte dürfen ohne Anführungszeichen stehen, wenn sie keine Leerraumzeichen enthalten, oder in einfachen oder doppelten Anführungszeichen eingeschlossen sein. color und size unterstützen sowohl einen ersten Wert in Kurzschreibweise als auch die benannte Form value.

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

Verschachtelung

Tags müssen in umgekehrter Reihenfolge ihres Öffnens geschlossen werden. Innere Stilwerte überschreiben dieselbe Eigenschaft eines äußeren Stils. Unterschiedliche Eigenschaften werden kombiniert. Effekte auf Textbereiche bleiben unabhängig voneinander aktiv. Verschachtelte Farbverläufe multiplizieren daher ihre Farben, und verschachtelte Positionseffekte addieren ihre Versätze.

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

Entitäten

Verwende &, ', >, < und " für reservierte Zeichen im sichtbaren Text. Numerische Entitäten werden derzeit nicht unterstützt.

Tags

Rich-Text-Tags gestalten entweder einen eingeschlossenen Textbereich oder beschreiben ein Objekt, das in Lua untersucht werden kann. Stil-Tags verwenden ein passendes schließendes Tag. Das Objekt sprite ist selbstschließend, während link den verlinkten Text einschließt.

color

Legt die Füllfarbe der Glyphen fest. Farben verwenden #RRGGBB oder #RRGGBBAA. Das vorangestellte Rautezeichen ist erforderlich; 0xFF0000 und FF0000 sind ungültig. Das Ergebnis multipliziert die Grundfarbe der Beschriftung oder des Renderers.

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

size

Ändert die Glyphenformung und die Layoutgröße, nicht nur die Vertex-Skalierung. Relative Werte beziehen sich immer auf die Basisschriftgröße des Layouts. Sie werden nicht mit einem umschließenden size-Tag verrechnet.

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

gradient

Ein Farbverlauf akzeptiert genau einen vollständigen Attributsatz. Das Mischen von Sätzen oder das Auslassen eines zugehörigen Attributs ist ungültig.

Wenn fit weggelassen wird, verteilt fit=span den Farbverlauf über den gesamten vom Tag eingeschlossenen Text. fit=glyph tastet jede geformte Textposition unabhängig ab. Das optionale Attribut hz gibt die Anzahl vollständiger Durchlaufzyklen der Animation pro Sekunde an; sein Standardwert null hält den Farbverlauf statisch. Die sich wiederholende, gespiegelte Farbskala fließt kontinuierlich und beginnt ohne Farbsprung wieder von vorn. direction=forward ist der Standardwert; verwende direction=reverse, um die Flussrichtung umzukehren.

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

Vier Ecken

Animiert

Die Farben des Farbverlaufs multiplizieren die aktuelle Füllfarbe. Ein Farbverlauf innerhalb von color=#808080 kann daher keinen Farbkanal erzeugen, der heller als dieser Basismultiplikator ist.

ul

Zeichnet eine Unterstreichung anhand der Unterstreichungsmetriken der Schriftart, sofern diese verfügbar sind. Das Tag hat keine eigene Farbe: Die Linie erbt die wirksame Füllfarbe, einschließlich horizontaler und vertikaler Farbverläufe sowie Farbverläufe zwischen vier Ecken.

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

strike

Zeichnet eine Linie durch den eingeschlossenen Text. Akzeptiert dieselben Werte für pattern wie ul und erbt ebenfalls die wirksame Füllfarbe.

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

outline

Legt die Konturbreite, die Konturfarbe oder beides fest. Mindestens ein Attribut ist erforderlich. Eine Breite von null deaktiviert die Kontur für den Textbereich ausdrücklich.

<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

Fügt dem eingeschlossenen Text einen harten Schatten hinzu. Mindestens ein Attribut ist erforderlich. Attribute, die ein verschachteltes Tag auslässt, behalten den Schattenwert des umschließenden Tags bei; Attribute, die das äußerste Tag auslässt, behalten den Basisschattenwert der Schriftart bei.

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

shake

Wendet einen deterministischen animierten zufälligen Versatz an, ohne den Zeilenumbruch oder die Layoutgrenzen zu ändern. Der Effekt verwaltet seine Zeit intern; Skripte müssen den Beschriftungstext nicht für jeden Animationsframe ändern.

<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

Bewegt Zeichen in einer animierten Sinuswelle auf und ab, ohne den Zeilenumbruch oder die Layoutgrenzen zu ändern. Das Layout summiert bei jeder Aktualisierung die Animationszeit.

<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

Fügt an der aktuellen Position im sichtbaren Text ein selbstschließendes Sprite-Objekt ein. Seine Attribute bleiben als Metadaten für label.get_layout_objects() und gui.get_layout_objects() erhalten.

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

Abmessungen akzeptieren positive Layout-Einheiten ohne Suffix sowie px, em oder %. Sowohl em als auch % beziehen sich auf die Basisschriftgröße des Textlayouts.

Jede fehlende Abmessung erhält unabhängig den Standardwert 1em. Werden beide weggelassen, entsteht ein Objekt mit 1em × 1em; wird nur die Breite angegeben, wird die Höhe nicht automatisch aus dem Seitenverhältnis einer Ressource abgeleitet.

link

Beschreibt einen Bereich des sichtbaren Textes als Link-Objekt. Der eingeschlossene Text erhält das normale Layout und standardmäßig den benannten Stil link. Beschriftungs- und GUI-Komponenten wählen als Reaktion auf Eingaben link:hover und link:active aus, ohne den Text erneut zu formen. Unter Interaktionsnachrichten findest du die Nachrichten, die durch Eingaben auf Links erzeugt werden.

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

Die Komponente verfolgt den Zeigerzustand jedes Links. Sie wendet link:hover an, solange sich der Zeiger über dem Link befindet, und link:active, solange die Zeigereingabe gedrückt gehalten wird. Wenn keiner der beiden Zustände zutrifft, stellt die Komponente den im Attribut style des Links benannten Stil wieder her oder link, wenn das Attribut fehlt.

Interaktionsnachrichten

Die Interaktion mit Links verwendet Defolds normales Eingabesystem. Füge unter Mouse Trigger eine Eingabebindung (input binding) für MOUSE_BUTTON_LEFT hinzu, die auch Single-Touch-Eingaben aktiviert, und fordere den Eingabefokus im Skript des Spielobjekts (game object) oder im GUI-Skript an:

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

Einzelheiten zur Einrichtung findest du unter Eingabefokus und Maus- und Touch-Eingaben.

Wenn eine Beschriftungs- oder GUI-Komponente Zeigereingaben empfängt, erzeugen Links die folgenden Nachrichten. Beschriftungsnachrichten werden an das zugehörige Spielobjekt gesendet; GUI-Nachrichten werden an das GUI-Skript gesendet.

Jede Nachricht enthält diese Felder:

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

Benannte Stile

Jede Schriftsammlung (font collection) enthält benannte Objektstile, die ausschließlich das Rendering beeinflussen. Ein Link verwendet den im Attribut style benannten Stil oder link, wenn das Attribut fehlt. Es gibt kein allgemeines <style>-Tag für Textbereiche.

Defold stellt die folgenden Standardwerte bereit:

Definiere einen Stil mit einer Zeichenfolge, die öffnende Tags enthält. Die Tags werden implizit in umgekehrter Reihenfolge geschlossen; schließende Tags und sichtbarer Text sind daher nicht erlaubt.

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

Tags werden von links nach rechts angewendet, als wären sie um den Objekttext verschachtelt. Ein vom Aufrufer ausgewählter Objektstil wird nach dem Standardstil angewendet. Wenn mehrere Tags dieselbe Rendering-Eigenschaft setzen, überschreibt der später angewendete Wert die früheren Werte. Effekte werden in der Reihenfolge von links nach rechts angehängt.

API für Layout-Objekte

Verwende label.get_layout_objects() oder gui.get_layout_objects(), um die Objekte sprite und link aus Text mit berechnetem Layout abzurufen.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Beide Funktionen geben ein neu erstelltes Array mit den aktuellen Layout-Objekten in der Reihenfolge ihres Auftretens im Quelltext zurück. Sie geben ein leeres Array zurück, wenn der Text keine Objekt-Tags enthält. Da die Objekte und ihre Attribute bei jedem Aufruf nach Lua kopiert werden, speichere das Ergebnis zwischen und frage es erneut ab, nachdem du den Text oder eine andere Eigenschaft geändert hast, die sein Layout verändert.

Zurückgegebene Objektfelder

Lua-Beispiel

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

Nützliche Kombinationen

Farbige Kontur mit horizontalem Farbverlauf

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

Der Farbverlauf multipliziert nur die Füllfarbe; die Kontur behält ihre eigene Farbe.

Einen Satz zittern lassen und ein Wort mit einem Farbverlauf versehen

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

Der äußere Positionseffekt wirkt auf jede Glyphe. Der verschachtelte Farbeffekt wirkt nur auf „whole“.

Eine Eigenschaft überschreiben, ohne die anderen zu verlieren

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

Die innere Farbe ändert die Füllung und behält dabei die geerbte Konturbreite und -farbe bei.