Tooltip

Çapalandığı kontrolün adını gösteren kısa bir etiket: bir ikon düğmesinin adı, kesilen bir etiketin tamamı.

import com.pantrixui.components.overlay.tooltip.PantrixTooltip

• Fare. İşaretçi kontrolün üzerinde stilin pointerRestMillis süresi kadar durunca çıkar, ayrılınca gider. İşaretçi etiketin üzerine geçip orada durabilir. Kontrole tıklamak etiketi kaldırır; işaretçi ayrılıp geri gelene kadar yeniden çıkmaz.
• Dokunma. Kontrole uzun basınca çıkar ve bir yere basılana kadar kalır. Adı soran uzun basış kontrole basmaz; kısa dokunuş yalnızca kontrole basar ve etiket çıkarmaz.
• Yön. side etiketin kontrolün hangi yanında duracağını söyler: söylenmezse üstte. Etiket o yanda kontrole ortalanır; yer yoksa karşı yana geçer ve pencerenin kenarlarına stilin margin'inden fazla yaklaşmaz.
• Durum. Etiketin açık olup olmadığı tek bir durumdur (state): fare, klavye ve uzun basış onu değiştirir. Ekran da değiştirebilir: rememberPantrixTooltipState() ile tutar, show() ve dismiss() çağırır.
• Kapatılabilir. enabled = false etiketi kaldırır ve çıkmasını engeller: adı zaten görünen bir kontrol için.
• Kendiliğinden kalkar. Kontrol bir dialog'un, sheet'in ya da açık bir popover'ın altında kalınca, görünür alandan kayıp çıkınca ve pencerenin boyutu değişince etiket kaldırılır.
• Tek etiket. Pencerede aynı anda tek etiket durur: yenisi çıkınca öncekisi gider. Escape, odak nerede olursa olsun açık olan etiketi kaldırır ve başka bir yere gitmez.
• Renkler ve stil. Etiket temanın ters tonundadır: açık temada koyu, koyu temada açık. colors (TooltipColors) kendi rengini; style (TooltipStyle) köşeleri, boşlukları, en çok genişliği ve farenin bekleyişini verir.
• Hangi kontrole. Çapa basılan bir kontroldür, bir düğme ya da bir ikon, ya da yalnızca okunan bir metin. Kendi uzun basışı olan bir kontrol, bir metin alanı ya da seçilebilen bir metin, dokunmatik ekranda o basışı tooltip'e kaptırır.

Örnekler

Araç çubuğu

En yalın hâli: PantrixTooltip adını gösterdiği kontrolü sarar. Yalnızca ikon gösteren dört düğmenin adını tooltip gösterir, ekran okuyucuya contentDescription söyler: ikisi aynı sözcüklerdir.

Fareyle bir düğmenin üzerinde dur, klavyeyle odaklan ya da parmakla uzun bas: adı çıkar. Tıklama ve kısa dokunuş düğmeye basar; adı soran uzun basış basmaz. Kartın "Son olay" satırı en son hangi düğmeye basıldığını söyler.

val report = LocalExampleEvents.current
Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixTooltip(text = "Yenile", tagKey = "refresh") {
        PantrixIconButton(
            imageVector = PantrixIcons.Refresh,
            contentDescription = "Yenile",
            onClick = { report("Yenile düğmesine basıldı") },
            tagKey = "refresh"
        )
    }
    PantrixTooltip(text = "Ara", tagKey = "search") {
        PantrixIconButton(
            imageVector = PantrixIcons.Search,
            contentDescription = "Ara",
            onClick = { report("Ara düğmesine basıldı") },
            tagKey = "search"
        )
    }
    PantrixTooltip(text = "Yakınlaştır", tagKey = "zoom_in") {
        PantrixIconButton(
            imageVector = PantrixIcons.ZoomIn,
            contentDescription = "Yakınlaştır",
            onClick = { report("Yakınlaştır düğmesine basıldı") },
            tagKey = "zoom_in"
        )
    }
    PantrixTooltip(text = "Uzaklaştır", tagKey = "zoom_out") {
        PantrixIconButton(
            imageVector = PantrixIcons.ZoomOut,
            contentDescription = "Uzaklaştır",
            onClick = { report("Uzaklaştır düğmesine basıldı") },
            tagKey = "zoom_out"
        )
    }
}

Yön

side etiketin kontrolün hangi yanında duracağını söyler; etiket o yanda kontrole ortalanır. Söylenmezse üstte durur: PopoverSide.Top. Baş ve Son yazı yönüne göre değişir: soldan sağa bir düzende Baş soldur. İstenen yanda yer yoksa etiket karşı yana geçer.

var side by rememberSaveable { mutableStateOf(PopoverSide.Top) }
PantrixSegmentButton(options = SIDES, selected = side, onSelect = { side = it }, tagKey = "tooltip_side")
Box(modifier = Modifier.fillMaxWidth(), contentAlignment = Alignment.Center) {
    PantrixTooltip(text = "side = ${side.name}", side = side, tagKey = "side") {
        PantrixButton(
            text = "Üzerine gel ya da uzun bas",
            onClick = {},
            variant = ButtonVariant.Outline,
            tagKey = "side_target"
        )
    }
}

private val SIDES = listOf(
    SegmentOption(value = PopoverSide.Top, label = "Üst", tagKey = "top"),
    SegmentOption(value = PopoverSide.Bottom, label = "Alt", tagKey = "bottom"),
    SegmentOption(value = PopoverSide.Start, label = "Baş", tagKey = "start"),
    SegmentOption(value = PopoverSide.End, label = "Son", tagKey = "end")
)

Kesilen etiket

Sütununa sığmadığı için tek satırda kesilen bir dosya adı: tooltip adın tamamını gösterir. Etiket stilin en çok genişliğinden (TooltipStyle.maxWidth) geniş olmaz; uzun ad onda satır atlar.

Çapa burada basılan bir kontrol değil, yalnızca okunan bir metindir: fareyle üzerinde durunca ya da parmakla uzun basınca etiket çıkar.

val fileName = "2026 üçüncü çeyrek satış raporu, kuzey bölgesi, ikinci taslak ve notlar.pdf"
PantrixTooltip(text = fileName, side = PopoverSide.Bottom, tagKey = "file") {
    PantrixText(text = fileName, modifier = Modifier.width(220.dp), maxLines = 1, tagKey = "file_name")
}

Ekranın gösterdiği ipucu

Etiketin açık olup olmadığı bir durumdur ve ekran onu kendisi tutabilir: rememberPantrixTooltipState(). hint.show() etiketi kimse kontrole dokunmadan çıkarır: ilk açılışta bir ipucu, az önce değişen bir kontrolün adı. hint.dismiss() ya da başka bir yere basmak kaldırır.

Fare, klavye ve uzun basış da aynı durumu değiştirir: hint.visible etiketin açık olup olmadığını her zaman doğru söyler.

val hint = rememberPantrixTooltipState()
val report = LocalExampleEvents.current
Row(
    horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm),
    verticalAlignment = Alignment.CenterVertically
) {
    PantrixTooltip(
        text = "Sık kullanılanlara ekle",
        side = PopoverSide.Bottom,
        state = hint,
        tagKey = "favourite"
    ) {
        PantrixIconButton(
            imageVector = PantrixIcons.Star,
            contentDescription = "Sık kullanılanlara ekle",
            onClick = { report("Sık kullanılanlara eklendi") },
            tagKey = "favourite"
        )
    }
    PantrixButton(text = "İpucunu göster", onClick = { hint.show() }, tagKey = "show_hint")
    PantrixButton(text = "Gizle", onClick = { hint.dismiss() }, variant = ButtonVariant.Text, tagKey = "hide_hint")
}

Kapatılabilir

enabled = false iken hiçbir şey etiketi çıkarmaz; açıkken çıkmış olan da kalkar. Adı zaten görünen bir kontrol içindir. Anahtarı aç: düğmenin tooltip'i çalışmaya başlar.

var enabled by rememberSaveable { mutableStateOf(false) }
val report = LocalExampleEvents.current
PantrixSwitchButton(
    checked = enabled,
    onCheckedChange = { enabled = it },
    label = "Bu düğmenin tooltip'i açık",
    tagKey = "tooltip_on"
)
// Tooltip düğmenin adını gösterir, yeni bir şey söylemez: ekran okuyucu düğmeyi okur, etiketi değil.
PantrixTooltip(text = "Kaydet", enabled = enabled, tagKey = "save") {
    PantrixButton(text = "Kaydet", onClick = { report("Kaydet düğmesine basıldı") }, tagKey = "save")
}

Kendi stili

style yalnızca bu tooltip'in geometrisini değiştirir: TooltipStyle'ın verilen alanları değişir, gerisi temanın ve platformun stilinden gelir. İlk düğmenin etiketi fare üzerine gelir gelmez çıkar: pointerRestMillis = 0. İkincisinin etiketi tam yuvarlak köşelidir (ShapeRole.Full), metnin çevresinde daha çok boşluk vardır ve düğmeden 12dp uzakta durur.

pointerRestMillis yalnızca farenin bekleyişidir: klavye odağı etiketi hemen, parmağın uzun basışı platformun uzun basış süresinde çıkarır. Stilin bekleyişi Android'de ve iOS'ta 400, masaüstünde ve web'de 500 milisaniyedir.

Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
    PantrixTooltip(text = "Takvim", style = TooltipStyle(pointerRestMillis = 0), tagKey = "instant") {
        PantrixIconButton(
            imageVector = PantrixIcons.Calendar,
            contentDescription = "Takvim",
            onClick = {},
            tagKey = "instant"
        )
    }
    PantrixTooltip(
        text = "Gelen kutusu",
        style = TooltipStyle(
            shape = ShapeRole.Full,
            horizontalPadding = 16.dp,
            verticalPadding = 8.dp,
            gap = 12.dp
        ),
        tagKey = "roomy"
    ) {
        PantrixIconButton(
            imageVector = PantrixIcons.Inbox,
            contentDescription = "Gelen kutusu",
            onClick = {},
            tagKey = "roomy"
        )
    }
}

Kendi renkleri

Renk verilmeyince etiket temanın ters tonundadır: açık temada koyu, koyu temada açık. colors etikete verilen renkleri verir: burada temanın hiçbir rolünde olmayan, uygulamanın kendi moru. TooltipColors'ın yalnızca verilen alanları değişir.

Rolü olmayan bir dolguda content de verilir: o dolgunun üstünde neyin okunduğunu tema bilmez. Dolgu temanın bir rolünün rengiyse, PantrixTheme.colors.primary.color gibi, metin kendiliğinden o rolün eş rengini alır.

val report = LocalExampleEvents.current
val own = ownColors()
PantrixTooltip(
    text = "Pro özelliği",
    colors = TooltipColors(container = own.color, content = own.onColor),
    tagKey = "own"
) {
    PantrixIconButton(
        imageVector = PantrixIcons.Info,
        contentDescription = "Pro özelliği",
        onClick = { report("Pro özelliği düğmesine basıldı") },
        tagKey = "own"
    )
}

Popover açan düğmede

Popover açan bir düğmenin tooltip'i: PantrixTooltip popover'ın anchor'ının içindedir. Popover açılınca düğme onun altında kalır ve etiket kalkar. Popover kapanınca da geri gelmez: o sırada kimse düğmenin adını sormuyordur.

var open by rememberSaveable { mutableStateOf(false) }
val report = LocalExampleEvents.current
PantrixPopover(
    visible = open,
    onDismissRequest = {
        open = false
        report("Diğer popover'ı kapatıldı")
    },
    anchor = {
        PantrixTooltip(text = "Diğer", tagKey = "more") {
            PantrixIconButton(
                imageVector = PantrixIcons.MoreHorizontal,
                contentDescription = "Diğer",
                onClick = { open = true },
                tagKey = "more"
            )
        }
    },
    side = PopoverSide.Bottom,
    tagKey = "more"
) {
    PantrixText(text = "Yeniden adlandır, taşı ya da sil.")
}

Dialog içinde

Dialog'un içindeki düğmelerin tooltip'i: etiket, dialog'un içindeki kontrolün yanında durur. Dialog klavyeyi kendine alır ve içinde basılan tuş alttaki sayfaya ulaşmaz. Escape yine önce açık etiketi kaldırır; dialog'u bir sonraki Escape kapatır.

var open by rememberSaveable { mutableStateOf(false) }
val report = LocalExampleEvents.current
PantrixButton(
    text = "Dosya ayrıntıları…",
    onClick = { open = true },
    variant = ButtonVariant.Outline,
    tagKey = "file_details"
)
PantrixDialog(
    visible = open,
    onDismissRequest = {
        open = false
        report("Dosya ayrıntıları kapatıldı")
    },
    title = "Rapor.pdf",
    message = "2,4 MB. Dün değiştirildi.",
    actions = {
        PantrixButton(
            text = "Kapat",
            onClick = {
                open = false
                report("Dosya ayrıntıları kapatıldı")
            },
            variant = ButtonVariant.Text,
            tagKey = "close_details"
        )
    },
    tagKey = "file_details"
) {
    Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
        PantrixTooltip(text = "Sık kullanılanlara ekle", tagKey = "file_favourite") {
            PantrixIconButton(
                imageVector = PantrixIcons.Star,
                contentDescription = "Sık kullanılanlara ekle",
                onClick = { report("Sık kullanılanlara ekle düğmesine basıldı") },
                tagKey = "file_favourite"
            )
        }
        PantrixTooltip(text = "Klasöre taşı", tagKey = "file_move") {
            PantrixIconButton(
                imageVector = PantrixIcons.Folder,
                contentDescription = "Klasöre taşı",
                onClick = { report("Klasöre taşı düğmesine basıldı") },
                tagKey = "file_move"
            )
        }
    }
}

Dar yerde ikon, geniş yerde yazı

Yer darken yalnızca ikon, genişken yazılı düğme. Düğme kendi yerini BoxWithPantrixWindow ile öğrenir: dar yerde adını tooltip gösterir; geniş yerde ad düğmenin üzerinde yazar ve tooltip yoktur.

Bu kutu içeriğini ölçerken kurar ve yer bir sınırı geçince eski dalı ölçümün içinde atar. Etiketin katmanı pencerenin kökünde kurulduğu için o sırada açık olsa da bir şey bozulmaz; pencerenin boyutu değişince etiket ayrıca kaldırılır.

val report = LocalExampleEvents.current
BoxWithPantrixWindow(modifier = Modifier.fillMaxWidth()) { box ->
    if (box.isNarrow) {
        PantrixTooltip(text = "Dosyalar", side = PopoverSide.End, tagKey = "files") {
            PantrixIconButton(
                imageVector = PantrixIcons.Folder,
                contentDescription = "Dosyalar",
                onClick = { report("Dosyalar düğmesine basıldı (ikon)") },
                variant = ButtonVariant.Outline,
                tagKey = "files"
            )
        }
    } else {
        PantrixButton(
            text = "Dosyalar",
            onClick = { report("Dosyalar düğmesine basıldı (yazılı)") },
            variant = ButtonVariant.Outline,
            tagKey = "files"
        )
    }
}

Pencere aynıyken daralan yer

Pencere aynı kalırken daralan bir yer: sürüklenen bir bölme ya da kayarak açılan bir kenar çubuğu gibi. Düğmeye bas: kutu üç saniye sonra genişler ya da daralır. O üç saniye içinde ikonun etiketini ya da popover'ı aç: yer değişince onları taşıyan dal atılır, etiket ve popover onunla birlikte gider.

Kutu içeriğini ölçerken kuran bir yerleşimdir (BoxWithConstraints): sınırı geçince içindeki dalı ölçümün içinde atar. Açık bir etiketin ve popover'ın katmanları pencerenin kökünde kurulduğu için dal atılınca bir sonraki karede kapanırlar.

var narrow by rememberSaveable { mutableStateOf(true) }
val report = LocalExampleEvents.current
val scope = rememberCoroutineScope()
PantrixButton(
    text = if (narrow) "3 sn sonra genişlet" else "3 sn sonra daralt",
    onClick = {
        scope.launch {
            delay(3_000L)
            narrow = !narrow
            report(if (narrow) "Yer daraldı" else "Yer genişledi")
        }
    },
    variant = ButtonVariant.Outline,
    tagKey = "room"
)
BoxWithConstraints(modifier = Modifier.width(if (narrow) 140.dp else 300.dp)) {
    if (maxWidth < 220.dp) IconsInTheRoom() else WrittenButtonsInTheRoom()
}

@Composable
private fun IconsInTheRoom() {
    var open by rememberSaveable { mutableStateOf(false) }
    val report = LocalExampleEvents.current
    Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
        PantrixTooltip(text = "Dosyalar", tagKey = "room_files") {
            PantrixIconButton(
                imageVector = PantrixIcons.Folder,
                contentDescription = "Dosyalar",
                onClick = {},
                variant = ButtonVariant.Outline,
                tagKey = "room_files"
            )
        }
        PantrixPopover(
            visible = open,
            onDismissRequest = {
                open = false
                report("Bilgi popover'ı kapatıldı")
            },
            anchor = {
                PantrixIconButton(
                    imageVector = PantrixIcons.Info,
                    contentDescription = "Bilgi",
                    onClick = { open = true },
                    variant = ButtonVariant.Outline,
                    tagKey = "room_info"
                )
            },
            side = PopoverSide.Bottom,
            tagKey = "room_info"
        ) {
            PantrixText(text = "Dar yerdeyiz.")
        }
    }
}

@Composable
private fun WrittenButtonsInTheRoom() {
    var open by rememberSaveable { mutableStateOf(false) }
    val report = LocalExampleEvents.current
    Row(horizontalArrangement = Arrangement.spacedBy(PantrixTheme.spacing.sm)) {
        PantrixButton(text = "Dosyalar", onClick = {}, variant = ButtonVariant.Outline, tagKey = "room_files")
        PantrixPopover(
            visible = open,
            onDismissRequest = {
                open = false
                report("Bilgi popover'ı kapatıldı")
            },
            anchor = {
                PantrixButton(
                    text = "Bilgi",
                    onClick = { open = true },
                    variant = ButtonVariant.Outline,
                    tagKey = "room_info"
                )
            },
            side = PopoverSide.Bottom,
            tagKey = "room_info"
        ) {
            PantrixText(text = "Geniş yerdeyiz.")
        }
    }
}

API

text

Çapalandığı kontrolün adını gösteren kısa bir etiket: bir ikon düğmesinin adı, kesilen bir etiketin tamamı.

TooltipStyle

PantrixTooltip'in geometrisi: etiketin ne kadar büyük olduğu, adını gösterdiği şeyden ne kadar uzakta durduğu, pencerenin kenarlarına ne kadar yaklaştığı ve işaretçinin, tooltip çıkmadan önce bir kontrolün üzerinde ne kadar durduğu.

TooltipColors

Temanın renklerini almayan bir çağrı için bir PantrixTooltip'in boyandığı renkler: verilen renk kullanılır, verilmeyen temanın kalır.

Erişilebilirlik

• Klavye. Odak kontrole klavyeyle gelince hemen çıkar, odak gidince gider. Escape kaldırır, odak kontrolde kalır.