Target API

The new Target API in version 4 is designed to abstract some of the logic out of ShowcaseView, and make it even easier to showcase whatever takes your fancy. First, we'll walk through what the new API does, and then how you can create your own targets.

What's changed?

Previous to the Target API, there were multiple insertShowcaseView(..) constructors which took different parameters. For example, there were constructors for Views, resource IDs, action views, action items and more. Not all the overloaded constructors were available for each type of item to showcase.

The Target API simplifies this by taking each item you'd want to showcase and wrapping it in a Target. For example, there is the new ViewTarget for Views and resource IDs, PointTarget for X/Y co-ordinates and more. This makes the library simpler, more maintainable and much more testable.

What's the same?

Currently using the ShowcaseViews class doesn't use Targets, but will do in the future. The old constructors will stay there for a few released but are marked deprecated - it's highly recommended to move to the new Target API as soon as you can.

Using Targets

To move to using Targets, simply replace your old insertShowcaseView(..) calls with the new ones which take a Target. Here's a quick-and-dirty list of what old calls match which Target constructor:

• insertShowcaseView(int resId, Activity activity...) --> ViewTarget(int resId, Activity activity)
• insertShowcaseView(View view, Activity activity...) --> ViewTarget(View view)
• insertShowcaseView(int x, int y,...) --> PointTarget(int x, int y)

insertShowcaseViewWithType() has changed and is now split in two:

• To showcase the ActionBar spinner, title, overflow button, or home button, use ActionViewTarget with the appropriate enum
• To showcase an Action Item (i.e. one of the buttons with icons on the right), use ActionItemTarget with the menu item ID

If you were using the setShowcaseWhatever() methods, instead use setShowcase(Target).

Making your own Targets

The Targets API is extensible. If you'd like to make your own Target, implement the Target interface and make getPoint() return the point which represents what you'd like to showcase. getPoint() is posted on the UI thread, so you shouldn't have any issues with threading or views not being created in time.

Check out the source if you'd like to see examples of the pre-built Targets.