Code Block

Okunmak için dizilmiş kod: temanın kod yazısıyla, her satır kendi satırında, her parçası ne olduğunun renginde ve kopyalanmaya hazır.

import com.pantrixui.components.data.codeblock.PantrixCodeBlock

• İki biçim. code alan biçim bir metni gösterir. lines alan biçim satırları tek tek alır: her satır kendi parçalarını ve kendisi hakkında söyleneni taşır. Bir metnin satırlarını codeLines verir; ekran oradan başlar ve istediği satırı işaretler.
• Parçalar. Sekiz tür parça vardır: düz yazı, yorum, anahtar sözcük, tür, metin, sayı, noktalama ve bir şeyin başına yazılan adlar (@Composable). Renkleri temanın rollerinden gelir; yorum ayrıca eğik yazılır. İki parça aynı harflerin üstündeyse sonra verilen boyar.
• Başlık. Kodun üstünde, söyleyecek bir şey oldukça bir başlık durur: title, çoğu zaman bir dosyanın adı; language, dilin adı; icon; ekranın leading ile başına, trailing ile sonuna koyduğu şey. Kopyalama düğmesi başlığın sonundadır; söyleyecek başka bir şey yoksa başlık da yoktur ve düğme kodun üstünde, kendi şeridinde durur.
• Kopyalama ve seçme. Düğme kodun tamamını kopyalar, ekranda hangi parçası görünüyor olursa olsun. Kopyalayınca iki saniye bir onay işareti gösterir ve bunu ekran okuyucuya da söyler; onCopy kodun panoya ulaşıp ulaşmadığını bildirir. Ekrandaki satırlar da seçilir, fareyle sürükleyerek ya da uzun basarak. copyable = false düğmeyi kaldırır, selectable = false seçmeyi kapatır.
• Satır numaraları. lineNumbers her satırın başına numarasını yazar; firstLineNumber ilk satırın numarasını verir: bir dosyadan alınmış bir parça, orada başladığı yerden başlar. Numaralar seçilmez ve ekran okuyucuya okunmaz.
• Yana kayma. Bloğa sığmayan satır bölünmez: kod yana kayar, satır numaraları yerinde durur. Girintisi kaybolan bir kod satırı okunmaz.
• Bölünen satırlar. softWrap ile uzun satır kendi altında sürer: sütunlardan çok sözcüklerin önemli olduğu dar bir ekran için.
• Yükseklik. Yükseklik verilen blokta kod o yüksekliğin içinde, yerinde duran başlığın altında kayar ve yalnızca ekrandaki satırlar kurulur. Yükseklik verilmeyen blok, kayan bir sayfada, 300 satırı geçmiyorsa satırları kadar yüksektir; daha uzun kodda pencereden yüksek olmaz ve onun içinde kayar.
• Kaydırma çubukları. Kaydığı yerde bloğun kendi çubuğu vardır: yan kenarında, yana kayan kodda alt kenarında da. İmleci olan okuyucuda kayacak bir şey oldukça durur ve fareyle sürüklenir; parmağın altında yalnızca kod kayarken görünür.
• Satır işaretleri. Bir satırın işareti (CodeMark) satırın arkasına tonunun rolünün yumuşak dolgusunu, sol kenarına rolün renginde bir çubuk çizer; message verilirse mesaj satırın altında durur. Altı ton vardır: Primary, Info, Success, Warning, Danger ve Neutral. İşaretli satırın tamamı, temanın o dolguyla eşlediği tek renkle yazılır.
• Kodun yazısı. textStyle kodu temanın code'undan başka bir stille yazar: bir telefonun sayfasında daha küçük.
• Yazı yönü. Kod her dilde soldan sağa yazılır; başlık ve bir işaretin mesajı uygulamanın yönündedir.
• Renk. Temanın kendi zeminlerinde her tür parçanın kendi rengi vardır. Temanın bir rol renginin üstünde kodun tamamı orada okunan tek renkle yazılır. CodeBlockColors ile verilen renk kullanılır, verilmeyen temanınki kalır.
• Platform. Kod satırları sık durur: içlerinde basılan bir şey yoktur. Temanın kod yazısıyla bir satır 20dp'dir; Android yazının üstünde ve altında 2dp, iOS 1dp bırakır, masaüstü ve web hiç bırakmaz. Köşeler kartınkilerdir.
• Otomasyon. tagKey ile blok CodeBlock_<tagKey>, bir satırı CodeBlock_<tagKey>.Line_<number>, bir satırın altındaki mesaj CodeBlock_<tagKey>.Note_<number>, klavyenin kaydırdığı pencere CodeBlock_<tagKey>.Lines_window, kopyalama düğmesi CodeBlock_<tagKey>.Button_copy olur. Bir kopyalama, panoya ulaşıp ulaşmadığıyla, copy olarak bildirilir. Koddan hiçbir şey bildirilmez.

Örnekler

Bir kod parçası

En yalın hâli: bir kod metni, onu renklendiren parçalar ve dilin adı. Blok dili bilmez; neyin anahtar sözcük, neyin metin, neyin yorum olduğunu tokens söyler. Burada onları uygulamanın kendi Kotlin okuyucusu verir.

Anahtar sözcükler temanın primary, türler info, metinler success, sayılar warning, @ ile başlayan adlar danger rolünün rengindedir; yorum textSecondary ile ve eğik yazılır. Başlıktaki düğme kodun tamamını kopyalar ve iki saniye bir onay işareti gösterir.

PantrixCodeBlock(
    code = GREETING,
    tokens = remember { kotlinTokens(GREETING) },
    language = "Kotlin",
    tagKey = "snippet"
)

private val GREETING =
    """
    @Composable
    fun Greeting(name: String) {
        // The greeting a new account is met with.
        val unread = 3
        PantrixText(text = "Hello, " + name + ": " + unread + " new messages")
    }
    """.trimIndent()

Bir dosya, kendi yüksekliğinde

Bir dosya: title adını, icon başındaki ikonu, lineNumbers satır numaralarını verir. Bloğa bir yükseklik verildi: kod onun içinde, yerinde duran başlığın altında kayar ve yalnızca ekrandaki satırlar kurulur.

Sığmayan satır bölünmez. Kodu yana kaydır: satır numaraları yerinde durur, satırlar onların altından geçer. İmleci olan bir ekranda bloğun iki kaydırma çubuğu da görünür ve fareyle sürüklenir; Tab ile satırlara gelince ok tuşları kodu kaydırır.

PantrixCodeBlock(
    code = REPOSITORY,
    modifier = Modifier.height(220.dp),
    tokens = remember { kotlinTokens(REPOSITORY) },
    title = "OrderRepository.kt",
    language = "Kotlin",
    icon = PantrixIcons.Folder,
    lineNumbers = true,
    tagKey = "file"
)

private val REPOSITORY =
    """
    package com.example.orders

    import kotlinx.coroutines.flow.Flow
    import kotlinx.coroutines.flow.map

    /** Reads the orders of an account, newest first. */
    class OrderRepository(private val api: OrderApi, private val cache: OrderCache, private val clock: Clock) {
        fun orders(account: String): Flow<List<Order>> = cache.observe(account).map { it.sortedBy(Order::placedAt) }

        suspend fun refresh(account: String) {
            val fresh = api.orders(account, since = cache.newest(account))
            cache.put(account, fresh, at = clock.now())
        }

        suspend fun cancel(order: Order): Boolean {
            if (order.shipped) return false
            api.cancel(order.id)
            cache.remove(order.id)
            return true
        }
    }
    """.trimIndent()

Bir bulgu, ilgili satırın altında

Bir inceleme: bulgu, hakkında olduğu satırın altında durur. lines alan biçimde her satır kendi işaretini taşır; codeLines metnin satırlarını verir, ekran istediğini işaretler. Bir işaret satırın arkasına tonunun rolünün yumuşak dolgusunu, sol kenarına rolün renginde bir çubuk çizer; message satırın altında, tonun ikonundan sonra yazılır ve source sonunda durur.

İşaretli satır, temanın o dolguyla eşlediği tek renkle yazılır. firstLineNumber parçanın dosyada başladığı yeri verir: bulgunun satırı dosyadaki numarasını taşır.

val lines = remember {
    codeLines(REVIEWED, kotlinTokens(REVIEWED)).mapIndexed { index, line ->
        when (index) {
            1 -> {
                line.copy(
                    mark = CodeMark(
                        tone = CodeTone.Danger,
                        message = "Jeton burada boş olabilir; `!!` uygulamayı çökertir.",
                        source = "kotlin:S2259"
                    )
                )
            }

            4 -> {
                line.copy(mark = CodeMark(CodeTone.Warning, message = "Süre sabiti bir ada alınmalı."))
            }

            else -> {
                line
            }
        }
    }
}
PantrixCodeBlock(
    lines = lines,
    title = "AuthRepository.kt",
    lineNumbers = true,
    firstLineNumber = 41,
    tagKey = "finding"
)

private val REVIEWED =
    """
    suspend fun token(): String {
        val cached = cache.token!!
        if (cached.isFresh()) return cached.value
        val fresh = api.refresh(cached.refreshToken)
        cache.keep(fresh, seconds = 3600)
        return fresh.value
    }
    """.trimIndent()

Eklenen ve çıkarılan satırlar

Mesajı olmayan bir işaret yalnızca bir banttır: iki sürümün farkında eklenen satırlar Success, çıkarılanlar Danger tonunda. Bandın ne demek olduğunu burada satırın başındaki + ve - de söyler: bir renk, onu göremeyene bir şey söylemez.

val lines = remember {
    codeLines(CHANGES, kotlinTokens(CHANGES)).map { line ->
        when {
            line.text.startsWith("+") -> line.copy(mark = CodeMark(CodeTone.Success))
            line.text.startsWith("-") -> line.copy(mark = CodeMark(CodeTone.Danger))
            else -> line
        }
    }
}
PantrixCodeBlock(lines = lines, title = "Greeting.kt", tagKey = "changes")

private val CHANGES =
    """
      @Composable
      fun Greeting(name: String) {
    -     PantrixText(text = "Hello")
    +     PantrixText(text = "Hello, " + name)
    +     PantrixDivider()
      }
    """.trimIndent()

Bir kılavuzun adımları

İşaretler ekranın verisidir: bir kılavuzun hangi adımında olunduğu değişince başka satırlar öne çıkar. Burada her adım kendi satırlarını Primary tonuyla işaretler; adımı değiştir, bant öteki satırlara geçer.

var step by remember { mutableIntStateOf(0) }
val lines = remember(step) {
    codeLines(GREETING, kotlinTokens(GREETING)).mapIndexed { index, line ->
        if (index in STEP_LINES[step]) line.copy(mark = CodeMark(CodeTone.Primary)) else line
    }
}
PantrixSegmentButton(
    options = STEPS,
    selected = step,
    onSelect = { step = it },
    fullWidth = false,
    tagKey = "step"
)
PantrixCodeBlock(lines = lines, lineNumbers = true, copyable = false, tagKey = "steps")

private val STEPS = listOf(
    SegmentOption(value = 0, label = "1. İmza", tagKey = "signature"),
    SegmentOption(value = 1, label = "2. Durum", tagKey = "state"),
    SegmentOption(value = 2, label = "3. Çizim", tagKey = "drawing")
)

private val STEP_LINES = listOf(0..1, 3..3, 4..4)

private val GREETING =
    """
    @Composable
    fun Greeting(name: String) {
        // The greeting a new account is met with.
        val unread = 3
        PantrixText(text = "Hello, " + name + ": " + unread + " new messages")
    }
    """.trimIndent()

Bölünen satırlar

Uzun bir komut. softWrap ile satır bloğa sığmadığı yerde kendi altında sürer ve blok yana kaymaz; kapalıyken komut tek satırdır ve kod yana kayar. Anahtarı çevir, ikisini karşılaştır.

Bölünen bir satır girintisini kaybeder: softWrap bir komut ya da bir günlük satırı için iyidir, girintisi anlam taşıyan kod için değil.

var wraps by remember { mutableStateOf(true) }
PantrixSwitchButton(
    checked = wraps,
    onCheckedChange = { wraps = it },
    label = "Uzun satır kendi altında sürsün",
    tagKey = "code_wraps"
)
PantrixCodeBlock(code = COMMAND, softWrap = wraps, language = "Shell", tagKey = "command")

private val COMMAND =
    "./gradlew :ui:components:jvmTest --tests 'com.pantrixui.components.CodeBlockTest' --offline --console=plain"

Kopyalama ve başlığın sonu

onCopy düğmeye basıldıktan sonra, kodun panoya ulaşıp ulaşmadığıyla çağrılır: bunu kendi yoluyla söyleyen ekran burayı dinler. trailing başlığın sonuna, kopyalama düğmesinden önce ekranın kendi şeyini koyar: burada satır sayısı.

İkinci blokta copyable ve selectable kapalı, başlıkta duracak başka bir şey de yok: başlığı yoktur ve kod seçilmez.

val report = LocalExampleEvents.current
PantrixCodeBlock(
    code = DEPENDENCIES,
    title = "build.gradle.kts",
    onCopy = { copied -> report(if (copied) "Kod panoya kopyalandı" else "Kod panoya kopyalanamadı") },
    trailing = { PantrixText(text = "4 satır", style = PantrixTheme.typography.caption) },
    tagKey = "copied"
)
PantrixCodeBlock(code = DEPENDENCIES, selectable = false, copyable = false, tagKey = "plain")

private val DEPENDENCIES =
    """
    dependencies {
        implementation("com.pantrixui:foundation:0.1.0")
        implementation("com.pantrixui:components:0.1.0")
    }
    """.trimIndent()

Başlıkta sekmeler

leading başlığın başına, ikondan ve başlıktan önce ekranın kendi şeyini koyar: burada aynı satırın iki biçimi arasında seçen iki sekme, bir belgelemenin kurulum adımındaki gibi. Başlığın yazı renginde yazılırlar.

textStyle kodu temanın code'undan başka bir stille yazar: burada caption boyunda, kodun ailesiyle, dar bir sütun için. style'ın headerLineWidth'i başlığın altındaki çizginin kalınlığıdır; headerHorizontalPadding başlıktakileri kenara satırlardan daha yakın durdurur.

var form by remember { mutableIntStateOf(0) }
val code = FORMS[form].second
val type = PantrixTheme.typography
PantrixCodeBlock(
    code = code,
    tokens = remember(code) { kotlinTokens(code) },
    style = CodeBlockStyle(headerLineWidth = 2.dp, headerHorizontalPadding = PantrixTheme.spacing.xs),
    leading = {
        FORMS.forEachIndexed { index, (name, _) ->
            PantrixButton(
                text = name,
                onClick = { form = index },
                variant = if (index == form) ButtonVariant.Soft else ButtonVariant.Text,
                size = ButtonSize.Small,
                tagKey = "form_$index"
            )
        }
    },
    textStyle = type.caption.copy(fontFamily = type.code.fontFamily),
    tagKey = "tabs"
)

private val FORMS = listOf(
    "Kotlin" to """implementation("com.pantrixui:components:0.1.0")""",
    "Groovy" to """implementation 'com.pantrixui:components:0.1.0'"""
)

Bir kartın içinde, kendi renkleriyle

Bloğun kendi dolgusu ve kenarı vardır: dolgu temanın surface'ı, kenar temanın divider'ıdır. İkisi de olan bir kartın içinde colors ikisini de saydam verir. Verilen renk kullanılır, verilmeyen temanınki kalır.

style bloğun geometrisini değiştirir; yalnızca verilen alanlar değişir. Burada satırlar kartın iç boşluğunun bittiği yerden başlasın diye horizontalPadding sıfır verildi.

PantrixCard(modifier = Modifier.fillMaxWidth(), variant = CardVariant.Outlined) {
    PantrixText(text = "Kurulum", style = PantrixTheme.typography.title)
    PantrixCodeBlock(
        code = DEPENDENCIES,
        tokens = remember { kotlinTokens(DEPENDENCIES) },
        style = CodeBlockStyle(horizontalPadding = 0.dp),
        colors = CodeBlockColors(container = Color.Transparent, border = Color.Transparent),
        tagKey = "in_a_card"
    )
}

private val DEPENDENCIES =
    """
    dependencies {
        implementation("com.pantrixui:foundation:0.1.0")
        implementation("com.pantrixui:components:0.1.0")
    }
    """.trimIndent()

Elle yazılan parçalar

Blok bir dil okuyucusu taşımaz; parçaları uygulama verir. Okuyucusu olmayan kısa bir metnin parçaları elle de yazılır: her CodeToken satırdaki bir aralığın (start'tan end'e) ne olduğudur (CodeTokenKind). Burada bir kabuk komutunun satırları doğrudan CodeLine olarak kuruldu: yorum Comment, komut Keyword, görev StringLiteral, seçenek Type.

PantrixCodeBlock(lines = SHELL_LINES, language = "Shell", tagKey = "hand_tokens")

private val SHELL_LINES = listOf(
    CodeLine(text = "# Masaüstü demosunu çalıştır", tokens = listOf(CodeToken(0, 28, CodeTokenKind.Comment))),
    CodeLine(
        text = "./gradlew :app:desktopApp:run --offline",
        tokens = listOf(
            CodeToken(0, 9, CodeTokenKind.Keyword),
            CodeToken(10, 29, CodeTokenKind.StringLiteral),
            CodeToken(30, 39, CodeTokenKind.Type)
        )
    )
)

API

code

Okunmak için dizilmiş kod: temanın kod yazısıyla, her satır kendi satırında, her parçası ne olduğunun renginde ve kopyalanmaya hazır.

lines

Satırları tek tek verilen PantrixCodeBlock; her satır kendisi hakkında söyleneni taşır: bakılacak bir satırın arkasındaki bant, eklenen ve çıkarılan satırlar, hakkında olduğu satırın altında mesajıyla bir bulgu.

CodeBlockStyle

PantrixCodeBlock'un geometrisi: satırlarının çevresindeki boşluk, başlığı, satırlar numaralıyken kodun önündeki yer ve kenar.

CodeBlockColors

Temanın renklerini almayan bir blok için PantrixCodeBlock'un renkleri: verilen renk kullanılır, verilmeyen temanınki kalır.

Erişilebilirlik

• Klavye. İmlecin olduğu yerde, kayacak bir şey varken satırlar Tab için bir duraktır. Odak oradayken ok tuşları bir satır ve, yana, bir adım kaydırır; Page Up ve Page Down bir ekran; Home ve End ilk ve son satıra gider.
• Ekran okuyucu. Kod satır satır okunur; satır numaraları geçilir. Bir işaretin mesajı satırından sonra, tek bir şey olarak okunur.