İpucu

Bir düğmeye veya başka bir kullanıcı arayüzü öğesine bağlam eklemek için ipuçlarını kullanın. İki tür ipucu vardır:

  • Düz ipuçları: Simge düğmelerin öğelerini veya işlemlerini açıklar.
  • Zengin ipuçları: Bir özelliğin değerini açıklama gibi daha fazla ayrıntı sağlar. İsteğe bağlı olarak başlık, bağlantı ve düğmeler de içerebilir.
(1) etiketli tek satırlık düz ipucu ve (2) etiketli başlık ve bilgi bloğu içeren çok satırlık zengin ipucu.
1. Şekil. Düz bir ipucu (1) ve zengin bir ipucu (2).

API yüzeyi

Uygulamanızda ipuçları uygulamak için TooltipBox composable'ını kullanabilirsiniz. TooltipBox görünümünü şu ana parametrelerle kontrol edersiniz:

  • positionProvider: İpucunu, bağlantı içeriğine göre yerleştirir. Genellikle TooltipDefaults konum sağlayıcısını kullanırsınız veya özel konumlandırma mantığına ihtiyacınız varsa kendi konum sağlayıcınızı kullanabilirsiniz.
  • tooltip: İpucu içeriğini içeren composable. Genellikle PlainTooltip veya RichTooltip composable'larını kullanırsınız.
    • Simge düğmelerinin öğelerini veya işlemlerini açıklamak için PlainTooltip kullanın.
    • RichTooltip kullanarak bir özelliğin değerini açıklama gibi daha fazla ayrıntı sağlayın. Zengin ipuçları isteğe bağlı olarak başlık, bağlantı ve düğmeler içerebilir.
  • state: Bu ipucu için kullanıcı arayüzü mantığını ve öğe durumunu içeren durum tutucu.
  • content: İpucunun sabitlendiği birleştirilebilir içerik.

Düz bir ipucu görüntüleme

Bir kullanıcı arayüzü öğesini kısaca açıklamak için düz bir ipucu kullanın. Bu kod snippet'i, "Favorilere ekle" etiketli bir simge düğmesinin üzerinde düz bir ipucu görüntüler:

@Composable
fun PlainTooltipExample(
    modifier: Modifier = Modifier,
    plainTooltipText: String = "Add to favorites"
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberPlainTooltipPositionProvider(),
        tooltip = {
            PlainTooltip { Text(plainTooltipText) }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Do something... */ }) {
            Icon(
                imageVector = Icons.Filled.Favorite,
                contentDescription = "Add to favorites"
            )
        }
    }
}

Tooltips.kt

Kodla ilgili önemli noktalar

  • TooltipBox, "Favorilere ekle" metnini içeren bir ipucu oluşturur.
  • IconButton simge içeren tıklanabilir bir düğme oluşturur.
    • Icon(...) düğmesinde kalp simgesi gösterilir.
    • Kullanıcı IconButton ile etkileşime girdiğinde TooltipBox, "Favorilere ekle" metnini içeren ipucunu gösterir. Kullanıcılar, cihaza bağlı olarak aşağıdaki yöntemlerle ipucunu tetikleyebilir:
    • İmleçle simgenin üzerine gelme
    • Mobil cihazda simgeye uzun basma

Sonuç

Bu örnek, bir simgenin üzerinde düz bir ipucu oluşturur:

Metni içeren tek satırlık ipucu
Şekil 2. Kullanıcı, kalp simgesinin üzerine geldiğinde veya simgeye uzun bastığında görünen düz bir ipucu.

Zengin araç ipucu görüntüleme

Bir kullanıcı arayüzü öğesi hakkında ek bağlam sağlamak için zengin ipucu kullanın. Bu örnekte, Icon öğesine sabitlenmiş bir başlığa sahip çok satırlı bir zengin ipucu oluşturuluyor:

@Composable
fun RichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text."
) {
    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) }
            ) {
                Text(richTooltipText)
            }
        },
        state = rememberTooltipState()
    ) {
        IconButton(onClick = { /* Icon button's click event */ }) {
            Icon(
                imageVector = Icons.Filled.Info,
                contentDescription = "Show more information"
            )
        }
    }
}
Tooltips.kt

Kodla ilgili önemli noktalar

  • TooltipBox, kullanıcı etkileşimleriyle ilgili etkinlik işleyicilerini yönetir ve TooltipState buna göre güncellemeler yapar. TooltipState, ipucunun gösterilmesi gerektiğini belirttiğinde ipucu lambdası yürütülür ve TooltipBox, RichTooltip öğesini gösterir. TooltipBox, hem içerik hem de ipucu için bağlantı ve kapsayıcı görevi görür.
    • Bu durumda, içerik, dokunma işlemi davranışını sağlayan bir IconButton bileşenidir. TooltipBox içeriğinde herhangi bir yerde uzun basıldığında (dokunmatik cihazlarda) veya imleçle üzerine gelindiğinde (fare işaretçisiyle olduğu gibi) ipucu, daha fazla bilgi göstermek için görüntülenir.
  • RichTooltip composable'ı, başlık ve gövde metni de dahil olmak üzere ipucunun içeriğini tanımlar. TooltipDefaults.rememberRichTooltipPositionProvider(), zengin ipuçları için konumlandırma bilgileri sağlar.

Sonuç

Bu örnekte, bilgi simgesine eklenmiş bir başlığa sahip zengin bir ipucu oluşturulur:

Başlığı içeren çok satırlı bir ipucu
Şekil 3. Başlık ve bilgi simgesi içeren zengin bir ipucu.

Zengin ipuçlarını özelleştirme

Bu kod snippet'i, kamera simgesi düğmesinin üzerinde başlık, özel işlemler ve özel şapka (ok) içeren zengin bir ipucu görüntüler:

@Composable
fun AdvancedRichTooltipExample(
    modifier: Modifier = Modifier,
    richTooltipSubheadText: String = "Custom Rich Tooltip",
    richTooltipText: String = "Rich tooltips support multiple lines of informational text.",
    richTooltipActionText: String = "Dismiss"
) {
    val tooltipState = rememberTooltipState()
    val coroutineScope = rememberCoroutineScope()

    TooltipBox(
        modifier = modifier,
        positionProvider = TooltipDefaults.rememberRichTooltipPositionProvider(),
        tooltip = {
            RichTooltip(
                title = { Text(richTooltipSubheadText) },
                action = {
                    Row {
                        TextButton(onClick = {
                            coroutineScope.launch {
                                tooltipState.dismiss()
                            }
                        }) {
                            Text(richTooltipActionText)
                        }
                    }
                },
                caretSize = DpSize(32.dp, 16.dp)
            ) {
                Text(richTooltipText)
            }
        },
        state = tooltipState
    ) {
        IconButton(onClick = {
            coroutineScope.launch {
                tooltipState.show()
            }
        }) {
            Icon(
                imageVector = Icons.Filled.Camera,
                contentDescription = "Open camera"
            )
        }
    }
}
Tooltips.kt

Kodla ilgili önemli noktalar

  • RichToolTip simgesi, başlık ve kapatma işlemi içeren bir ipucu gösterir.
  • Uzun basarak veya fare imleciyle ToolTipBox içeriğin üzerine gelerek etkinleştirildiğinde ipucu yaklaşık bir saniye boyunca gösterilir. Ekranın başka bir yerine dokunarak veya kapatma işlemi düğmesini kullanarak bu ipucunu kapatabilirsiniz.
  • Kapatma işlemi yürütüldüğünde sistem, tooltipState.dismiss işlevini çağırmak için bir eşzamanlı yordam başlatır. Bu, ipucu gösterilirken işlem yürütmenin engellenmediğini doğrular.
  • onClick = coroutineScope.launch { tooltipState.show() } }, tooltipState.show kullanarak ipucunu manuel olarak göstermek için bir coroutine başlatır.
  • action parametresi, bir ipucuna düğme gibi etkileşimli öğeler eklenmesine olanak tanır.
  • caretSize parametresi, ipucu okunun boyutunu değiştirir.

Sonuç

Bu örnek aşağıdaki sonucu verir:

Başlığı içeren çok satırlı ipucu
4.şekil Kamera simgesine sabitlenmiş kapatma işlemi içeren özel bir zengin ipucu.

Ek kaynaklar