リッチテキストマークアップ

Label コンポーネント（component）と GUI テキストノードでマークアップを使うと、入れ子の視覚スタイルやエフェクトを適用し、Lua からリンクやスプライトを調べられます。

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

または、フォントに再利用できる名前付きオブジェクトスタイルを定義して、リンクから選択できます。

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

タグリファレンス

タグ	用途	例
color	グリフの塗りの色を設定します。
size	グリフの字形形成とレイアウトのサイズを変更します。
gradient	静的またはアニメーションするカラーグラデーションを適用します。
ul	テキストに下線を引きます。
strike	テキストに取り消し線を引きます。
outline	グリフの輪郭の幅と色を設定します。
shadow	テキストに影を追加します。
shake	アニメーションするランダムなオフセットを適用します。
wave	正弦波のアニメーションでテキストを動かします。
sprite	インラインのスプライトオブジェクトを追加します。
link	操作に反応するリンクオブジェクトを追加します。

構文

タグ名と属性名では大文字と小文字が区別されます。対になったタグは、その内側の表示される UTF-32 テキストに適用されます。スプライトオブジェクトには自己終了タグを使います。

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

属性

属性値に空白が含まれていなければ引用符を省略できます。単一引用符または二重引用符で囲むこともできます。color と size では、名前付きの value 形式に加えて、最初の値を省略形で指定できます。

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

入れ子

タグは、後から開いたものから順に閉じる必要があります。内側のスタイルの値は、外側のスタイルの同じプロパティを上書きします。異なるプロパティは組み合わされます。スパンのエフェクトはそれぞれ独立して有効なため、入れ子のグラデーションは色を乗算し、入れ子の位置エフェクトはオフセットを加算します。

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

実体参照

表示するテキスト内の予約文字には &、'、>、<、" を使います。数値文字参照は現在サポートされていません。

タグ

リッチテキストのタグは、囲んだテキストの範囲（スパン）にスタイルを適用するか、Lua から調べられるオブジェクトを記述します。スタイルタグには対応する終了タグを使います。sprite オブジェクトは自己終了形式で、link はリンクするテキストを囲みます。

color

グリフの塗りの色を設定します。色には #RRGGBB または #RRGGBBAA を使います。先頭のハッシュ記号は必須で、0xFF0000 と FF0000 は無効です。結果はラベルまたはレンダラーの基本色に乗算されます。

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

size

頂点のスケールだけでなく、グリフの字形形成とレイアウトのサイズを変更します。相対値には常にレイアウトの基本フォントサイズを使います。外側の size タグと累積して計算されることはありません。

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

gradient

グラデーションには、完全な属性セットをちょうど1つ指定します。複数のセットを混在させたり、セット内の属性を省略したりすると無効です。

fit を省略すると、fit=span によりタグで囲まれたテキスト全体にグラデーションが分布します。fit=glyph は字形形成後のテキストの各位置を独立してサンプリングします。省略可能な hz は、流れるアニメーションの1秒当たりの完全な周期数を指定します。既定値のゼロではグラデーションは静止します。鏡像として繰り返す色の変化が連続して流れ、色の飛びなしに折り返します。既定値は direction=forward です。流れを逆にするには direction=reverse を使います。

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

四隅

アニメーション

グラデーションの色は現在の塗りの色に乗算されます。そのため、color=#808080 の内側にあるグラデーションは、この基本乗算値より明るい色成分を生成できません。

ul

フォントの下線メトリクスが利用できる場合は、それを使って下線を描画します。このタグ自体に独立した色はありません。線は、水平方向、垂直方向、四隅のグラデーションを含め、適用後の塗りの色を継承します。

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

strike

囲まれたテキストに取り消し線を描画します。ul と同じ pattern 値を受け取り、同様に適用後の塗りの色を継承します。

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

outline

輪郭の幅、色、またはその両方を設定します。少なくとも1つの属性が必須です。幅をゼロにすると、そのスパンの輪郭が明示的に無効になります。

<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

囲まれたテキストに硬い影を追加します。少なくとも1つの属性が必須です。入れ子のタグで省略した属性は外側の影の値を保持し、一番外側のタグで省略した属性はフォントの基本の影の値を保持します。

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

shake

改行位置やレイアウトの境界を変えずに、決定論的にアニメーションするランダムなオフセットを適用します。エフェクトが内部で時間を管理するため、スクリプトでアニメーションの各フレームごとにラベルのテキストを変更する必要はありません。

<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

改行位置やレイアウトの境界を変えずに、正弦波のアニメーションで文字を上下に動かします。レイアウトは更新時にアニメーション時間を累積します。

<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

表示されるテキストの現在位置に、自己終了形式のスプライトオブジェクトを追加します。その属性は label.get_layout_objects() と 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/>

寸法には、正の数値のみのレイアウト単位、px、em、% を指定できます。em と % はどちらもテキストレイアウトの基本フォントサイズを使います。

省略した寸法はそれぞれ独立して 1em になります。両方を省略すると 1em × 1em のオブジェクトになります。幅だけを指定しても、リソースのアスペクト比から高さが自動的に計算されることはありません。

link

表示されるテキストの範囲をリンクオブジェクトとして記述します。囲まれたテキストは通常どおりレイアウトされ、既定では名前付きの link スタイルが適用されます。Label コンポーネントと GUI コンポーネントは、テキストの字形形成をやり直さずに、入力に応じて link:hover と link:active を選択します。リンクへの入力が生成するメッセージについては、操作メッセージを参照してください。

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

コンポーネントは各リンクのポインター状態を追跡します。ポインターがリンク上にある間は link:hover を、ポインターを押している間は link:active を適用します。どちらの状態にも該当しなくなると、リンクの style 属性で指定された名前のスタイルに戻します。属性がなければ link に戻します。

操作メッセージ

リンクの操作には Defold の通常の入力システムを使います。MOUSE_BUTTON_LEFT の Mouse Trigger バインディングを追加します。これによりシングルタッチ入力も有効になります。続いて、ゲームオブジェクト（game object）のスクリプトまたは GUI スクリプトで入力フォーカスを取得します。

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

設定の詳細は、入力フォーカスとマウスとタッチ入力を参照してください。

ラベルまたは GUI コンポーネントがポインター入力を受け取ると、リンクは以下のメッセージを生成します。ラベルのメッセージはそのラベルを所有するゲームオブジェクトに送信され、GUI のメッセージは GUI スクリプトに送信されます。

各メッセージには以下のフィールドが含まれます。

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

名前付きスタイル

各フォントコレクションには、描画だけに作用する名前付きオブジェクトスタイルが含まれます。リンクは style 属性で指定した名前のスタイルを使い、属性がなければ link を使います。汎用の <style> スパンタグはありません。

Defold には以下の既定値があります。

開始タグを含むテキスト文字列でスタイルを定義します。タグは逆順に暗黙的に閉じられるため、終了タグや表示されるテキストを含めることはできません。

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

タグは、オブジェクトのテキストを入れ子で囲むように、左から右へ適用されます。呼び出し元が選択したオブジェクトスタイルは既定のスタイルの後に適用されます。複数のタグが同じ描画プロパティを設定する場合、後から適用した値が前の値を上書きします。エフェクトは左から右の順序で追加されます。

レイアウトオブジェクト API

label.get_layout_objects() または gui.get_layout_objects() を使うと、レイアウト済みのテキストから sprite オブジェクトと link オブジェクトを取得できます。

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

どちらの関数も、現在のレイアウトオブジェクトをソース内の順序で格納した新しい配列を返します。テキストにオブジェクトタグが含まれていなければ、空の配列を返します。呼び出すたびにオブジェクトとその属性が Lua にコピーされるため、結果をキャッシュし、テキストやレイアウトに影響する別のプロパティを変更した後で再取得してください。

返されるオブジェクトのフィールド

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

便利な組み合わせ

色付きの輪郭と水平方向のグラデーション

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

グラデーションは塗りの色だけに乗算されます。輪郭は自身の色を保持します。

文を震わせ、1つの単語にグラデーションを付ける

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

外側の位置エフェクトはすべてのグリフに適用されます。入れ子の色エフェクトは「whole」だけに適用されます。

他のプロパティを保持したまま1つのプロパティを上書きする

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

内側の色は、継承した輪郭の幅と色を保持しながら、塗りを変更します。