This is a little Android library that provides a convenient way to add an overlay with the ability to highlight and access widgets underneath it. It can be useful for two common scenarios:
- Building an in-app tutorial with accents and tooltips. Accents draw user's attention to certain parts of your UI while tooltips provide user with some information regarding those parts.
- Building custom UI controls that require widgets belonging to a view under the overlay to show through. For example, the demo app uses this library to implement a dimming floating action menu. This scenario doesn't involve tooltips.
The overlay is designed to have a minimal impact on your view hierarchy:
- It sits on top of a
ContentFrameLayout
which is created by the Android framework. No extra nesting is required in most cases. - It is created immediately before shown and destroyed after dismissed. There are no invisible views.
- It does not keep strong references to your UI.
The overlay is also customizable in ways it handles touch events and supports custom animations.
NOTE: The API is aimed at Kotlin and may be cumbersome if used from Java.
- Add JitPack repo in your root
build.gradle
at the end of repositories:allprojects { repositories { // ... maven { url 'https://jitpack.io' } } }
- Add dependency:
dependencies { implementation 'com.github.squeezymo.spotlight:overlay:{version}' }
- Make sure your activity is a standard activity that implements
LifecycleOwner
(namely,AppCompatActivity
orFragmentActivity
). - In your activity, replace
setContentView()
withsetContentViewWithOverlay()
:override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentViewWithOverlay(layoutResId) // ... }
- When you need to show an overlay, get a reference to a
SpotlightController
with an extension propertyspotlightController
from your Activity or Fragment. Be sure to call it aftersetContentViewWithOverlay()
.
View can be accented (highlighted) in four manners:
Shape | Parameters | Example |
---|---|---|
ExactViewShape |
scale |
|
Circle |
scale |
|
Oval |
scale |
|
Rectangle |
scale , roundPx for rounded corners |
Any view can be used as a tooltip. Tooltips are positioned relative to their anchors. Usually you will use your accented view for an anchor but generally they don't have to be the same. The position is given with a bearing angle (or simply bearing), a bearing reference and distance. These values are part of the tooltip's layout parameters (TooltipsViewGroup.LayoutParams
).
Bearing is expressed in degrees. 0°/90°/180°/270° respectively correspond to a tooltip above/to the right of/below/to the left of its anchor. Bearing reference is one of the 9 points of the tooltip with respect to which bearing angle and distance are provided.
If you don't care about the exact position of the tooltip, you can use utility methods TooltipsViewGroup.LayoutParams.suggestBearing()
and TooltipsViewGroup.LayoutParams.suggestBearingReference()
to let the library try to define these values for you based on the position of the anchor on the screen.