README.md

Showcase Layout Compose

Create a beautiful animated showcase effect for your compose UIs easily !

Now with multiplatform support :D

Web demo

Click here to try showcase layout for web in your browser!

Demo

.

Setup

Showcase Layout Compose can be used in both Jetpack Compose (native Android) or Compose Multiplatform (Kotlin Multiplatform) projects.

Compose multiplatform support starts at version 1.0.5-alpha-8 and up.

Add the dependency to your module's build.gradle file like below

implementation("ly.com.tahaben:showcase-layout-compose:1.0.6")

Usage

Step 1

Create a ShowcaseLayout and make it the root composable (put all screen composables inside it)

    var isShowcasing by remember {
    mutableStateOf(true)
}
ShowcaseLayout(
    isShowcasing = isShowcasing,
    onFinish = { isShowcasing = false }
) {
    // screen content here
    Column(
        modifier = Modifier
            .fillMaxSize()
    ) {
        Text(text = "ShowcaseLayout Test 1")
        Spacer(modifier = Modifier.height(16.dp))
        Text(text = "ShowcaseLayout Test 2")
        Spacer(modifier = Modifier.height(16.dp))
        Text(text = "ShowcaseLayout Test 3")
    }
}

Step 2

In composables you want to showcase on the modifier use Modifier.showcase(), Lets say we want to showcase the first text "ShowcaseLayout Test 1"

Text(
    modifier = Modifier.showcase(
        // should start with 1 and increment with 1 for each time you use Modifier.showcase()
        index = 1,
        message =
    ),
    text = "ShowcaseLayout Test 1"
)

you also use the old method by wrap the composables you want to showcase with Showcase()

Step 3

You have 2 ways of showcasing, showcase everything subsequently or showcasing each item manually

Showcase all items subsequently

Start showcasing by making isShowcasing = true, and stop showcasing by making it false above we stop showcasing after we showcase the last item using `onFinished` which is called whenever all items are showcased,

Showcase a single item (1.0.5 and up)

After you attach the index and showcase message to your components you can simply call showcaseItem(i) where i is the index of the item you want to showcase

    val coroutineScope = rememberCoroutineScope()

    coroutineScope.launch{
        showcaseItem(1)
    }

similarly you can show a greeting using showGreeting and passing the message

    val coroutineScope = rememberCoroutineScope()

    coroutineScope.launch{
        showGreeting(
            ShowcaseMsg(
            text = "I like compose bro <3",
            textStyle = TextStyle(color = Color.White)
            )
        )
    }

Done, our text is now showcased!, customize it further with Additional parameters

Additional parameters

isDarkLayout

Makes the showcase view white instead of black (useful for dark UI).

ShowcaseLayout(
    isShowcasing = isShowcasing,
    onFinish = { isShowcasing = false },
    isDarkLayout = isSystemInDarkTheme()
)

isDarkLayout = true

greeting

A customizable greeting message of type showcaseMsg()

ShowcaseLayout(
    isShowcasing = isShowcasing,
    onFinish = { isShowcasing = false },
    isDarkLayout = isSystemInDarkTheme(),
    greeting = ShowcaseMsg(
        "Welcome to my app, lets take you on a quick tour!, tap anywhere to continue",
        textStyle = TextStyle(color = Color.White)
    )
)

initIndex

the initial value of the counter, set this to 1 if you don't want a greeting message before showcasing targets.

animationDuration

total animation time taken when switching from current to next target in milliseconds(default is 1000ms).

    val greetingString = buildAnnotatedString {
    append("Welcome to ")
    pushStyle(SpanStyle(fontWeight = FontWeight.Bold))
    append("My App")
    pop()
    append(", let's take you on a quick tour!")
    pushStyle(SpanStyle(fontWeight = FontWeight.Bold))
    append("\n Tap anywhere")
    pop()
    append(" to continue")
}
ShowcaseLayout(
    isShowcasing = isShowcasing,
    onFinish = { isShowcasing = false },
    isDarkLayout = isSystemInDarkTheme(),
    greeting = ShowcaseMsg(
        text = greetingString, // You can use an annotated string or a normal string here
        textStyle = TextStyle(color = Color.White, textAlign = TextAlign.Center)
    ),
    animationDuration = 1000
) 

ShowcaseMsg

Use ShowcaseMsg() to add a message and customize it with arrow, background and more.

ShowcaseMsg(
    // the message text to be displayed
    "Track your phone usage from here",
    // text style for the message text
    textStyle = TextStyle(color = Color(0xFF827717)),
    // a background color for the text
    msgBackground = MaterialTheme.colors.primary,
    // control corner radius of msgBackground
    roundedCorner = 15.dp,
    // determine if the message will be displayed above or below the target composable
    gravity = Gravity.Bottom,
    // adds an arrow to be displayed with the message
    arrow = Arrow(color = MaterialTheme.colors.primary),
    // starting from version 1.0.3 ShowcaseMsg will have an enter and exit animation of FadeInOut by default you can disable it by using MsgAnimation.None
    enterAnim = MsgAnimation.FadeInOut(),
    exitAnim = MsgAnimation.FadeInOut()
)

ShowcaseMsg	without ShowcaseMsg

Arrow

Used with ShowcaseMsg to add an arrow pointing to the target

arrow = Arrow(
    // From where the arrow will point at the target, can be: Top, Bottom, Right or Left
    targetFrom = Side.Top,
    // animates a curved arrow from the message to the target(if true targetFrom is ignored)
    // might not work properly depending on the location of the target on the screen
    curved = true,
    // if false then just draw a line (an arrow without head :P)
    hasHead = false,
    // color of the arrow
    color = MaterialTheme.colors.primary
)

Default Arrow	curved = true	hasHead = false

Head style

By default, an Arrow will have a triangle as the head to change this, set head in the arrow to one of these options

TRIANGLE	CIRCLE	SQUARE	ROUND_SQUARE

You can also animate the arrow head and change the size, see the example below.

showcase(
    index = 5, 
    message = ShowcaseMsg(
        "A Circle !",
        textStyle = TextStyle(
            color = Color(0xFF827717),
            fontSize = 18.sp
        ),
        msgBackground = MaterialTheme.colors.primary,
        gravity = Gravity.Top,
        arrow = Arrow(
            color = MaterialTheme.colors.primary,
            targetFrom = Side.Top,
            head = Head.CIRCLE, // head style
            headSize = 30f, // the size of the circle
            animSize = true // animates the arrow head size
        )
    )
)

Logging Events

In recent releases logs have been disabled by default, to print log statement of the current actions taken by compose layout register a listener in your ShowcaseLayout

        registerEventListener(object: ShowcaseEventListener {
            override fun onEvent(level: Level, event: String) {
                println("$level: $event")
            }
        })

Complete Example

For a complete example check out MainScreen.kt
or clone/download this repository and check the app module.

Contributing

Contributions are always welcome!

Used By

Showcase Layout is used by:

• Farhan

Contact me on LinkedIn or open an issue if you used ShowcaseLayout in your app, and you want it added to this list