From 6382d96b6e10f9e509e71db39d7a7e116934101a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Odin=20Asbj=C3=B8rnsen?= Date: Fri, 10 Mar 2023 18:05:14 +0100 Subject: [PATCH 1/2] Add documentation regarding Custom preview annotation usage Her I have added documentation for using Custom preview annotation with Showkase. I have added use cases and KSP vs KAPT differences. Also added docs about how to use this with KAPT. --- README.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 75 insertions(+) diff --git a/README.md b/README.md index fa9e07a0c..177b41c13 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,81 @@ fun MyComposable() { Name and group are optional. Look at the [properties section](#showkasecomposable-currently-supports-the-following-properties) to understand the behavior when you don't pass any properties. +### Custom Preview Annotations +You can use custom preview annotations for Showkase as well. Custom preview annotations are annotations that are annotated with preview it self. +An example of this can be: + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +@Preview(name = "Custom Preview One Second", group = "Custom Previews") +annotation class CustomPreview1 +``` + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +annotation class CustomPreview2 +``` + +this can be used to annotate a composable function like you would do any other preview function in Compose like this: + +```kt +@CustomPreview1 +@Composable +fun CustomAnnotationPreview() { +} +``` + +This can also be combined like this: + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +@Preview(name = "Custom Preview One Second", group = "Custom Previews") +annotation class CustomPreviewOne + + +@Preview(name = "Custom Preview Two First", group = "Custom Previews") +annotation class CustomPreviewTwo + +@CustomPreviewOne +@CustomPreviewTwo +@Composable +fun CustomAnnotationPreviewCombined() { +} +``` + +### KAPT vs KSP + +Because of [this issue](https://youtrack.jetbrains.com/issue/KT-49682/Support-JVM-IR-in-KAPT-stub-generation) KAPT does not quite support repeatable annotations from Kotlin. This means that if you have an annotation class like: + +```kt +@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) +@Preview(name = "Shape 150 by 150", group = "Shapes", widthDp = 150, heightDp = 150) +annotation class CustomShape +``` + +This will be skipped by KAPT, but KSP will pick it up. However, if you have an annotation like: + +```kt +@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) +annotation class CustomShape +``` +It will be picked up by both KSP and KAPT. + +#### Important for KAPT users + +You will need to provide a compiler arg in you module for the custom preview annotations that you are using and expecting to be picked up by Showkase. This can be done with the following code: + +```kt +kapt { + arguments { + arg("multiPreviewType", "com.airbnb.android.submodule.showkasesample.LocalePreview") + } +} +``` + +It is important to remember to use the whole qualified name of the annotation, and not just the name. + +### Further usage **Note:** Make sure that you add this annotation to only those functions that meet the following criteria: - Functions that don't have any parameters - If it does have a parameter, it has to be annotated with `@PreviewParameter` that is provided a `PreviewParameterProvider` implementation. From 3215a80b02555e9d612d97f32b6412dbe7df15ae Mon Sep 17 00:00:00 2001 From: Vinay Gaba Date: Tue, 5 Aug 2025 09:54:48 -0700 Subject: [PATCH 2/2] Moved this documentation to an alternate section README.md --- README.md | 149 +++++++++++++++++++++++++++--------------------------- 1 file changed, 74 insertions(+), 75 deletions(-) diff --git a/README.md b/README.md index c3dd2cbf1..d027319b9 100644 --- a/README.md +++ b/README.md @@ -164,81 +164,6 @@ fun MyComposable() { Name and group are optional. Look at the [properties section](#showkasecomposable-currently-supports-the-following-properties) to understand the behavior when you don't pass any properties. -### Custom Preview Annotations -You can use custom preview annotations for Showkase as well. Custom preview annotations are annotations that are annotated with preview it self. -An example of this can be: - -```kt -@Preview(name = "Custom Preview One First", group = "Custom Previews") -@Preview(name = "Custom Preview One Second", group = "Custom Previews") -annotation class CustomPreview1 -``` - -```kt -@Preview(name = "Custom Preview One First", group = "Custom Previews") -annotation class CustomPreview2 -``` - -this can be used to annotate a composable function like you would do any other preview function in Compose like this: - -```kt -@CustomPreview1 -@Composable -fun CustomAnnotationPreview() { -} -``` - -This can also be combined like this: - -```kt -@Preview(name = "Custom Preview One First", group = "Custom Previews") -@Preview(name = "Custom Preview One Second", group = "Custom Previews") -annotation class CustomPreviewOne - - -@Preview(name = "Custom Preview Two First", group = "Custom Previews") -annotation class CustomPreviewTwo - -@CustomPreviewOne -@CustomPreviewTwo -@Composable -fun CustomAnnotationPreviewCombined() { -} -``` - -### KAPT vs KSP - -Because of [this issue](https://youtrack.jetbrains.com/issue/KT-49682/Support-JVM-IR-in-KAPT-stub-generation) KAPT does not quite support repeatable annotations from Kotlin. This means that if you have an annotation class like: - -```kt -@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) -@Preview(name = "Shape 150 by 150", group = "Shapes", widthDp = 150, heightDp = 150) -annotation class CustomShape -``` - -This will be skipped by KAPT, but KSP will pick it up. However, if you have an annotation like: - -```kt -@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) -annotation class CustomShape -``` -It will be picked up by both KSP and KAPT. - -#### Important for KAPT users - -You will need to provide a compiler arg in you module for the custom preview annotations that you are using and expecting to be picked up by Showkase. This can be done with the following code: - -```kt -kapt { - arguments { - arg("multiPreviewType", "com.airbnb.android.submodule.showkasesample.LocalePreview") - } -} -``` - -It is important to remember to use the whole qualified name of the annotation, and not just the name. - -### Further usage **Note:** Make sure that you add this annotation to only those functions that meet the following criteria: - Functions that don't have any parameters - If it does have a parameter, it has to be annotated with `@PreviewParameter` that is provided a `PreviewParameterProvider` implementation. @@ -461,6 +386,80 @@ val typography = metadata.typographyList ``` +##### 6. Custom/Multipreview Annotations +You can use custom preview annotations for Showkase as well. Custom preview annotations are annotations that are annotated with preview it self. +An example of this can be: + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +@Preview(name = "Custom Preview One Second", group = "Custom Previews") +annotation class CustomPreview1 +``` + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +annotation class CustomPreview2 +``` + +this can be used to annotate a composable function like you would do any other preview function in Compose like this: + +```kt +@CustomPreview1 +@Composable +fun CustomAnnotationPreview() { +} +``` + +This can also be combined like this: + +```kt +@Preview(name = "Custom Preview One First", group = "Custom Previews") +@Preview(name = "Custom Preview One Second", group = "Custom Previews") +annotation class CustomPreviewOne + + +@Preview(name = "Custom Preview Two First", group = "Custom Previews") +annotation class CustomPreviewTwo + +@CustomPreviewOne +@CustomPreviewTwo +@Composable +fun CustomAnnotationPreviewCombined() { +} +``` + +###### KAPT vs KSP + +Because of [this issue](https://youtrack.jetbrains.com/issue/KT-49682/Support-JVM-IR-in-KAPT-stub-generation) KAPT does not quite support repeatable annotations from Kotlin. This means that if you have an annotation class like: + +```kt +@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) +@Preview(name = "Shape 150 by 150", group = "Shapes", widthDp = 150, heightDp = 150) +annotation class CustomShape +``` + +This will be skipped by KAPT, but KSP will pick it up. However, if you have an annotation like: + +```kt +@Preview(name = "Shape 100 by 100", group = "Shapes", widthDp = 100, heightDp = 100) +annotation class CustomShape +``` +It will be picked up by both KSP and KAPT. + +###### Important for KAPT users + +You will need to provide a compiler arg in you module for the custom preview annotations that you are using and expecting to be picked up by Showkase. This can be done with the following code: + +```kt +kapt { + arguments { + arg("multiPreviewType", "com.airbnb.android.submodule.showkasesample.LocalePreview") + } +} +``` + +It is important to remember to use the whole qualified name of the annotation, and not just the name. + ## R8 / ProGuard If you use Showkase as a dependency in an Android project which uses R8 as a default compiler