A Tap Target implementation in Android based on Material Design Onboarding guidelines.

Android is moving towards compose, for an alternative library in compose have a look at intro-showcase-view .

Bug fix pull requests will be accepted for this library for the immediate future but there will be no active development or new features and it will eventually be archived.

Thank you to everyone who has contributed to the library over the years!

Follow the quick start guide below to get started.

JavaDocs , examples and a sample app with examples implemented are available. The sample app is available to download on the Google Play Store:

Quick start

Gradle

Add the following to build.gradle using Maven Central:

dependencies
 {

    implementation
 'uk.co.samuelwall:material-tap-target-prompt:3.3.2'

}

Supports Android minSdkVersion 14

Usage

Tap target prompts are created with a builder class much like the Android AlertDialog builder:

Java

Kotlin

builder
 =
 new
 MaterialTapTargetPrompt
.
Builder
(
MainActivity
.
this
)

builder
 =
 MaterialTapTargetPrompt
.
Builder
(
this
@MainActivity
)

Set the view to focus the prompt on:

Java

Kotlin

builder
.
setTarget
(
R
.
id
.
target_view_id
)

builder
.
target
 =
 R
.
id
.
target_view_id

Set the text to display on the first line:

Java

Kotlin

builder
.
setPrimaryText
(
"This text is displayed on the first line"
);

builder
.
primaryText
 =
 "This text is displayed on the first line"

Optionally set the text to display on the second line. If the primary text is not set the secondary text must be set

Java

Kotlin

builder
.
setSecondaryText
(
"Text to display on the second line"
)

builder
.
secondaryText
 =
 "Text to display on the second line"

To listen in to the prompt events set a PromptStateChangeListener. Possible states are:

STATE_NOT_SHOWN - Prompt has yet to be shown
STATE_REVEALING - Prompt reveal animation is running
STATE_REVEALED - Prompt reveal animation has finished and the prompt is displayed
STATE_FOCAL_PRESSED - Prompt target has been pressed
STATE_NON_FOCAL_PRESSED - Prompt has been pressed outside the focal area
STATE_DISMISSING - Prompt dismiss method has been called and the prompt is being removed from view
STATE_DISMISSED - Prompt has been removed from view after the prompt has either been pressed somewhere other than the prompt target or the system back button has been pressed
STATE_FINISHING - Prompt finish method has been called and the prompt is being removed from view
STATE_FINISHED - Prompt has been removed from view after the prompt has been pressed in the focal area

Java

Kotlin

builder
.
setPromptStateChangeListener
(
new
 MaterialTapTargetPrompt
.
PromptStateChangeListener
()

        {

            @Override

            public
 void
 onPromptStateChanged
(
MaterialTapTargetPrompt
 prompt
,
 int
 state
)

            {

                if
 (
state
 ==
 MaterialTapTargetPrompt
.
STATE_FOCAL_PRESSED
)

                {

                    // User has pressed the prompt target

                }

            }

        })

builder
.
setPromptStateChangeListener
 {
 prompt
,
 state
 ->

    if
 (
state
 ==
 MaterialTapTargetPrompt
.
STATE_FOCAL_PRESSED
)

    {

        // User has pressed the prompt target

    }

}

The Builder extends abstract class PromptOptions which contains more customisation options.

Finally show the tap target:

Java

Kotlin

builder
.
show
()

builder
.
show
()

All combined together:

Java

Kotlin

import
 uk.co.samuelwall.materialtaptargetprompt.MaterialTapTargetPrompt
;


new
 MaterialTapTargetPrompt
.
Builder
(
MainActivity
.
this
)

        .
setTarget
(
R
.
id
.
target_view_id
)

        .
setPrimaryText
(
"This text is displayed on the first line"
)

        .
setSecondaryText
(
"Text to display on the second line"
)

        .
setPromptStateChangeListener
(
new
 MaterialTapTargetPrompt
.
PromptStateChangeListener
()

        {

            @Override

            public
 void
 onPromptStateChanged
(
MaterialTapTargetPrompt
 prompt
,
 int
 state
)

            {

                if
 (
state
 ==
 MaterialTapTargetPrompt
.
STATE_FOCAL_PRESSED
)

                {

                    // User has pressed the prompt target

                }

            }

        })

        .
show
();

import
 uk.co.samuelwall.materialtaptargetprompt.MaterialTapTargetPrompt;


MaterialTapTargetPrompt
.
Builder
(
this
@MainActivity
)

        .
setTarget
(
R
.
id
.
target_view_id
)

        .
setPrimaryText
(
"This text is displayed on the first line"
)

        .
setSecondaryText
(
"Text to display on the second line"
)

        .
setPromptStateChangeListener
 {
 prompt
,
 state
 ->

            if
 (
state
 ==
 MaterialTapTargetPrompt
.
STATE_FOCAL_PRESSED
)

            {

                // User has pressed the prompt target

            }

        }

        .
show
()

Note

If a target is not set or the target view could not be found or both the primary and secondary text are null then builder.show and builder.create will return null.

Customisation

The library is designed with extendable classes to allow for maximum customisation. More details and examples are available here .

License

Copyright (C) 2016-2018 Samuel Wall

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.

Edit this page