Command Palette

Uygulamanın her komutu, adıyla bulunur ve klavyeden çalıştırılır: Cmd+K ya da Ctrl+K'nın açtığı.

import com.pantrixui.components.overlay.commandpalette.PantrixCommandPalette

Modal bir panel. Bir dialog gibi: arkasında bir scrim, odak içinde; geri, Esc ve scrim'e tıklama kapatmak ister. Gösterilip gösterilmediği ekranın durumudur (visible, onDismissRequest); palet kendini kapatmaz. onRun, komut işini yapmadan önce paletin kapatıldığı yerdir.
Üstte durur. Pencerenin üst kısmında, ortada: yazdıkça liste altında kısalır ve uzar, alan yerinde kalır. Telefonda kenar payları kadar geniştir ve klavyenin üstünde biter.
Komutlar. Bir PantrixCommand'ın key'i her dilde aynıdır; label okunan adı, group altında durduğu başlığı, icon önündeki ikonu, shortcut sonundaki kısayolu, keywords onu bulduran başka sözleri, supportingText etiketin altındaki ikinci satırı verir.
Arama. Yazılan her söz etiket, grup, anahtar sözcükler ya da ikinci satırda aranır; büyük küçük harf temanın diline göre karşılaştırılır (Türkçede İ ile i, I ile ı). Grupların sırası korunur, her grubun içinde baştan ve bir sözün başından eşleşenler öne geçer; bulunan harfler kalın yazılır.
Devre dışı. enabled = false olan komut listededir, soluk yazılır; oklar onu atlar ve çalışmaz.
Kısayollar. PantrixShortcut bir tuşu ve onunla basılanları tutar; command Apple'da Command, başka yerde Control'dür. Satırın sonunda sistemin yazdığı gibi yazılır: ⇧⌘K ya da Ctrl+Shift+K. Modifier.onShortcut bir kısayolu, Modifier.commandShortcuts listedeki her komutun kısayolunu bağlar; pencerenin kökündeki Modifier.shortcutRoot hiçbir şey odakta değilken de kısayolların duyulmasını sağlar.
Platform. Panel bir dialog'unkidir, satırlar platformun liste satırı: Android'de 48dp, iOS'ta 44pt, masaüstünde ve web'de 36dp. Masaüstünde ve web'de panel üstten biraz daha aşağıdadır.

Örnekler

Gruplar, kısayollar ve anahtar sözcükler

Bir dosya düzenleyicisinin komutları, gruplarıyla. Düğmeyle açılır; yazdıkça liste daralır, oklarla gezilir, Enter vurgulanan komutu çalıştırır ve palet kapanır. "Sil" şu an çalıştırılamaz: listededir ama oklar onu atlar. "Görünüm"ü "tema" ya da "karanlık" yazarak da bulursun: anahtar sözcükleri bunlardır. İki komutun etiketinin altında ne yaptığını söyleyen ikinci bir satır var (supportingText); arama onu da okur: "adres" yaz.

var open by rememberSaveable { mutableStateOf(false) }
var ran by rememberSaveable { mutableStateOf<String?>(null) }
Column(verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.md)) {
    PantrixButton(text = "Komut paletini aç", onClick = { open = true }, tagKey = "open_editor")
    PantrixText(
        text = "Son çalıştırılan: ${ran ?: "yok"}",
        color = PantrixTheme.colors.textSecondary,
        tagKey = "ran_editor"
    )
}
PantrixCommandPalette(
    visible = open,
    onDismissRequest = { open = false },
    commands = EDITOR_COMMANDS,
    onRun = { command ->
        open = false
        ran = command.label
    },
    tagKey = "editor"
)

private val EDITOR_COMMANDS = listOf(
    PantrixCommand(
        key = "new",
        label = "Yeni dosya",
        group = "Dosya",
        icon = PantrixIcons.Plus,
        shortcut = PantrixShortcut(Key.N, command = true)
    ),
    PantrixCommand(
        key = "open",
        label = "Dosya aç",
        group = "Dosya",
        icon = PantrixIcons.Folder,
        shortcut = PantrixShortcut(Key.O, command = true)
    ),
    PantrixCommand(
        key = "rename",
        label = "Yeniden adlandır",
        group = "Dosya",
        shortcut = PantrixShortcut(Key.R, command = true, shift = true)
    ),
    PantrixCommand(key = "delete", label = "Sil", group = "Dosya", enabled = false),
    PantrixCommand(
        key = "copy",
        label = "Bağlantıyı kopyala",
        group = "Dosya",
        icon = PantrixIcons.Copy,
        keywords = listOf("link", "paylaş"),
        supportingText = "Dosyayı görebilenler için bir adres"
    ),
    PantrixCommand(
        key = "zoom_in",
        label = "Yakınlaştır",
        group = "Görünüm",
        icon = PantrixIcons.ZoomIn,
        shortcut = PantrixShortcut(Key.Equals, command = true)
    ),
    PantrixCommand(
        key = "zoom_out",
        label = "Uzaklaştır",
        group = "Görünüm",
        icon = PantrixIcons.ZoomOut,
        shortcut = PantrixShortcut(Key.Minus, command = true)
    ),
    PantrixCommand(
        key = "appearance",
        label = "Görünüm ayarları",
        group = "Görünüm",
        icon = PantrixIcons.Eye,
        keywords = listOf("tema", "karanlık", "açık"),
        supportingText = "Tema, yazı boyutu, satır aralığı"
    ),
    PantrixCommand(
        key = "search",
        label = "Dosyalarda ara",
        icon = PantrixIcons.Search,
        shortcut = PantrixShortcut(Key.F, command = true, shift = true)
    )
)

Komutların kendi kısayolları

Komutların kendi kısayolları: aynı liste hem paletin gösterdiği hem klavyenin çalıştırdığıdır. Alana yazarken ⌘B ya da Ctrl+B "Kalın"ı, ⌘I ya da Ctrl+I "İtalik"i çalıştırır; harf alana yazılmaz. Odak bu kartın içindeyken duyulurlar: bütün pencere için kökte durmaları gerekir.

var open by rememberSaveable { mutableStateOf(false) }
var ran by rememberSaveable { mutableStateOf<String?>(null) }
val note = rememberTextFieldState()
val run = { command: PantrixCommand -> ran = command.label }
Column(
    modifier = Modifier.fillMaxWidth().commandShortcuts(TEXT_COMMANDS, onRun = run),
    verticalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.md)
) {
    PantrixTextField(
        state = note,
        modifier = Modifier.fillMaxWidth(),
        label = "Not",
        placeholder = "Buraya yaz, sonra ⌘B ya da Ctrl+B",
        tagKey = "note"
    )
    PantrixButton(
        text = "Biçim komutları",
        onClick = { open = true },
        variant = ButtonVariant.Outline,
        tagKey = "open_text"
    )
    PantrixText(
        text = "Son çalıştırılan: ${ran ?: "yok"}",
        color = PantrixTheme.colors.textSecondary,
        tagKey = "ran_text"
    )
}
PantrixCommandPalette(
    visible = open,
    onDismissRequest = { open = false },
    commands = TEXT_COMMANDS,
    onRun = { command ->
        open = false
        run(command)
    },
    tagKey = "text"
)

private val TEXT_COMMANDS = listOf(
    PantrixCommand(
        key = "bold",
        label = "Kalın",
        group = "Biçim",
        shortcut = PantrixShortcut(Key.B, command = true)
    ),
    PantrixCommand(
        key = "italic",
        label = "İtalik",
        group = "Biçim",
        shortcut = PantrixShortcut(Key.I, command = true)
    ),
    PantrixCommand(
        key = "clear",
        label = "Biçimi temizle",
        group = "Biçim",
        shortcut = PantrixShortcut(Key.Backslash, command = true)
    )
)

Kendi sözleri ve kendi renkleri

Paletin kendi sözleri ve kendi renkleri: alanın yer tutucusu ve hiçbir şey eşleşmediğinde yazılan söz çağıranın, vurgulanan satır uygulamanın kendi morunda. "zzz" yazınca boş listenin sözü görünür.

var open by rememberSaveable { mutableStateOf(false) }
val own = ownColors()
PantrixButton(text = "Bir yere git", onClick = { open = true }, variant = ButtonVariant.Outline, tagKey = "open_go")
PantrixCommandPalette(
    visible = open,
    onDismissRequest = { open = false },
    commands = PLACES,
    onRun = { open = false },
    placeholder = "Bir sayfanın adını yaz…",
    emptyText = "Bu adla bir sayfa yok",
    colors = CommandPaletteColors(highlightedContainer = own.container, highlightedContent = own.onContainer),
    tagKey = "go"
)

private val PLACES = listOf(
    PantrixCommand(key = "home", label = "Ana sayfa", icon = PantrixIcons.Inbox),
    PantrixCommand(key = "profile", label = "Profil", icon = PantrixIcons.Person),
    PantrixCommand(key = "favourites", label = "Favoriler", icon = PantrixIcons.Star),
    PantrixCommand(key = "calendar", label = "Takvim", icon = PantrixIcons.Calendar)
)

Kendi stiliyle

Kendi stiliyle: CommandPaletteStyle paletin genişliğini, köşesini ve satırlarını değiştirir. Burada palet en çok 420dp genişlikte, köşeleri orta yuvarlak ve satırları 40dp yüksekliğindedir; verilmeyen her alan platformun ön ayarıdır.

var open by rememberSaveable { mutableStateOf(false) }
PantrixButton(text = "Dar paleti aç", onClick = { open = true }, tagKey = "open_narrow")
PantrixCommandPalette(
    visible = open,
    onDismissRequest = { open = false },
    commands = EDITOR_COMMANDS,
    onRun = { open = false },
    style = CommandPaletteStyle(maxWidth = 420.dp, shape = ShapeRole.Medium, itemHeight = 40.dp, iconGap = 12.dp),
    tagKey = "narrow"
)

private val EDITOR_COMMANDS = listOf(
    PantrixCommand(
        key = "new",
        label = "Yeni dosya",
        group = "Dosya",
        icon = PantrixIcons.Plus,
        shortcut = PantrixShortcut(Key.N, command = true)
    ),
    PantrixCommand(
        key = "open",
        label = "Dosya aç",
        group = "Dosya",
        icon = PantrixIcons.Folder,
        shortcut = PantrixShortcut(Key.O, command = true)
    ),
    PantrixCommand(
        key = "rename",
        label = "Yeniden adlandır",
        group = "Dosya",
        shortcut = PantrixShortcut(Key.R, command = true, shift = true)
    ),
    PantrixCommand(key = "delete", label = "Sil", group = "Dosya", enabled = false),
    PantrixCommand(
        key = "copy",
        label = "Bağlantıyı kopyala",
        group = "Dosya",
        icon = PantrixIcons.Copy,
        keywords = listOf("link", "paylaş"),
        supportingText = "Dosyayı görebilenler için bir adres"
    ),
    PantrixCommand(
        key = "zoom_in",
        label = "Yakınlaştır",
        group = "Görünüm",
        icon = PantrixIcons.ZoomIn,
        shortcut = PantrixShortcut(Key.Equals, command = true)
    ),
    PantrixCommand(
        key = "zoom_out",
        label = "Uzaklaştır",
        group = "Görünüm",
        icon = PantrixIcons.ZoomOut,
        shortcut = PantrixShortcut(Key.Minus, command = true)
    ),
    PantrixCommand(
        key = "appearance",
        label = "Görünüm ayarları",
        group = "Görünüm",
        icon = PantrixIcons.Eye,
        keywords = listOf("tema", "karanlık", "açık"),
        supportingText = "Tema, yazı boyutu, satır aralığı"
    ),
    PantrixCommand(
        key = "search",
        label = "Dosyalarda ara",
        icon = PantrixIcons.Search,
        shortcut = PantrixShortcut(Key.F, command = true, shift = true)
    )
)

API

visible

Uygulamanın her komutu, adıyla bulunur ve klavyeden çalıştırılır: Cmd+K ya da Ctrl+K'nın açtığı.

Parametre	Tür	Varsayılan	Ne olduğu
`visible`	`Boolean`		paletin gösterilip gösterilmediği. Kendini asla gizlemez.
`onDismissRequest`	`() -> Unit`		geri, Escape ve scrim'e tıklama için çağrılır.
`commands`	`List<PantrixCommand>`		her komut, gruplarının altında listelendikleri sırayla. İkisi aynı anahtarı taşımaz.
`onRun`	`(PantrixCommand) -> Unit`		çalıştırılan komutla çağrılır; Enter, klavyenin eylemi ya da bir basışla. Paleti burada kapat.
`modifier`	`Modifier`	`Modifier`	panelin modifier'ı.
`placeholder`	`String?`	`null`	boş alanın gösterdiği, ya da temanın komut aramak için sözleri için null.
`emptyText`	`String?`	`null`	hiçbir şey eşleşmezken listenin yerinde duran, ya da temanın bunun için sözleri için null.
`style`	`CommandPaletteStyle?`	`null`	bu çağrının kendi stili: çevreleyen her stilin üstünde, yoğunluğun altında. Yalnızca verdiği alanlar değişir, her platformda.
`colors`	`CommandPaletteColors?`	`null`	bu paletin temanınkiler olmayan kendi renkleri: burada verilenler, geri kalanlar için temanınkiler.
`tagKey`	`String?`	`null`	paletin otomasyon anahtarı: panel `CommandPalette_<tagKey>`, alanı `CommandPalette_<tagKey>.TextField_query` ve bir komutun satırı `CommandPalette_<tagKey>.Command_<key>` olur. Yapılan bir `CommandPalette` olayı olarak bildirilir: `open`, `via` (`back` ya da `scrim`) ile `dismiss`, ve komutun anahtarı ile `via` (`key` ya da `click`) ile `run`. Yazılan asla bildirilmez.

CommandPaletteStyle

PantrixCommandPalette'in geometrisi: panel, durduğu yer ve listesinin satırları.

Parametre	Tür	Varsayılan	Ne olduğu
`shape`	`ShapeSpec`	`ShapeSpec.Unspecified`	Panelin köşeleri: markanın şekil ölçeğinden bir adım, ya da sabit bir şekil.
`maxWidth`	`Dp`	`Dp.Unspecified`	Panelin geniş bir pencerede büyüyebildiği en geniş hâl.
`maxHeight`	`Dp`	`Dp.Unspecified`	Panelin uzun bir pencerede büyüyebildiği en uzun hâl. Daha dar bir pencere ve klavye onu kısaltır.
`elevation`	`Dp`	`Dp.Unspecified`	Panelin gölgesi. iOS bir paneli yalnızca karartmayla ayırır.
`margin`	`Dp`	`Dp.Unspecified`	Panel ile pencerenin güvenli alanı arasındaki en az boşluk.
`topSpace`	`Dp`	`Dp.Unspecified`	Panelin üstündeki boşluk, `margin`'in ötesinde.
`itemHeight`	`Dp`	`Dp.Unspecified`	Bir komut satırının en az yüksekliği. Daha büyük bir yazı onu uzatır.
`itemHorizontalPadding`	`Dp`	`Dp.Unspecified`	Bir satırın kenarlarıyla içindekiler arasındaki boşluk, bir başlığınki de.
`iconSize`	`Dp`	`Dp.Unspecified`	Bir komutun ikonunun genişliği ve yüksekliği.
`iconGap`	`Dp`	`Dp.Unspecified`	Bir komutun ikonu, etiketi ve kısayolu arasında.

CommandPaletteColors

Bir PantrixCommandPalette'in temanın renkleri yerine boyandığı renkler: verilen bir renk kullanılır, bırakılan temanınki kalır.

Parametre	Tür	Varsayılan	Ne olduğu
`container`	`Color`	`Color.Unspecified`	Panelin dolgusu. Temanın `surface`'ı.
`content`	`Color`	`Color.Unspecified`	Bir komutun etiketi ve ikonu, bir de yazılan. Temanın `textPrimary`'si, ya da `container` olarak verilen bir rol dolgusunun üstünde duranlara verdiği renk.
`highlightedContainer`	`Color`	`Color.Unspecified`	Enter'ın çalıştırdığı komutun arkasındaki dolgu. Birincil rolün `container`'ı.
`highlightedContent`	`Color`	`Color.Unspecified`	O komutun etiketi, ikonu ve kısayolu: `highlightedContainer` üstünde okunan renk. Birincil rolün `onContainer`'ı.
`heading`	`Color`	`Color.Unspecified`	Bir grubun başlığı, bir kısayol ve hiçbir şey eşleşmediğinde listenin yerinde duran. Temanın kendi zeminlerinde `textSecondary`'si, başka bir dolguda `content`.
`scrim`	`Color`	`Color.Unspecified`	Paletin arkasında uygulamanın üstüne serilen karartma, kendi alfasıyla. Temanın `scrim`'i.

Erişilebilirlik

Klavye. Alan odağı tutar; aşağı ve yukarı ok çalıştırılabilen komutlar arasında gider ve uçlarda durur, Page Down ve Page Up bir sayfa atlar, fare üstünden geçtiği satırı vurgular. Enter, klavyenin eylemi ve satıra basmak komutu çalıştırır. Her açılışta alan boştur ve vurgu ilk çalıştırılabilen komuttadır.
Ekran okuyucu. Palet açılınca temanın komut listesi adıyla duyurulur. Vurgulanan satır seçilidir, gruplar başlıktır, kısayol satırın durumu olarak okunur; yazdıkça kaç komut kaldığı söylenir.