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

Şekil 1. Düz bir ipucu (1) ve zengin bir ipucu (2).

API yüzeyi

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

• 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 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 özelliklerin 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

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üğmenin üzerinde düz bir ipucu gösterir:

@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.
  • TooltipDefaults.rememberPlainTooltipPositionProvider(), düz araç ipuçları için varsayılan konumlandırma sağlar.
  • tooltip, PlainTooltip composable'ı kullanarak ipucunun içeriğini tanımlayan bir lambda işlevidir.
  • Text(plainTooltipText), fareyle üzerine gelindiğinde gösterilen ipucundaki metni gösterir.
  • tooltipState, ipucunun durumunu kontrol eder.
• 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. Cihaza bağlı olarak kullanıcılar ipucunu aşağıdaki şekillerde tetikleyebilir:
  • İmleçle simgenin üzerine gelme
  • Mobil cihazda simgeye uzun basma

Sonuç

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

Şekil 2. Kullanıcı, kalp simgesinin üzerine geldiğinde veya simgeye uzun bastığında görünen düz bir ipucu.

Zengin bir 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şleyicileri yönetir ve buna göre TooltipState güncellemelerini yapar. TooltipState, ipucunun gösterilmesi gerektiğini belirttiğinde ipucu lambda'sı 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, dokunulabilir işlem 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 görüntülenerek daha fazla bilgi gösterilir.
• 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:

Ş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)
                        }
                    }
                },
            ) {
                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 işaretçisiyle 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şlem 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ş 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:

Şekil 4. Kamera simgesine sabitlenmiş kapatma işlemi içeren özel bir zengin ipucu.

Ek kaynaklar

• Materyal Tasarım: İpuçları