टूलटिप

किसी बटन या अन्य यूज़र इंटरफ़ेस (यूआई) एलिमेंट के बारे में जानकारी देने के लिए, टूलटिप का इस्तेमाल करें. टूलटिप दो तरह के होते हैं:

• सामान्य टूलटिप: इनमें आइकॉन बटन के एलिमेंट या कार्रवाइयों के बारे में बताया जाता है.
• ज़्यादा जानकारी वाले टूलटिप: इनमें ज़्यादा जानकारी दी जाती है. जैसे, किसी सुविधा की अहमियत के बारे में बताना. इसमें टाइटल, लिंक, और बटन भी शामिल किए जा सकते हैं. हालांकि, ऐसा करना ज़रूरी नहीं है.

एपीआई सरफ़ेस

अपने ऐप्लिकेशन में टूलटिप लागू करने के लिए, TooltipBox कंपोज़ेबल का इस्तेमाल किया जा सकता है. इन मुख्य पैरामीटर की मदद से, TooltipBox के दिखने के तरीके को कंट्रोल किया जा सकता है:

• positionProvider: यह टूलटिप को ऐंकर कॉन्टेंट के हिसाब से प्लेस करता है. आम तौर पर, TooltipDefaults से डिफ़ॉल्ट पोज़िशन प्रोवाइडर का इस्तेमाल किया जाता है. इसके अलावा, अगर आपको कस्टम पोज़िशनिंग लॉजिक की ज़रूरत है, तो अपना पोज़िशन प्रोवाइडर भी दिया जा सकता है.
• tooltip: ऐसा कंपोज़ेबल जिसमें टूलटिप का कॉन्टेंट शामिल है. आम तौर पर, PlainTooltip या RichTooltip कंपोज़ेबल का इस्तेमाल किया जाता है.
  • आइकॉन बटन के एलिमेंट या कार्रवाइयों के बारे में बताने के लिए, PlainTooltip का इस्तेमाल करें.
  • ज़्यादा जानकारी देने के लिए, RichTooltip का इस्तेमाल करें. जैसे, किसी सुविधा की अहमियत बताना. रिच टूलटिप में टाइटल, लिंक, और बटन शामिल किए जा सकते हैं. हालांकि, ऐसा करना ज़रूरी नहीं है.
• state: स्टेट होल्डर, जिसमें इस टूलटिप के लिए यूज़र इंटरफ़ेस (यूआई) लॉजिक और एलिमेंट की स्थिति शामिल होती है.
• content: कंपोज़ेबल कॉन्टेंट, जिससे टूलटिप को ऐंकर किया गया है.

सामान्य टूलटिप दिखाएं

किसी यूज़र इंटरफ़ेस (यूआई) एलिमेंट के बारे में कम शब्दों में जानकारी देने के लिए, सामान्य टूलटिप का इस्तेमाल करें. इस कोड स्निपेट में, "पसंदीदा में जोड़ें" लेबल वाले आइकॉन बटन के ऊपर एक सामान्य टूलटिप दिखाई गई है:

@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

कोड के बारे में अहम बातें

• TooltipBox, "पसंदीदा में जोड़ें" टेक्स्ट वाली टूलटिप जनरेट करता है.
  • TooltipDefaults.rememberPlainTooltipPositionProvider(), सामान्य टूलटिप के लिए डिफ़ॉल्ट पोज़िशन उपलब्ध कराता है.
  • tooltip एक लैम्डा फ़ंक्शन है, जो PlainTooltip कंपोज़ेबल का इस्तेमाल करके टूलटिप के कॉन्टेंट को तय करता है.
  • Text(plainTooltipText), टूलटिप में टेक्स्ट दिखाता है.
  • tooltipState, टूलटिप की स्थिति को कंट्रोल करता है.
• IconButton, आइकॉन के साथ क्लिक किया जा सकने वाला बटन बनाता है.
  • Icon(...) बटन में दिल का आइकॉन दिखाता है.
  • जब कोई उपयोगकर्ता IconButton के साथ इंटरैक्ट करता है, तो TooltipBox "पसंदीदा में जोड़ें" टेक्स्ट वाली टूलटिप दिखाता है. डिवाइस के आधार पर, उपयोगकर्ता इन तरीकों से टूलटिप को ट्रिगर कर सकते हैं:
  • कर्सर को आइकॉन पर ले जाना
  • मोबाइल डिवाइस पर आइकॉन को दबाकर रखना

नतीजा

इस उदाहरण में, आइकॉन के ऊपर एक सामान्य टूलटिप दिखाया गया है:

रिच टूलटिप दिखाएं

किसी यूज़र इंटरफ़ेस (यूआई) एलिमेंट के बारे में ज़्यादा जानकारी देने के लिए, पूरी जानकारी वाले टूलटिप का इस्तेमाल करें. इस उदाहरण में, कई लाइनों वाली रिच टूलटिप बनाई गई है. इसमें एक टाइटल है, जो Icon से ऐंकर किया गया है:

@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

कोड के बारे में अहम बातें

• TooltipBox, उपयोगकर्ता के इंटरैक्शन के लिए इवेंट लिसनर को मैनेज करता है और TooltipState को उसी हिसाब से अपडेट करता है. जब TooltipState से यह पता चलता है कि टूलटिप दिखानी है, तब टूलटिप लैम्डा काम करता है. इसके बाद, TooltipBox, RichTooltip दिखाता है. TooltipBox, कॉन्टेंट और टूलटिप, दोनों के लिए ऐंकर और कंटेनर के तौर पर काम करता है.
  • इस मामले में, कॉन्टेंट एक IconButton कॉम्पोनेंट है. यह कॉम्पोनेंट, टैप करके कार्रवाई करने की सुविधा देता है. TooltipBox के कॉन्टेंट में कहीं भी दबाकर रखने (टच डिवाइसों पर) या कर्सर घुमाने (जैसे कि माउस पॉइंटर से) पर, ज़्यादा जानकारी दिखाने के लिए टूलटिप दिखेगा.
• RichTooltip कंपोज़ेबल, टूलटिप के कॉन्टेंट के बारे में बताता है. इसमें टाइटल और मुख्य टेक्स्ट शामिल होता है. TooltipDefaults.rememberRichTooltipPositionProvider(), रिच टूलटिप की पोज़िशन की जानकारी देता है.

नतीजा

इस उदाहरण में, जानकारी के आइकॉन से जुड़े टाइटल के साथ एक रिच टूलटिप जनरेट होता है:

रिच टूलटिप को पसंद के मुताबिक बनाना

इस कोड स्निपेट में, टाइटल, कस्टम कार्रवाइयों, और कैमरे के आइकॉन वाले बटन के ऊपर दिखने वाले कस्टम कैरेट (ऐरो) के साथ एक रिच टूलटिप दिखाई गई है:

@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

कोड के बारे में अहम बातें

• RichTooltip, टाइटल और खारिज करने की कार्रवाई के साथ टूलटिप दिखाता है.
• इसे चालू करने के बाद, TooltipBox कॉन्टेंट को दबाकर रखें या उस पर माउस घुमाएं. इसके बाद, टूलटिप करीब एक सेकंड तक दिखती है. इस टूलटिप को खारिज करने के लिए, स्क्रीन पर कहीं और टैप करें या 'खारिज करें' बटन का इस्तेमाल करें.
• जब खारिज करने की कार्रवाई पूरी हो जाती है, तो सिस्टम tooltipState.dismiss को कॉल करने के लिए एक कोरूटीन लॉन्च करता है. इससे पुष्टि होती है कि टूलटिप दिखने के दौरान, कार्रवाई को ब्लॉक नहीं किया गया है.
• onClick = coroutineScope.launch { tooltipState.show() } }, tooltipState.show का इस्तेमाल करके, टूलटिप को मैन्युअल तरीके से दिखाने के लिए एक कोरूटीन लॉन्च करता है.
• action पैरामीटर की मदद से, टूलटिप में इंटरैक्टिव एलिमेंट जोड़े जा सकते हैं. जैसे, कोई बटन.
• caretSize पैरामीटर, टूलटिप के ऐरो का साइज़ बदलता है.

नतीजा

इस उदाहरण से यह नतीजा मिलता है:

अन्य संसाधन

• मटीरियल डिज़ाइन: टूलटिप