ShowcaseView

This ShowcaseView library can be used to showcase any specific part of the UI or can even be used during OnBoarding of a user to give a short intro about different widgets visible on the screen. You may add any number of views (ImageView, TextView, FrameLayout, etc displaying images, videos, GIF, text etc) to describe the showcasing view.

Try out sample application on Android PlayStore

Usage

For a working implementation of this project see the /app folder

1. Include the library as local library project or add this dependency in your build.gradle.

         
           dependencies {
             compile 'com.outlander.showcaseview:showcaseview:1.3.0'
           }
         
       

2. Initialise the ShowcaseViewBuilder as follows:

         
           ShowcaseViewBuilder showcaseViewBuilder;
           ...
           showcaseViewBuilder = ShowcaseViewBuilder.init(this)
                   .setTargetView(fab)
                   .setBackgroundOverlayColor(0xdd4d4d4d)
                   .setRingColor(0xcc8e8e8e)
                   .setRingWidth((int) TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, 20, getResources().getDisplayMetrics()))
                   .setMarkerDrawable(getResources().getDrawable(R.drawable.arrow_up), Gravity.LEFT)
                   .addCustomView(R.layout.description_view, Gravity.TOP)
                   .addCustomView(R.layout.skip_layout)
                   .setCustomViewMargin((int) TypedValue.applyDimension(TypedValue.COMPLEX_UNIT_DIP, 70, getResources().getDisplayMetrics()));
       showcaseViewBuilder.show();
     </code>
   </pre>
   
     

3. Register click listeners on the customView added as follows:

           
             showcaseViewBuilder.setClickListenerOnView(R.id.exit_btn, new View.OnClickListener() {
               @Override
               public void onClick(View v) {
                   //TODO: Add thing to do when clicked.
               }
             });
           
         

4. To hide the showcaseView just call:

           
             showcaseViewBuilder.hide()
           
         

5. To hide the showcaseView when user clicks on the overlay, just set the following flag: showcaseViewBuilder.setHideOnTouchOutside(true); By default, this is always false.

#Things to keep in mind

• Call the showcaseViewBuilder.show() only after adding all the customViews and MarkerDrawable.

• setRingWidth(float width) and other margin setters take pixels as parameters. So make sure to send into density independent pixels (dp) value to support multiple screen sizes (See the sample code snippet above for reference)

• Once showcaseViewBuilder.hide() is called, all the click listeners get deregistered. Thus, you will have to set them back if showing it again. Better to register all the click listeners in a single method which can be called when showing the showcaseView.

#Method Definitions

• setTargetView(View v): Sets the view which needs to be showcased.

• setBackgroundOverlayColor(int color): Sets the color of the overlay to be shown.

• setRingColor(int color): Sets the color of the ring around the showcaseView.

• setRingWidth(float width): Sets the width of the ring around the showcaseView. Default value is 10px

• setMarkerDrawable(Drawable drawable, int gravity): Sets the marker drawable if any to point the showcaseView. Also, sets a gravity for the drawable (TOP, LEFT, RIGHT, BOTTOM) around the showcasing view.

• setDrawableLeftMargin(float margin): Sets the marker drawable left margin.

• setDrawableTopMargin(float margin): Sets the marker drawable top margin.

• addCustomView(View view, int gravity): Sets the custom description view to describe the showcaseView. Also, sets a gravity for the view (TOP, LEFT, RIGHT, BOTTOM) around the showcasing view.

• addCustomView(View view): Sets the custom description view to describe the showcaseView. This doesn't takes any gravity as an argument and renders the view as per the gravity defined in the layout file.

• setCustomViewMargin(int margin): Sets the custom description view margin from the showcaseView in the direction of the gravity defined, if any. If no gravity defined, then no point in using this method.

• setHideOnTouchOutside(boolean hide): Sets the flag which decide whether to hide the showcase overlay when user touches on the screen anywhere.

• setClickListenerOnView(int id, View.OnClickListener clickListener): Sets clicklistener on the components of the customView(s) added.

• show(): Start showcasing the targetView.

• hide(): Stop showcasing the targetView.

#Developed by

• Aashish Totla

#License

Copyright Aashish Totla © 2016. All rights reserved.

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.