StateView

An alternate state control for views for Android. Can be used to show that a RecyclerView or any other View has no data

💪 Installation

Add the library to the dependencies { ... } section of your app level build.gradle file:

// Refer to the badge named Download for the version number.
implementation 'com.kishannareshpal:stateview:<version>'

🍺 Usage

In the layout:

<com.kishannareshpal.stateview.StateView
     android:id="@+id/stateview"
     android:layout_width="match_parent"
     android:layout_height="wrap_content"
     app:stateMode="normal">

        <!-- 
         Place 1 child view here.
         E.g.: <RecyclerView .../> 
        -->
</com.kishannareshpal.stateview.StateView>

NOTE: You can only add One (1) child view to StateView. If you try adding more than one child view, you will get an IllegalStateException.

Attributes

Attribute	Description	Data Type	Enums	Default Value
app:stateMode	Sets the state mode.	enum	normal alternate	normal
app:stateBackgroundColor	Sets the background color for the alternate state mode.	color	n/a	#FFFFFF (white)
app:stateGravity	Change the alternate state components gravity (icon, title, icons, progress bars, description, button)	enum	left center right	center
app:stateContentPaddingLeft	Change the left content padding.	dimension (dp)	n/a	18dp
app:stateContentPaddingTop	Change the top content padding.	dimension (dp)	n/a	18dp
app:stateContentPaddingRight	Change the right content padding.	dimension (dp)	n/a	18dp
app:stateContentPaddingBottom	Change the bottom content padding.	dimension (dp)	n/a	18dp
app:stateMainProgressEnabled	If the main circular progress is enabled/shown.	boolean	n/a	true
app:stateSmallProgressEnabled	If the small circular progress is enabled/shown.	boolean	n/a	true
app:stateProgressStrokeColor	Sets the circular progress stroke color.	color	n/a	#000 (black)
app:stateProgressBackgroundColor	Sets the circular progress background color	color	n/a	#00000000 (transparent)
app:stateIcon	Sets a 56x56dp image.	drawable	n/a	null
app:stateTitle	Sets the title text.	string	n/a	null
app:stateTitleTextSize	Sets the title text size.	dimension (sp)	n/a	24sp
app:stateTitleTextColor	Sets the title text color.	color	n/a	#000 (black)
app:stateTitleTextAppearance	Customize color, fontFamily, size via style for title text.	StyleRes	n/a	@style/StateViewTheme.TitleTextAppearance
app:stateDescription	Sets the description text.	string	n/a	null
app:stateDescriptionTextSize	Sets the description text size.	dimension (sp)	n/a	16sp
app:stateDescriptionTextColor	Sets the description text color	color	n/a	#3f3f3f (dark grey)
app:stateDescriptionTextAppearance	Customize color, fontFamily, size via style for description text.	StyleRes	n/a	@style/StateViewTheme.DescriptionTextAppearance
app:stateActionButtonText	Sets the action button text.	string	n/a	null
app:stateActionButtonTextColor	Sets the action button text color.	color	n/a	#fff (white)
app:stateActionButtonColor	Sets the action button background color.	color	n/a	#000 (black)
app:stateActionButtonCornerRadius	Sets the action button corner radius.	dimension (dp)	n/a	rounded (64dp)
app:stateActionButtonTextAppearance	Customize color, fontFamily, size via style for action button text.	StyleRes	n/a	@style/StateViewTheme.ActionButton TextAppearance

Theming

You can overwrite StateViewTheme in your styles.xml to apply your customized theme for the StateView:

<styles name="MyStateViewTheme" parent="StateViewTheme">
    <!-- Customize the stateview here with any attribute listed
       on the atrributes table above. 
    -->

    <!-- Example: -->
    <item name="stateBackgroundColor">#ff6363</item>
    <item name="stateActionButtonCornerRadius">8dp</item>
    …    
</styles>

After you have your styles MyStateViewTheme set, use it by applying the style attribute to the StateView in your layout file as follows:

<com.kishannareshpal.stateview.StateView
    …
    style="@style/MyStateViewTheme">

</com.kishannareshpal.stateview.StateView>

TextAppearance Styling (text color, font, size, spacing, ...)

To customise the default text appearance for title, description and actionButton you can override the following styles:

Style names	Description
StateViewTheme.TitleTextAppearance	Styles the title text.
StateViewTheme.DescriptionTextAppearance	Styles the description text.
StateViewTheme.ActionButtonTextAppearance	Styles the action button text.

For example, if you want to style the title, add this to your styles.xml

<styles name="MyTitleTextAppearance" parent="StateViewTheme.TitleTextAppearance">
    <!-- Customize the text appearance for the title -->

    <!-- Example: -->
    <item name="android:fontFamily">@font/times_new_roman</item>
    <item name="android:textColor">@color/blue</item>
    <item name="android:textSize">48sp</item>
    …    
</styles>

Now either apply it to the attribute app:stateTitleTextAppearance in your layout:

<!-- The same applies to
      • app:stateDescriptionTextAppearance
      • app:stateActionButtonTextAppearance 
 -->
<com.kishannareshpal.stateview.StateView
     …
     app:stateTitleTextAppearance="@style/MyTitleTextAppearance">

</com.kishannareshpal.stateview.StateView>

Or in your custom StateView theme:

<styles name="MyStateViewTheme" parent="StateViewTheme">
    …    
    <item name="stateTitleTextAppearance">@style/MyTitleTextAppearance</item>
    <!-- The same applies to
      • <item name="stateDescriptionTextAppearance">…</item>
      • <item name="stateActionButtonTextAppearance">…</item> 
     -->

</styles>

Methods: List

Getters

Name	Return type	Description
getState()	State	Gets the currently set state.
getTitleText()	@Nullable CharSequence	Gets the currently set title text.
getDescriptionText()	@Nullable CharSequence	Gets the currently set description text.
getActionButton()	MaterialButton	Exposes the action button. May be used to customise stuff like adding an icon.

Setter

Name
void backgroundColor(@ColorInt int backgroundColor)
void contentPadding(int left, int top, int right, int bottom)
void contentPadding(int padding)
void gravity(ComponentGravity gravity)
void mainIcon(@Nullable @DrawableRes Integer iconRes, boolean isGif)
void mainProgressEnabled(boolean mainProgressEnabled)
void smallProgressEnabled(boolean smallProgressEnabled)
void progressStrokeColor(@ColorInt int progressStrokeColor)
void progressBackgroundColor(@ColorInt int progressBackgroundColor)
void state(State state) void state(State state, boolean animated)
void title(@Nullable CharSequence title) void title(@Nullable CharSequence title, AnimationType titleTextChangeAnimationType)
void titleTextSize(int titleTextSize)
void titleTextColor(@ColorInt int titleTextColor)
void description(@Nullable CharSequence description)
void description(@Nullable CharSequence description, AnimationType descriptionTextChangeAnimationType)
void descriptionTextColor(@ColorInt int descriptionTextColor)
void descriptionTextSize(int descriptionTextSize)
void actionButtonText(@Nullable CharSequence actionButtonText)
void actionButtonCornerRadius(int actionButtonCornerRadius)
void actionButtonTextColor(@ColorInt int actionButtonTextColor)
void actionButtonColor(@ColorInt int actionButtonColor)
void onActionButtonClick(OnActionButtonClickListener onActionButtonClickListener)
void actionButtonEnabled(boolean enabled)
void actionButtonIsVisible(boolean isVisible)

Methods: Details

backgroundColor

Changes the default background color of the state view in State#NORMAL.

public void backgroundColor (@ColorInt int backgroundColor)

Parameter	Description
backgroundColor	@ColorInt int: the background color you want to set. Use ContextCompat#getColor(Context, int)

contentPadding

Change the content padding.

public void contentPadding (int left, int top, int right, int bottom)
public void contentPadding (int padding)

Parameter	Description
padding	int: all sides padding.
left	int: left side padding.
top	int: top side padding.
right	int: right side padding.
bottom	int: bottom side padding.

gravity

Change the gravity of the state view components in State#ALTERNATE.

public void gravity (ComponentGravity gravity)

Parameter	Description
gravity	ComponentGravity: the gravity of title, main progress, description and button on State#ALTERNATE . This is an enum consisting of three (3) values: LEFT: to set the gravity to the left (start) CENTER: to set the gravity to the center. RIGHT: to set the gravity to the right (end).

mainIcon

Change the icon.

public void mainIcon (@Nullable @DrawableRes Integer iconRes, boolean isGif)

Parameter	Description
iconRes	@Nullable @DrawableRes Integer: the drawable resource identifier. If null, icon will be hidden.
isGif	boolean: set this to true if you are passing a .gif file to iconRes to view it animate infinitely.

mainProgressEnabled

Shows/hides the main circular progress.

public void mainProgressEnabled (boolean mainProgressEnabled)

Parameter	Description
mainProgressEnabled	boolean: set this to true to show the main circular progress (this will replace the icon). If false, the main progress will be hidden (and be replaced with the icon if mainIcon is set).

smallProgressEnabled

Shows/hides the small circular progress.

public void smallProgressEnabled (boolean smallProgressEnabled)

Parameter	Description
smallProgressEnabled	boolean: set this to true to show the small circular progress in front of the description text. If false, the small progress will be hidden.

progressStrokeColor

Change all circular progress stroke color.

public void progressStrokeColor (@ColorInt int progressStrokeColor)

Parameter	Description
progressStrokeColor	@ColorInt int: the stroke color of the main and small circular progress. Use ContextCompat#getColor(Context, int)

progressBackgroundColor

Change all circular progress background color.

public void progressBackgroundColor (@ColorInt int progressBackgroundColor)

Parameter	Description
progressBackgroundColor	@ColorInt int: the background color of the main and small circular progress. Use ContextCompat#getColor(Context, int)

state

Change the state.

public void state (State state)
public void state (State state, boolean animated)

Parameter	Description
state	State: the state to which you want to change. This is an enum consisting of two (2) values: NORMAL: use this to view the original view. ALTERNATE: use this for showing the StateView Title, Description and other components.
animated	boolean: if true, show a slight fade animation on the changing of states.

title

Change the title text.

public void title (@Nullable CharSequence title)
public void title (@Nullable CharSequence title, AnimationType titleTextChangeAnimationType)

Parameter	Description
title	@Nullable CharSequence: the title text. If null, title will be hidden.
titleTextChangeAnimationType	AnimationType: the animation type to use when changing the title text. This is an enum consisting of four (4) values: NO_ANIMATION: does not animate the text change. Same as title(CharSequence) SLIDE_TO_TOP: slides the old text to top and back to normal with the new text. SLIDE_TO_BOTTOM: slides the old text to bottom and back to normal with the new text. FADE: fades out the old text and fades in the new text.

titleTextSize

Change the title text size.

public void titleTextSize (int titleTextSize)

Parameter	Description
titleTextSize	int: the title text size in sp.

titleTextColor

Change the title text color

public void titleTextColor (@ColorInt int titleTextColor)

Parameter	Description
titleTextColor	@ColorInt int: the title text color. Use ContextCompat#getColor(Context, int)

description

Change the description text.

public void description (@Nullable CharSequence description)
public void description (@Nullable CharSequence description, AnimationType descriptionTextChangeAnimationType)

Parameter	Description
description	@Nullable CharSequence: the description text. If null, description will be hidden.
descriptionTextChangeAnimationType	AnimationType: the animation type to use when changing the description text. This is an enum consisting of four (4) values: NO_ANIMATION: does not animate the text change. Same as title(CharSequence) SLIDE_TO_TOP: slides the old text to top and back to normal with the new text. SLIDE_TO_BOTTOM: slides the old text to bottom and back to normal with the new text. FADE: fades out the old text and fades in the new text.

descriptionTextSize

Change the description text size.

public void descriptionTextSize (int descriptionTextSize)

Parameter	Description
descriptionTextSize	int: the description text size in sp.

descriptionTextColor

Change the description text color

public void descriptionTextColor (@ColorInt int descriptionTextColor)

Parameter	Description
descriptionTextColor	@ColorInt int: the description text color. Use ContextCompat#getColor(Context, int)

actionButtonText

Change the action button text.

public void actionButtonText (@Nullable CharSequence actionButtonText)

Parameter	Description
actionButtonText	@Nullable CharSequence: the action button text. If null , action button will be hidden.

actionButtonColor

Change the action button background color.

public void actionButtonColor (@ColorInt int actionButtonColor)

Parameter	Description
actionButtonColor	@ColorInt int: the action button background color. Use ContextCompat#getColor(Context, int)

actionButtonCornerRadius

Change the action button corner radius.

public void actionButtonCornerRadius (int actionButtonCornerRadiues)

Parameter	Description
actionButtonCornerRadius	int: corner radius in sp.

actionButtonTextColor

Change the action button text color.

public void actionButtonTextColor (@ColorInt int actionButtonTextColor)

Parameter	Description
actionButtonTextColor	@ColorInt int: the action button text color. Use ContextCompat#getColor(Context, int)

onActionButtonClickListener

The action to execute when the button is clicked.

public void onActionButtonClickListener (OnActionButtonClickListener onActionButtonClickListener)

Parameter	Description

onActionButtonClickListener	OnActionButtonClickListener: Interface definition for a callback to be invoked when the action button is clicked. void OnActionButtonClick(StateView sv, View actionBtn)

actionButtonEnabled

Change the enabled or disabled state of the action button.

public void actionButtonEnabled (boolean actionButtonEnabled)

Parameter	Description
actionButtonEnabled	boolean: if false, action button will be disabled of any touch input, and will have a visually light grey background. Otherwise, enabled.

actionButtonIsVisible

Changes the action button visibility only.

public void actionButtonIsVisible (boolean isVisible)

Parameter	Description
isVisible	boolean: if true, action button will be visible, otherwise, hidden.

🩺 Public Enums

enum State

State consists of two (2) enum values:

• NORMAL: original view.

• ALTERNATE: state view alternate view with custom Title, Description and other components.

enum ComponentGravity

ComponentGravity consists of four (3) enum values:

• LEFT: to set the gravity to the left (start)

• CENTER: to set the gravity to the center/middle.

• RIGHT: to set the gravity to the right (end).

enum AnimationType

AnimationType consists of four (4) enum values:

• NO_ANIMATION: no animation!

• SLIDE_TO_TOP: slides the old text to top and back to normal with the new text.

• SLIDE_TO_BOTTOM: slides the old text to bottom and back to normal with the new text.

• FADE: fades out the old text and fades in the new text.