Welcome to XDA

Search to go directly to your device's forum

Register an account

Unlock full posting privileges

Ask a question

No registration required
Post Reply

[GUIDE] Holo-themed transparent demo overlays with ShowcaseView

OP nikwen

25th August 2013, 07:44 PM   |  #1  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
[GUIDE] Holo-themed transparent demo overlays

Lately I found a great tutorial by @marty331 explaining how to create transparent demo pages on Android.
I really liked his guide. Thanks again.

However, I am no graphics designer. So the pages wouldn't look very good for me.
I did a little research on the internet and found the ShowcaseView library by Alex Curran. It is licensed under an Apache 2.0 License. You can find its source code here.

It is very easy to get stunning, holo-themed results with the library:


(Source: https://raw.github.com/amlcurran/Sho...er/example.png)

Demo app

The developer put a demo app on Google Play to showcase what you can do with the library:



Set-up

For the set-up I'll quote the developer:

Quote:

For people who use Maven, ShowcaseView should work immediately without any issues. If you aren't, you'll need to download the NineOldAndroids library and add it as a dependency library to the ShowcaseView library. Then add ShowcaseView as a library dependency to your project, and you're done!

WARNING: Sometimes Eclipse/IDEA will automatically import the non-NineOldAndroid versions of the animation classes, which will cause crashes on versions of Android below 3.0. Check that your imports start with com.nineoldandroids.animation and not android.animation.

(Source: https://github.com/amlcurran/ShowcaseView#set-up)

Showcasing views

Showcasing views is really easy:

Code:
public class MyActivity extends Activity {

    ShowcaseView sv;

 @override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);

        ShowcaseView.ConfigOptions co = new ShowcaseView.ConfigOptions();
        co.hideOnClickOutside = true;
        sv = ShowcaseView.insertShowcaseView(R.id.showcasedView, this, R.string.showcase_title, R.string.showcase_message, co);
    }
}
That's it.

Showcasing views in Fragments

It is a bit different for Fragments though:

Code:
public class ShowcaseFragment extends Fragment {

    ShowcaseView sv;

 @override
    public View onCreateView(LayoutInflater inflater, ViewGroup container, Bundle savedInstanceState) {
        return inflater.inflate(R.layout.fragment_layout, container);
    }

 @override
    public void onActivityCreated(Bundle savedInstanceState) {
        super.onActivityCreated(savedInstanceState);

        ShowcaseView.ConfigOptions co = new ShowcaseView.ConfigOptions();
        co.hideOnClickOutside = true;
        sv = ShowcaseView.insertShowcaseView(R.id.showcasedView, getActivity(), R.string.showcase_title, R.string.showcase_message, co);
    }
}
To show the ShowcastView setContentView() needs to be called in the Activity first.
So you have to put the code into the onActivityCreated() method.

Setting listerners

You can also add listeners to the ShowcastView:

Code:
sv.setOnShowcaseEventListener(new ShowcaseView.OnShowcaseEventListener() {
 @override
    public void onShowcaseViewHide(ShowcaseView showcaseView) {
        //The view is hidden/dismissed
    }

 @override
    public void onShowcaseViewShow(ShowcaseView showcaseView) {
        //The view is shown
    }
});
Animations

You can also add animations to your app, i.e. a virtual finger performing a gesture.

First you need to showcase the view as above. Then use this method of ShowcaseView:

Code:
public void animateGesture(float offsetStartX,
                           float offsetStartY,
                           float offsetEndX,
                           float offsetEndY)
All values are relative to the center of the view.

For example this is a swipe upwards, beginning at the center of the view:

Code:
sv.animateGesture(0, 0, 0, -400);
Showcasing parts of the ActionBar

Another possiblity is to showcase ActionItems:


(Source: https://lh6.ggpht.com/C7upo-Cx63WFid...g4qo0QAnw=h900)

This is how to do it:

Code:
 @override
public boolean onCreateOptionsMenu(Menu menu) {
    getMenuInflater().inflate(R.menu.menu, menu);

    sv = ShowcaseView.insertShowcaseViewWithType(ShowcaseView.ITEM_ACTION_ITEM, R.id.menu_item1, this,
            R.string.showcase_title, R.string.showcase_message, new ShowcaseView.ConfigOptions());

    return super.onCreateOptionsMenu(menu);
}
(Replace "this" by "getActivity()" in a Fragment.)

There are also other things in the ActionBar which can be highlighted. Just replace ITEM_ACTION_ITEM in the example above with the proper constant:

Quote:

  • ITEM_ACTION_ITEM: An ActionItem
  • ITEM_ACTION_OVERFLOW: The action overflow (The three dots at the right side of the ActionBar which appears if not all items can be shown as icons.)
  • ITEM_TITLE: The title
  • ITEM_ACTION_HOME: HOME arrow in the ActionBar
  • ITEM_SPINNER: A spinner in the ActionBar

Last edited by nikwen; 14th December 2013 at 05:45 PM.
The Following 28 Users Say Thank You to nikwen For This Useful Post: [ View ]
25th August 2013, 07:44 PM   |  #2  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
Customization options

The ShowcaseView can be customized using the ShowcaseView.ConfigOptions object you pass to the ShowcaseView.insertShowcaseView() method.

For some strange reason, there are no getter/setter methods for that class. So you can access the fields of that class directly.

This is the basic code for the following code snippets:

Code:
ShowcaseView.ConfigOptions co = new ShowcaseView.ConfigOptions();
co.hideOnClickOutside = true;
ShowcaseView sv = ShowcaseView.insertShowcaseView(R.id.showcasedView, this, R.string.showcase_title, R.string.showcase_message, co);
Don't respond to touches outside the showcased area

Code:
co.hideOnClickOutside = false;
co.block = true;
The field "block" determines whether the app will respond to touches outside the showcased area.

Don't hide the ShowcaseView on touches outside the showcased area

Code:
co.hideOnClickOutside = false;
The field "hideOnClickOutside" determines whether the view will be hidden when the screen is touched outside the highlighted area.

Set a fade-in or fade-out duration

The proper fields:

Code:
co.fadeInDuration = 1000;
co.fadeOutDuration = 1000;
Using these fields, you can set the time it will take the ShowcaseView to fade in or out.

Don't overlay the ActionBar

Code:
co.insert = ShowcaseView.INSERT_TO_VIEW;
This field allows you to determine whether the ShowcaseView will overlay the ActionBar.

Possible values:

Quote:

  • ShowcaseView.INSERT_TO_DECOR: Will overlay the ActionBar
  • ShowcaseView.INSERT_TO_VIEW: Will just overlay the content, but not the ActionBar


Hide the button

Code:
co.noButton = true;
This field allows you to hide the button of the ShowcaseView.

Show the overlay only once

Code:
co.shotType = ShowcaseView.TYPE_ONE_SHOT;
This field determines how often the overlay should be shown.

Possible values:

Quote:

  • ShowcaseView.TYPE_NO_LIMIT: Every time the Activity is opened
  • ShowcaseView.TYPE_ONE_SHOT: Only once


Change the circle radius

Use the method setShowcaseIndicatorScale(float scaleMultiplier) of ShowcaseView for that:

Code:
sv.setShowcaseIndicatorScale(1.5f);


Theming

The ShowcaseView library offers plenty of options to adjust the appearance of the ShowcaseView.

Fortunately, the library allows you to theme the ShowcaseView as a whole.

To theme the appearance of the ShowcaseView you need to create a style derived from either the ShowcaseView or ShowcaseView.Light style:

Code:
<style name="CustomShowcaseTheme" parent="ShowcaseView.Light">
    <item name="sv_backgroundColor">#33ffbb33</item>
    <item name="sv_buttonBackgroundColor">#CF3119</item>
    <item name="sv_buttonText">Close</item>
    <item name="sv_titleTextAppearance">@style/CustomTitle</item>
    <item name="sv_detailTextAppearance">@style/CustomDetailText</item>
</style>
(Add this to your /res/values/styles.xml file.)

The different options allow you to change the colors of the View and the text of the button.

The text styling is done using TextAppearance styles like this:

Code:
<style name="CustomTitle" parent="TextAppearance.ShowcaseView.Title">
    <item name="android:textColor">#00801A</item>
</style>

<style name="CustomDetailText" parent="TextAppearance.ShowcaseView.Detail">
    <item name="android:textColor">#00801A</item>
</style>
(Add this to your /res/values/styles.xml file.)

For a lighter theme, use "TextAppearance.ShowcaseView.Title.Light" and "TextAppearance.ShowcaseView.Detail.Light" as parent themes instead.

Then add this to the /res/values/styles.xml file as well:

Code:
<style name="CustomAppTheme" parent="android:Theme.Light">
    <item name="showcaseViewStyle">@style/CustomShowcaseTheme</item>
</style>
(You might want to replace Theme.Light by another one.)

Furthermore, add this to the /res/values-v14/styles.xml file:

Code:
<style name="CustomAppTheme" parent="android:Theme.Holo.Light">
    <item name="showcaseViewStyle">@style/CustomShowcaseTheme</item>
</style>
(You might want to replace Theme.Holo.Light by another one.)

The last step is adding this to the <application> tag in your AndroidManifest.xml:

Code:
<application
    android:theme="@style/CustomAppTheme"
    ... />
You're done. You successfully themed your ShowcaseView.

Attributions
  • Big thanks to Alex Curran for the library.
  • I wouldn't have got the idea to write this guide without @marty331's guide. Thank you, Marty.
  • Moreover, I got inspired by the sample folder of the ShowcaseView project.

This was featured on the XDA portal on August 31, 2013.
Last edited by nikwen; 14th December 2013 at 05:39 PM.
The Following 12 Users Say Thank You to nikwen For This Useful Post: [ View ]
26th August 2013, 06:37 AM   |  #3  
Senior Member
Thanks Meter: 31
 
99 posts
Join Date:Joined: Nov 2012
More
cool guide, thanks. Nice work on the pull request too.

Question.

does this allow for showcasing an expanded action item(overflow for example), or do you have to showcase the overflow, have the user select it and keep the showcase highlight?
The Following User Says Thank You to out of ideas For This Useful Post: [ View ]
26th August 2013, 08:32 AM   |  #4  
Senior Member
Flag Rome
Thanks Meter: 295
 
222 posts
Join Date:Joined: May 2013
Donate to Me
More
Good Tutorial, many thanks!

Inviato dal mio Galaxy Nexus
The Following User Says Thank You to CrotaNexus For This Useful Post: [ View ]
26th August 2013, 04:48 PM   |  #5  
marty331's Avatar
Senior Member
Dallas, TX
Thanks Meter: 246
 
782 posts
Join Date:Joined: Jun 2011
More
Good job figuring this out, looks like it just needed to be called from onActivityCreated. I'm going to use this in my app instead of the Overlay View I came up with.
The Following 2 Users Say Thank You to marty331 For This Useful Post: [ View ]
26th August 2013, 05:41 PM   |  #6  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
Quote:
Originally Posted by CrotaNexus

Good Tutorial, many thanks!

Inviato dal mio Galaxy Nexus

Quote:
Originally Posted by marty331

Good job figuring this out, looks like it just needed to be called from onActivityCreated. I'm going to use this in my app instead of the Overlay View I came up with.

Thanks.
26th August 2013, 05:43 PM   |  #7  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
Quote:
Originally Posted by out of ideas

cool guide, thanks. Nice work on the pull request too.

Question.

does this allow for showcasing an expanded action item(overflow for example), or do you have to showcase the overflow, have the user select it and keep the showcase highlight?

Thanks.

Well, I haven't tried that yet. Try it yourself and tell us.
If it does not work, create an issue on Github.
26th August 2013, 08:50 PM   |  #8  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
Added the first customization options.
The Following 2 Users Say Thank You to nikwen For This Useful Post: [ View ]
31st August 2013, 11:08 PM   |  #9  
nikwen's Avatar
OP Recognized Contributor
Thanks Meter: 1,398
 
2,789 posts
Join Date:Joined: Feb 2013
More
Just finished the theming section and therefore the whole guide.
The Following User Says Thank You to nikwen For This Useful Post: [ View ]
1st September 2013, 10:02 AM   |  #10  
Dr.Alexander_Breen's Avatar
Senior Member
Thanks Meter: 1,040
 
433 posts
Join Date:Joined: Jun 2012
Donate to Me
More
So, it does not matter where the view belongs to? Can I use it to showcase a button of a View which was attached to the window by service?

Post Reply Subscribe to Thread

Tags
demo, higlight, holo, overlay, showcaseview
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes