DOCSEARCHbyAlgolia
Submit Docs

Spotlight Android Library

repository·master·Indexed 25 days ago

https://github.com/takusemba/spotlight

An Android library for highlighting specific UI elements through a sequence of visual effects and shapes, typically used for onboarding or feature tours. It provides a Builder-based API to configure targets, background colors, and animations, with built-in support for shapes like Circle and RoundedRectangle, and effects such as RippleEffect and FlickerEffect.

Tokens
3.1K
Snippets
8
Records
21
Agent score
86%

What's inside spotlight

  1. Requirements and Breaking Changes for Version 2.0.0

    master

    When upgrading to version 2.0.0, note the following:

    • Kotlin Requirement: Requires Kotlin 1.3.50 or higher.
    • Removed SimpleTarget: This class has been removed.
    • Removed Attribute: The isClosedOnTouchedOutside attribute is no longer available.

  2. Add Spotlight dependency via Gradle

    master

    To use Spotlight in your Android project, add the following implementation dependency to your build.gradle file. Replace x.x.x with the desired version.

    dependencies {
    implementation 'com.github.takusemba:spotlight:x.x.x'
}

  3. Initialize and start Spotlight

    master

    Use Spotlight.Builder to configure and launch a spotlight sequence. You can set multiple targets, a background color, duration, animation interpolator, and a container view. You can also attach an OnSpotlightListener to react to the spotlight starting or ending.

    Note: If you want to show Spotlight immediately, ensure you wait until views are laid out using doOnPreDraw (from core-ktx).

    val spotlight = Spotlight.Builder(this)
    .setTargets(firstTarget, secondTarget, thirdTarget ...)
    .setBackgroundColor(R.color.spotlightBackground)
    .setDuration(1000L)
    .setAnimation(DecelerateInterpolator(2f))
    .setContainer(viewGroup)
    .setOnSpotlightListener(object : OnSpotlightListener {
      override fun onStarted() {
        Toast.makeText(this@MainActivity, "spotlight is started", Toast.LENGTH_SHORT).show()
      }
      override fun onEnded() {
        Toast.makeText(this@MainActivity, "spotlight is ended", Toast.LENGTH_SHORT).show()
      }
    })
    .build()         

// To show immediately after layout:
view.doOnPreDraw { Spotlight.Builder(this)...start() }

  5. Control Spotlight navigation and lifecycle

    master

    Once a Spotlight instance is created, you can control its flow using the following methods:

    • start(): Begins the spotlight sequence.
    • finish(): Ends the spotlight sequence.
    • next(): Moves to the next target.
    • previous(): Moves to the previous target.
    • show(index): Jumps to a specific target by its index.
    val spotlight = Spotlight.Builder(this)...start()

spotlight.finish()
spotlight.next()
spotlight.previous()
spotlight.show(2)

  6. Create a Spotlight Target

    master

    A Target defines a specific spot to be highlighted by the Spotlight. You can use Target.Builder to set an anchor point, a Shape, an Effect, an overlay layout, and an OnTargetListener to handle events specific to that target.

    val target = Target.Builder()
    .setAnchor(100f, 100f)
    .setShape(Circle(100f))
    .setEffect(RippleEffect(100f, 200f, argb(30, 124, 255, 90)))
    .setOverlay(layout)
    .setOnTargetListener(object : OnTargetListener {
      override fun onStarted() {
        makeText(this@MainActivity, "first target is started", LENGTH_SHORT).show()
      }
      override fun onEnded() {
        makeText(this@MainActivity, "first target is ended", LENGTH_SHORT).show()
      }
    })
    .build()

  7. Navigate between targets using Spotlight navigation methods

    master

    Version 2.0.0 introduced several methods to control target progression:

    • next(): Closes the current target and shows the next target if one exists.
    • previous(): Closes the current target and shows the previous target if one exists.
    • show(index): Shows the target at the specified index.

  8. Configure Spotlight targets with Effects

    master

    Starting from version 2.0.0, you can apply visual effects to a Target using the .setEffect() method. The library provides RippleEffect and FlickerEffect by default. You can also use custom Effect implementations.

    val target = Target.Builder()
  .setAnchor(100f, 100f)
  .setShape(Circle(150f))
  .setEffect(FlickerEffect(200f, rgb(124, 255, 90)))
  .build()

  11. Create a Target using Target.Builder

    master

    A Target represents the specific area that Spotlight will highlight. You should use the Target.Builder to define the anchor point, the shape of the spotlight, the visual effect applied, an optional overlay view, and an optional listener.

    Key configuration options:

    • setAnchor(view: View): Automatically calculates the center point of the provided View.
    • setAnchor(x: Float, y: Float): Sets a specific coordinate.
    • setShape(shape: Shape): Defines the geometry of the spotlight (e.g., Circle).
    • setEffect(effect: Effect): Defines the visual effect applied to the spotlight.
    • setOverlay(overlay: View): Attaches a View to be displayed at the target location.
    • setOnTargetListener(listener: OnTargetListener): Attaches a listener to respond to target state changes.

  12. FlickerEffect default configuration constants

    master

    When using FlickerEffect without specifying animation parameters, the following defaults are applied:

    • DEFAULT_DURATION: 1000 milliseconds.
    • DEFAULT_INTERPOLATOR: LinearInterpolator().
    • DEFAULT_REPEAT_MODE: ObjectAnimator.REVERSE.
    val DEFAULT_DURATION = TimeUnit.MILLISECONDS.toMillis(1000)
val DEFAULT_INTERPOLATOR = LinearInterpolator()
const val DEFAULT_REPEAT_MODE = ObjectAnimator.REVERSE