Free Online Courses for Software Developers - MrBool
× Please, log in to give us a feedback. Click here to login
×

You must be logged to download. Click here to login

×

MrBool is totally free and you can help us to help the Developers Community around the world

Yes, I'd like to help the MrBool and the Developers Community before download

No, I'd like to download without make the donation

×

MrBool is totally free and you can help us to help the Developers Community around the world

Yes, I'd like to help the MrBool and the Developers Community before download

No, I'd like to download without make the donation

How to Create Tour Guide Tooltips in Android Apps

It is very common to have in our apps a way to teach users how to best use them. One of these ways is tooltips. In this article we will learn how to control its components through TourGuide Android library.

One of the main concerns on mobile development applications nowadays is "how to make them the most comfortable and useful" to all kind of users. A lot of apps in Apple Store and Google Play miss it, making users lost and confused. Because of this, many developers and mobile communities (like Google itself) have become more focused on how to increase their programs usability, mainly in their code.

And one important step to prevent users from uninstalling your app after the first try is to add a kind of tour guide to show them how to use it and understand the main parts of it as well. There are many third-party libraries you can use to fulfil this, but the most famous ones are all deprecated. So this will be not a good choice since new SDK versions are released frequently and your app might not be able to adapt to hardware/software changes. That's the case of the well known ShowCase and SuperToolTips libraries that were discontinued and are not accepting new issues and PRs anymore. Anyway, you can find their official web page links at Links section in the end of this article.

For the purposes of this article, we're going to use TourGuide library that allows us to easily add, overlay and tooltip pieces of our screens, in order to guide users on how to use the app.

Figure 1 shows the final screen of our app.

Figure 1. TourGuide app final screen.

1. Add Gradle Dependencies

The first thing we need to do is to create a new project at Android Studio. Those simple steps will be omitted, but if you have any question regarding this, please refer to our Android learning Course (which uses Android Studio by default IDE). After that, open your Gradle dependencies file (build.gradle) located in the app module and add the code listed below:

repositories {
    mavenCentral()
    maven(){
        url "https://oss.sonatype.org/content/repositories/snapshots"
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.android.support:appcompat-v7:22.2.0'
    compile ('com.github.worker8:tourguide:1.0.13-SNAPSHOT@aar'){
        transitive=true
    }
}

This way the app can find TourGuide dependencies. For this project we will also use classes belonging to Android Support v4 lib, but it's not necessary to import it because it comes with Android Studio projects by default.

Plus, the example works only in an Android app created under API level 11+, at least. So, make sure to check this.

2. First Steps

The simplest example is to use the code auto generated by Android Studio in MainActivity. Let's consider we have just a single xml layout page, with the following code:

<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools" android:layout_width="match_parent"
    android:layout_height="match_parent" android:paddingLeft="@dimen/activity_horizontal_margin"
    android:paddingRight="@dimen/activity_horizontal_margin"
    android:paddingTop="@dimen/activity_vertical_margin"
    android:paddingBottom="@dimen/activity_vertical_margin" tools:context=".MainActivity">

    <TextView
        android:text="@string/hello_world"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:id="@+id/txtHelloWorld"/>

    <Button
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        android:id="@+id/btnTest"
        android:layout_below="@id/txtHelloWorld"
        android:text="Click Me" />

</RelativeLayout>

This represents just a TextView within a "Hello World" text and a Button with "Click Me" text and no action assigned to. Suppose also that we are going to create a tip at the exactly position of our button. For it, we can use the following code at onCreate() method in the activity class:

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

    btnClickMe = (Button) findViewById(R.id.btnTest);

    TourGuide mTourGuideHandler = TourGuide.init(this).with(TourGuide.Technique.Click)
            .setPointer(new Pointer())
            .setToolTip(new ToolTip().setTitle("Welcome!").setDescription("Click on Get Started to begin..."))
            .setOverlay(new Overlay())
            .playOn(btnClickMe);
}

Now, run the code and you'll probably see the same as in Figure 2. Let's see some points on the code:

  • Function setPointer() - defines the "pointer" appearance located in front of the widget (button, in this case);
  • Function setTooltTip() - defines the text description of the tooltip title;
  • Function setOverlay() - defines the semi-transparent background surrounding the widget;
  • Function playOn() - receives the widget to locate the tooltip by itself.

Figure 2. TourGuide example with a tooltip over a button

After the exhibition, when the user is done, you can close the tooltip with the following code:

mTourGuideHandler.cleanUp();

If you want to learn how to make tooltips in web environments, please refer to some of our articles/videos below:

Still, it's possible to set a lot of other properties on ToolTip object. You can change the gravity (place where the box appears), shadow, colors and also add an animation to show the tip with effect. Please refer to the documentation (see Links section) to check this out.

For example, using the same example we've done, let's change some basic configuration from TourGuide object:

<TextView
    android:text="Hi, this is a MrBool tooltip"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txtHelloWorld"/>

<Button
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/btnTest"
    android:layout_below="@id/txtHelloWorld"
    android:text="Click Me"
    android:onClick="clickMe"/>

We just added a new text and onClick attribute to the button, in order to handle the right action when it's clicked. For the Java side, we must perform the next changes:

private Button btnClickMe;

private TourGuide mTourGuideHandler;

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

    btnClickMe = (Button) findViewById(R.id.btnTest);

    mTourGuideHandler = TourGuide.init(this).with(TourGuide.Technique.Click)
            .setPointer(new Pointer())
            .setToolTip(
                    new ToolTip()
                            .setTitle("Welcome...")
                            .setDescription("... to MrBool website!!")
                            .setBackgroundColor(Color.parseColor("#e54d26"))
                            .setShadow(true).setGravity(Gravity.TOP | Gravity.RIGHT))
            .setOverlay(new Overlay())
            .playOn(btnClickMe);
}

public void clickMe(View view) {
    mTourGuideHandler.cleanUp();
}

This will be enough to set a different background color, position and add a shadow to the tooltip box. Now, reexecute the application and you must see something like in Figure 3. See how we organized the code. It is important to know where you are exactly when you're coding.

Figure 3. TourGuide app example with different sets.

3. Calling a tooltip from another

In order to get closer to a real application, let's implement another example where we have three buttons calling one another. In this case, we'll use cleanUp() method in each onClick() method assigned to every button.

See the code changes we need to perform at our xml layout:

<TextView
    android:text="Hi, this is a MrBool tooltip"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/txtHelloWorld"/>

<Button
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/btnTest1"
    android:layout_below="@id/txtHelloWorld"
    android:text="Click Me 1"
    android:onClick="clickMe1"/>

<Button
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/btnTest2"
    android:layout_centerInParent="true"
    android:text="Click Me 2"
    android:onClick="clickMe2"/>

<Button
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:id="@+id/btnTest3"
    android:layout_alignParentBottom="true"
    android:text="Click Me 3"
    android:onClick="clickMe3"/>

Now, buttons are organized in different places at the screen, in order to allow us to explore how the tool deals with distinct widget positions. This way, we can simulate a real app, which will have to teach users how to use widgets from different locations. Please, certify to create different ids to each button and align them in different regions on the screen, like we did through layout_align attributes.

Getting back to the activity, let's change our Java code to adapt to the new layout:

private Button btnClickMe1, btnClickMe2, btnClickMe3;

private TourGuide mTourGuideHandler;

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

    btnClickMe1 = (Button) findViewById(R.id.btnTest1);
    btnClickMe2 = (Button) findViewById(R.id.btnTest2);
    btnClickMe3 = (Button) findViewById(R.id.btnTest3);

    mTourGuideHandler = TourGuide.init(this).with(TourGuide.Technique.Click)
            .setPointer(new Pointer())
            .setToolTip(
                    new ToolTip()
                            .setTitle("Welcome...")
                            .setDescription("... to MrBool website!!")
                            .setBackgroundColor(Color.parseColor("#e54d26"))
                            .setShadow(true)
                            .setGravity(Gravity.BOTTOM | Gravity.RIGHT))
            .setOverlay(new Overlay())
            .playOn(btnClickMe1);
}

public void clickMe1(View view) {
    mTourGuideHandler.cleanUp();

    mTourGuideHandler
            .setToolTip(new ToolTip()
                    .setTitle("Here you'll find...")
                    .setDescription("... a lot of good tutorials")
                    .setBackgroundColor(Color.parseColor("#4b4b4b")))
            .playOn(btnClickMe2);
}

public void clickMe2(View view) {
    mTourGuideHandler.cleanUp();

    mTourGuideHandler
            .setToolTip(new ToolTip()
                    .setTitle("Enjoy!!!")
                    .setDescription("and leave a comment if you like it! :)")
                    .setBackgroundColor(Color.parseColor("#0E37EC"))
                    .setGravity(Gravity.TOP | Gravity.RIGHT))
            .playOn(btnClickMe3);
}

public void clickMe3(View view) {
    mTourGuideHandler.cleanUp();
}

Now you can see different configurations for each onClick button methods. You can feel free to set it as you want and make tests to analyse how the app reacts to changes. The secret here is to close (cleanUp()), the previous button, when the actual one is clicked. The last one, clickMe3, must do nothing else other than close the TourGuide handler.

When you reexecute the application, you must see the same as in Figure 4.

Figure 4. Final app example with three tooltips.

Conclusion

As we said, there are other libraries you can use to perform the same implementation. Some of them still receive support from creators as well as from the community, like RoboDemo. It is very simple and too similar to TourGuide (refer to Links section).

For the tour purposes, this is enough to guide your users through how to use things. You must play a bit with it until feel totally comfortable to make things more complex. Remember that, for a better experience, the tour can't be too long and it's a good idea to allow users to skip it at any time.

You can also run this source code example via download link at the top of the page. Good studies.

Links

ShowCaseView GitHub page

https://github.com/amlcurran/ShowcaseView

SuperToolTips GitHub page

https://github.com/nhaarman/supertooltips

TourGuide official website

https://github.com/worker8/TourGuide

RoboDemo official GitHub page

https://github.com/stephanenicolas/RoboDemo



Diogo Souza works as Java Developer at Fulcrum Worldwide and has worked for companies such as Indra Company, Atlantic Institute and Ebix LA. He is also an Android trainer, speaker at events on Java and mobile world and a DevMedia ...

What did you think of this post?
Services
[Close]
To have full access to this post (or download the associated files) you must have MrBool Credits.

  See the prices for this post in Mr.Bool Credits System below:

Individually – in this case the price for this post is US$ 0,00 (Buy it now)
in this case you will buy only this video by paying the full price with no discount.

Package of 10 credits - in this case the price for this post is US$ 0,00
This subscription is ideal if you want to download few videos. In this plan you will receive a discount of 50% in each video. Subscribe for this package!

Package of 50 credits – in this case the price for this post is US$ 0,00
This subscription is ideal if you want to download several videos. In this plan you will receive a discount of 83% in each video. Subscribe for this package!


> More info about MrBool Credits
[Close]
You must be logged to download.

Click here to login