takusemba / spotlight

Android Library that lights items for tutorials or walk-throughs etc...

Spotlight

Gradle

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

Usage

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()         

If you want to show Spotlight immediately, you have to wait until views are laid out.

// with core-ktx method.
view.doOnPreDraw { Spotlight.Builder(this)...start() }

Target

Create a Target to add Spotlight.

Target is a spot to be casted by Spotlight. You can add multiple targets to Spotlight.

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()

Start/Finish Spotlight

val spotlight = Spotlight.Builder(this)...start()

spotlight.finish()

Next/Previous/Show Target

val spotlight = Spotlight.Builder(this)...start()

spotlight.next()

spotlight.previous()

spotlight.show(2)

Custom Shape

Shape defines how your target will look like. Circle and RoundedRectangle shapes are already implemented, but if you want your custom shape, it's arhivable by implementing Shape interface.

class CustomShape(
    override val duration: Long,
    override val interpolator: TimeInterpolator
) : Shape {

  override fun draw(canvas: Canvas, point: PointF, value: Float, paint: Paint) {
    // draw your shape here.
  }
}

Custom Effect

Effect allows you to decorates your target. RippleEffect and FlickerEffect shapes are already implemented, but if you want your custom effect, it's arhivable by implementing Effect interface.

class CustomEffect(
    override val duration: Long,
    override val interpolator: TimeInterpolator,
    override val repeatMode: Int
) : Effect {

  override fun draw(canvas: Canvas, point: PointF, value: Float, paint: Paint) {
    // draw your effect here.
  }
}

Sample

Clone this repo and check out the app module.

Author

• Taku Semba
  • Github - (https://github.com/takusemba)
  • Twitter - (https://twitter.com/takusemba)
  • Facebook - (https://www.facebook.com/takusemba)

Licence

Copyright 2017 Taku Semba.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

spotlight's Issues

only circle nor square？

only circle nor square？

Can show all target at once. Without any click

There is need to show all targeted spotlight when activity created, how to do that there is only one target showing at a time.

Set click listener only in spotlight

hi there, i want to implement on click only on spotlight so i can say it cant cancellable on when user touch on black area. Is this feature already implemented? or is there any code to backup this logic?

thank you

.setTargets(targets) does not work

I was trying to set targets added to ArrayList but I get this error

Is this works with fragments too?

Text overflow

Description

I have an issue with the description in the simple target.
When I have a large string and move the overlay point away from x=0, it won't wrap the text but lets it overflow the layout. Probably I did something wrong and I will try to fix it with a custom target, but in case it is a generell issue I wanted to let you know. Of course, if I did something wrong, any help to fix it is highly appreciated 😄

Below is an example of what I mean, together with my current layout where I tested it on

Code with screenshots

 Spotlight.with(this)
            .setOverlayColor(R.color.background)
            .setDuration(1000L)
            .setAnimation(DecelerateInterpolator(2f))
            .setTargets(bugTarget)
            .setClosedOnTouchedOutside(true)
            .start()

Without overflow

        val bugTarget = SimpleTarget.Builder(this)
            .setPoint(layout_coordinator.width.toFloat() - 50, 400f)
            .setShape(Circle(150f))
            .setTitle(resources.getString(R.string.spotlight_feedback_bug))
            .setDescription(resources.getString(R.string.spotlight_feedback_bug_desc))
            .setOverlayPoint(20f, 500f)
            .build()

With overflow

        val bugTarget = SimpleTarget.Builder(this)
            .setPoint(layout_coordinator.width.toFloat() - 50, 400f)
            .setShape(Circle(150f))
            .setTitle(resources.getString(R.string.spotlight_feedback_bug))
            .setDescription(resources.getString(R.string.spotlight_feedback_bug_desc))
            .setOverlayPoint(400f, 500f)
            .build()

Activity Layout

<?xml version="1.0" encoding="utf-8"?>
<androidx.drawerlayout.widget.DrawerLayout
    xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/layout_drawer"
    android:layout_width="match_parent"
    android:layout_height="match_parent">
    <androidx.coordinatorlayout.widget.CoordinatorLayout
        android:id="@+id/layout_coordinator"
        android:layout_width="match_parent"
        android:layout_height="match_parent"
        tools:context=".view.activity.GodActivity">

...

    </androidx.coordinatorlayout.widget.CoordinatorLayout>

    <com.google.android.material.navigation.NavigationView
        android:id="@+id/drawer_navigation_view"
        android:layout_width="wrap_content"
        android:layout_height="match_parent"
        android:layout_gravity="start"
        app:headerLayout="@layout/menu_navigation_header"
        app:menu="@menu/menu_drawer_navigation"/>
    
</androidx.drawerlayout.widget.DrawerLayout>

how to set spot in menuItem?

menu item doesn't have "getLocationWindow"

Add "show once only" feature

In its current state we have to handle the limiting of the displaying ourselves. It would be great if there was a feature in the api where we can define that the spotlight is displayed only once.

Close w/ back button

It would be nice if the showcase overlay could be closed by the android (hardware) back button. I think this is the default user expectation.

assign target to view..

Hi,

im trying to implement the library, but i cant put target as a view to method setPoint(textview1);

the round is not fit to the view..

any advice would help much.

thanks

target.getView().getTag() return Null in OnTargetStateChangedListener

Hello,
I got trouble when put data in tag view before put in setPoint method and get data in OnTargetStateChangedListener in method onStarted and onEnded, and always got null value.

I think this is a bug.

Sorry, my english is bad.

Thank you

Need method to finish spotlight from code anytime and to check if spotlight is visible

IOS version

Hi, is there is any plane to develop this lib on IOS?

Coachmark with Dialog

Its an awesome library but I have a query how do I show the coachmark over the dialog. Its always coming behind the dialog. I am using the DialogFragment with animation in android.

Spotlight is not started with CustomTarget

I created a customtarget.

CustomTarget customtarget = new CustomTarget.Builder(activity)
                .setPoint(viewToFocus)
                .setRadius(50f)
                .setView(R.layout.fab_filter_coachmark)
                .build();

Start spotlight:

Spotlight.with(activity)
                    .setOverlayColor(ContextCompat.getColor(activity, R.color.transparent))
                    .setTargets(customtarget)
                    .setClosedOnTouchedOutside(true)
                    .start();

layout : fab_filter_coachmark

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:orientation="vertical" android:layout_width="match_parent"
    android:background="@color/coachMarkBg"
    android:layout_height="match_parent">
    <TextView
        android:id="@+id/textViewDescription"
        android:layout_width="match_parent"
        android:text="Description"
        android:textColor="@color/white"
        android:layout_height="wrap_content" />
    <TextView
        android:layout_width="match_parent"
        android:text="got it"
        android:textColor="@color/blue_priceinsight"
        android:layout_height="wrap_content" />
</LinearLayout>

There are two issues

1. Custom view is not inflated near to the target, It inflated on the top left of screen.
2. Spotlight is not started on target.

<setPoint> in <SimpleTarget> mode

SimpleTarget firstTarget = new SimpleTarget.Builder(this) .setPoint(findViewById(R.id.one)) .setShape(new Circle(100f)) .setTitle("the title") .setDescription("the description") .setOverlayPoint(100f, 100f) .setOnSpotlightStartedListener(new OnTargetStateChangedListener<SimpleTarget>()
setPoint doesn't work on SimpleTarget.
it goes to top left in application, in the corner.

can't work when Build.VERSION.SDK_INT less than LOLLIPOP

can't work when Build.VERSION.SDK_INT less than LOLLIPOP

view

If you want to achieve such as the effect of the map, used to indicate the progress, what is the good way?

Spotlight Always on Corner point

i use spotlight same the sample
but in my project , spotlight always show in corner

setTargets with ArrayList of Targets as parameter

Good day and thank you for providing the long waited custom shape feature,

could you kindly provide another setTargets method that takes an ArrayList of CustomTargets or SimpleTargets?
It is needed when number of targets is dynamic.

or do you prefer that I fork the project and return with a pull request?

setOverlayColor error

I get error message "Android Release error: Expected a color resource id (R.color.) but received an RGB integer" when try call
setOverlayColor(ContextCompat.getColor(MainActivity.this, R.color.background))

Possible cause by annotation @ColorRes in your define method setOverlayColor

How to draw a rectangle not a circle?

I tried to change the chosen shape to a rectangle but it doesn't work

OnSpotlightEndedListener isn't called if an OnStarted listener isn't also set

Any code inside an OnSpotlightEndedListener isn't called unless an OnSpotlightStartedListener is also set.

How to run Spotlight immediately without Click ?

Add "Skip tutorial" button

Hi. First of all, thank you for so great library. I have a question, is there any way to add a button (not a target) visible all time over the overlay to add any special action? In my case would be a "Skip intro/tutorial" to close spotlight before all targets have been shown.

Thanks

Code works only from OnClickListener() of a button .

I have created a method to create SimpleTarget and show a SpotLight.

createSpotLight();

If I call it inside View.OnClickListener() it works correctly and focuses on my all views.
But if I call it in onCreate() it does not focus correctly. Instead, it focuses on top of my activity.

Check my full code as below:

On Create of Activity :

@Override
protected void onCreate(Bundle savedInstanceState) {
 super.onCreate(savedInstanceState);
 setContentView(R.layout.activity_1);

 button1 = (Button) findViewById(R.id.button1);
 button2 = (Button) findViewById(R.id.button2);
 createSpotLight();

 button1.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
   createSpotLight();
  }
 });

 button2.setOnClickListener(new View.OnClickListener() {
  @Override
  public void onClick(View v) {
   showInputAlert();
  }
 });
}

Method that creates spotlight:

private void createSpotLight() {
 // make an target
 SimpleTarget simpleTarget1 = new SimpleTarget.Builder(MainActivity.this)
  .setPoint(findViewById(R.id.textview_1))
  .setRadius(200 f)
  .setTitle("This is textview")
  .setDescription("It is used to show a title")
  .build();

 // make an target
 SimpleTarget simpleTarget2 = new SimpleTarget.Builder(MainActivity.this)
  .setPoint(button1)
  .setRadius(100 f)
  .setTitle("This is a button")
  .setDescription("It starts Spotlight")
  .build();

 // Create Spotlight Targets
 SimpleTarget simpleTarget3 = new SimpleTarget.Builder(MainActivity.this)
  .setPoint(button2) // position of the Target. setPoint(Point point), setPoint(View view) will work too.
  .setRadius(100 f) // radius of the Target
  .setTitle("This is another Button") // title
  .setDescription("It will open a popup") // description
  .build();

 // Pass targets to method that show spotlight
 showSpotLight(simpleTarget1, simpleTarget2, simpleTarget3);
}

Add animation in custom shape

how can I add an animation for a custom shape

Make SpotlightView/Targetclickable

Can you make spotlightview or the target clickable? I know we can make a custom view and set clickable there but it would be great to make the target itself clickable to make the user tap on the target to move forward

com.takusemba.spotlight.SpotlightView.turnDown(float, long, android.animation.TimeInterpolator)' on a null object reference

java.lang.NullPointerException: Attempt to invoke virtual method 'void com.takusemba.spotlight.SpotlightView.turnDown(float, long, android.animation.TimeInterpolator)' on a null object reference

round rectangle spotlight

Thanks for awesome library, but I am little disappointed that there is no round rectangle option.
anyone who forked and made changes for this feature?

Manifest merger failed

i had a issues. please help me.

"Manifest merger failed : Attribute application@appComponentFactory value=(android.support.v4.app.CoreComponentFactory) from [com.android.support:support-compat:28.0.0] AndroidManifest.xml:22:18-91
is also present at [androidx.core:core:1.0.1] AndroidManifest.xml:22:18-86 value=(androidx.core.app.CoreComponentFactory).
Suggestion: add 'tools:replace="android:appComponentFactory"' to element at AndroidManifest.xml:6:5-24:19 to override."

A probrelm with black panel

I have a problem,the black panel is gray.no black when i Running program...

title and text on spot

hi i make a round rectangle for my app's help, everything fine but texts show on spot.
you can see this problem on pictures .

can't set alpha?

it's always in zero to one, can you provide method to set zero to 0.x?

Not Able to draw exactly on same view

How to Autoscroll the spotlights to target views.

Hi there, Library does an impressive work but if I have views below the viewport library not able to autoscroll on its own what should we do in that case.

Spotlight position between phones

The spotlight position is different between two phone. A Pixel 2 XL emulator looks like this:

https://i.imgur.com/G7Lcrmq.png

but on a Pixel 3 XL phone (no emulator) it's here:

https://i.imgur.com/7qddSSE.png

I'm thinking the notch might be effecting the positioning.

I'm also using 1.5.0 because 1.8.0 is throwing some manifest merge compiling error.

Library has settings in AndroidManifest.xml that can collide with importing projects settings.

If a project that imports this library has any other configuration for these it's impossible to build.

    android:allowBackup="true"
    android:label="@string/app_name"
    android:supportsRtl="true">

SpannableString not support for setTitle and setDescription of SimpleTarget.Builder

SpannableString is useful in showing customized text.

recommend use
public Builder setTitle(CharSequence title)
instead of
public Builder setTitle(String title)

Having Issue Implementing on Custom View !

The Error was : java.lang.IllegalStateException: The specified child already has a parent. You must call removeView() on the child's parent first.

CustomTarget customTarget = new CustomTarget.Builder(this)
                .setPoint(100f, 100f)
                .setShape(new com.takusemba.spotlight.shape.Circle(120f))
                **.setOverlay(root)**
                .setOnSpotlightStartedListener(new OnTargetStateChangedListener<CustomTarget>() {
                    @Override
                    public void onStarted(CustomTarget target) {
                        // do something
                    }
                    @Override
                    public void onEnded(CustomTarget target) {
                        // do something
                    }
                })
                .build();

CustomTarget customTarget = new CustomTarget.Builder(this)
                .setPoint(100f, 100f)
                .setShape(new com.takusemba.spotlight.shape.Circle(120f))
                **.setOverlay(findViewById(R.id.rl))**
                .setOnSpotlightStartedListener(new OnTargetStateChangedListener<CustomTarget>() {
                    @Override
                    public void onStarted(CustomTarget target) {
                        // do something
                    }
                    @Override
                    public void onEnded(CustomTarget target) {
                        // do something
                    }
                })
                .build();

I tried above two different methods but both throwed same error when added as custom view !

Simple Target is working perfectly though !

Add Test

it would be appreciated, if someone could write tests for me...

How to set radius size device specific?

If I am setting radius in float value it will not make a circle based on device density and size.

Is it possible to add the skip and next button in this library?

Spotlight isn't centered properly for some targets

For some targets, the spotlight is centered correctly, but for others, it is centered on the corner of the target. Example:

setview method not found

There is no set view method for the customtarget and simpletarget class, Can you please help me on what cause this? also i saw that the setpoint method can also take a view parameter can this be used instead of setview? Thanks

Target class should be public

I see absolutely no reason why it shouldn't be, it severely limits extensibility and when trying to add different types of targets as target compile error is thrown because it can't infer the type (at least under kotlin)

Click Event ?

Is there any click event listener that i can use in this library ?

SimpleTarget setRadius renamed?

Is this method rename to a new one? Thanks

how set Font for title and Description ?

Issue about paddings

Hi

Thanks for your work but i have a problem: If i add this library to my project my other view's paddings are not working. Do you know how to resolve this problem?