Zengin metin işaretlemesi

İç içe görsel stiller ve efektler uygulamak, bağlantıları ve sprite nesnelerini Lua’dan incelemek için etiket bileşenlerinde (Label component) ve GUI metin düğümlerinde (GUI text node) işaretleme (markup) kullanın.

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

Alternatif olarak, yazı tipinde yeniden kullanılabilir, adlandırılmış bir nesne stili tanımlayın ve bu stili bir bağlantıdan seçin:

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

Etiket başvurusu

Etiket	Amaç	Örnek
color	Glifin (glyph) dolgu rengini ayarlayın.
size	Glif şekillendirme ve yerleşim boyutunu değiştirin.
gradient	Sabit veya animasyonlu bir renk geçişi uygulayın.
ul	Metnin altını çizin.
strike	Metnin üstünü çizin.
outline	Glif dış çizgisinin genişliğini ve rengini ayarlayın.
shadow	Metne gölge ekleyin.
shake	Animasyonlu rastgele bir kaydırma uygulayın.
wave	Metni animasyonlu bir sinüs dalgasıyla hareket ettirin.
sprite	Satır içi bir sprite nesnesi ekleyin.
link	Etkileşimli bir bağlantı nesnesi ekleyin.

Sözdizimi

Etiketler ve öznitelik adları büyük/küçük harfe duyarlıdır. Açılış ve kapanış etiketinden oluşan bir çift, arasındaki görünür UTF-32 metnine uygulanır. Sprite nesneleri kendiliğinden kapanan etiketler kullanır.

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

Öznitelikler

Öznitelikler, boşluk karakteri içermediklerinde tırnaksız yazılabilir ya da tek veya çift tırnak içine alınabilir. color ve size, adlandırılmış value biçiminin yanı sıra kısaltılmış bir ilk değeri de destekler.

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

İç içe yerleştirme

Etiketler son giren ilk çıkar sırasıyla kapatılmalıdır. İçteki stil değerleri, dıştaki stilin aynı özelliğini geçersiz kılar. Farklı özellikler birleşir. Metin aralığı (span) efektleri birbirinden bağımsız olarak etkin kalır; bu nedenle iç içe renk geçişleri renkleri çarpar, iç içe konum efektleri ise kaydırmalarını toplar.

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

Karakter başvuruları

Görünür metindeki ayrılmış karakterler için &, ', >, < ve " kullanın. Sayısal karakter başvuruları şu anda desteklenmez.

Etiketler

Zengin metin etiketleri, çevreledikleri bir metin aralığını biçimlendirir veya Lua’dan incelenebilen bir nesneyi tanımlar. Stil etiketleri eşleşen bir kapanış etiketi kullanır. sprite nesnesi kendiliğinden kapanırken link, bağlantı verilen metni çevreler.

color

Glifin dolgu rengini ayarlar. Renkler #RRGGBB veya #RRGGBBAA biçimini kullanır. Kare işareti öneki zorunludur; 0xFF0000 ve FF0000 geçersizdir. Sonuç, etiketin veya görüntüyü oluşturan işleyicinin (renderer) temel rengiyle çarpılır.

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

size

Yalnızca köşe ölçeğini değil, glif şekillendirme ve yerleşim (layout) boyutunu da değiştirir. Göreli değerler her zaman yerleşimin temel yazı tipi boyutunu kullanır. Çevreleyen bir size etiketinin etkisiyle birleşmezler.

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

gradient

Bir renk geçişi (gradient), eksiksiz olarak belirtilmiş tek bir öznitelik kümesini kabul eder. Kümeleri karıştırmak veya bir üyeyi atlamak geçersizdir.

fit belirtilmediğinde fit=span, renk geçişini etiketlenmiş metnin tamamına dağıtır. fit=glyph, şekillendirilmiş metindeki her konumu bağımsız olarak örnekler. İsteğe bağlı hz, saniyedeki tam akış animasyonu döngülerinin sayısını belirtir; varsayılan sıfır değeri renk geçişini sabit tutar. Yansıtılarak yinelenen renk geçişi sürekli akar ve renk sıçraması olmadan başa döner. Varsayılan direction=forward değeridir; akışı tersine çevirmek için direction=reverse kullanın.

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

Dört köşe

Animasyonlu

Renk geçişinin renkleri geçerli dolgu rengiyle çarpılır. Bu nedenle color=#808080 içindeki bir renk geçişi, bu temel çarpandan daha parlak bir kanal değeri üretemez.

ul

Varsa yazı tipinin alt çizgi ölçülerini kullanarak bir alt çizgi çizer. Etiketin bağımsız bir rengi yoktur: çizgi, yatay, dikey ve dört köşeli renk geçişleri dahil olmak üzere etkin dolgu rengini devralır.

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

strike

Çevrelenen metnin üstünü çizer. pattern için ul ile aynı değerleri kabul eder ve benzer şekilde etkin dolgu rengini devralır.

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

outline

Dış çizgi genişliğini, dış çizgi rengini veya her ikisini ayarlar. En az bir öznitelik zorunludur. Sıfır genişlik, metin aralığı için dış çizgiyi açıkça devre dışı bırakır.

<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

Çevrelenen metne keskin kenarlı bir gölge ekler. En az bir öznitelik zorunludur. İç içe yerleştirilmiş bir etikette belirtilmeyen öznitelikler, çevreleyen gölgenin değerini korur; en dıştaki etikette belirtilmeyen öznitelikler ise yazı tipinin temel gölge değerini korur.

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

shake

Satır kaydırmayı veya yerleşim sınırlarını değiştirmeden, belirlenimci ve animasyonlu rastgele bir kaydırma uygular. Efekt zamanı kendi içinde takip eder; betiklerin her animasyon karesinde etiket metnini değiştirmesi gerekmez.

<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

Satır kaydırmayı veya yerleşim sınırlarını değiştirmeden, karakterleri animasyonlu bir sinüs dalgasıyla yukarı ve aşağı hareket ettirir. Yerleşim, güncellendiğinde animasyon süresini biriktirir.

<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

Görünür metindeki geçerli konuma, kendiliğinden kapanan bir sprite nesnesi ekler. Öznitelikleri, label.get_layout_objects() ve gui.get_layout_objects() için üst veri olarak korunur.

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

Boyutlar, pozitif yalın yerleşim birimlerini, px, em veya % kabul eder. Hem em hem de %, metin yerleşiminin temel yazı tipi boyutunu kullanır.

Belirtilmeyen her boyut, birbirinden bağımsız olarak varsayılan 1em değerini alır. İkisinin de belirtilmemesi 1em × 1em boyutunda bir nesne oluşturur; yalnızca genişliğin belirtilmesi, yüksekliği bir kaynağın en boy oranından otomatik olarak türetmez.

link

Görünür metindeki bir aralığı bağlantı nesnesi olarak tanımlar. Çevrelenen metin normal şekilde yerleştirilir ve varsayılan olarak link adlı stili alır. Etiket ve GUI bileşenleri, metni yeniden şekillendirmeden girdiye yanıt olarak link:hover ve link:active stillerini seçer. Bağlantı girdisinin ürettiği iletiler için Etkileşim iletileri bölümüne bakın.

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

Bileşen, her bağlantının işaretçi durumunu izler. İşaretçi bağlantının üzerindeyken link:hover, işaretçi basılıyken link:active stilini uygular. Bu durumlardan hiçbiri geçerli olmadığında bileşen, bağlantının style özniteliğinde adlandırılan stili veya öznitelik yoksa link stilini geri yükler.

Etkileşim iletileri

Bağlantı etkileşimi, Defold’un normal girdi sistemini kullanır. MOUSE_BUTTON_LEFT için bir Mouse Trigger eşlemesi ekleyin; bu, tek dokunuşlu girdiyi de etkinleştirir. Oyun nesnesinin (game object) betiğinde veya GUI betiğinde girdi odağını (input focus) alın:

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

Kurulum ayrıntıları için Girdi odağı ve Fare ve dokunma girdisi bölümlerine bakın.

Bir etiket veya GUI bileşeni işaretçi girdisi aldığında bağlantılar aşağıdaki iletileri üretir. Etiket iletileri, etiketin sahibi olan oyun nesnesine; GUI iletileri ise GUI betiğine gönderilir.

Her ileti şu alanları içerir:

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

Adlandırılmış stiller

Her yazı tipi koleksiyonu (font collection), yalnızca işlemeyi (rendering), yani görüntü oluşturmayı etkileyen adlandırılmış nesne stilleri içerir. Bir bağlantı, style özniteliğinde adlandırılan stili veya öznitelik yoksa link stilini kullanır. Genel amaçlı bir <style> metin aralığı etiketi yoktur.

Defold aşağıdaki varsayılanları sağlar:

Açılış etiketlerini içeren bir metin dizesiyle stil tanımlayın. Etiketler ters sırayla örtük olarak kapatılır; bu nedenle kapanış etiketlerine ve görünür metne izin verilmez.

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

Etiketler, nesne metninin çevresinde iç içe yerleştirilmiş gibi soldan sağa uygulanır. Çağıran kodun seçtiği nesne stili, varsayılan stilden sonra uygulanır. Birden çok etiket aynı işleme özelliğini ayarladığında, daha sonra uygulanan değer önceki değerleri geçersiz kılar. Efektler soldan sağa sırayla eklenir.

Yerleşim nesnesi API’si

label.get_layout_objects() veya gui.get_layout_objects() kullanarak yerleştirilmiş metindeki sprite ve link nesnelerini alın.

label.get_layout_objects()

objects = label.get_layout_objects(url)

gui.get_layout_objects()

objects = gui.get_layout_objects(node)

Her iki işlev de geçerli yerleşim nesnelerini kaynak sırasıyla içeren, yeni oluşturulmuş bir dizi döndürür. Metin nesne etiketi içermediğinde boş bir dizi döndürürler. Nesneler ve öznitelikleri her çağrıda Lua’ya kopyalandığından, sonucu önbelleğe alın ve metni veya yerleşimini değiştiren başka bir özelliği değiştirdikten sonra yeniden sorgulayın.

Döndürülen nesnenin alanları

Lua örneği

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

Yararlı birleşimler

Yatay renk geçişli, renkli dış çizgi

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

Renk geçişi yalnızca dolgu rengiyle çarpılır; dış çizgi kendi rengini korur.

Bir cümleyi titretme, bir sözcüğe renk geçişi uygulama

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

Dıştaki konum efekti her glife uygulanır. İç içe yerleştirilmiş renk efekti yalnızca “whole” sözcüğüne uygulanır.

Diğerlerini kaybetmeden tek bir özelliği geçersiz kılma

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

İçteki renk, devralınan dış çizgi genişliğini ve rengini korurken dolgu rengini değiştirir.