MaterialCheckBox

public class MaterialCheckBox
extends AppCompatCheckBox

java.lang.Object
   ↳ android.view.View
     ↳ android.widget.TextView
       ↳ android.widget.Button
         ↳ android.widget.CompoundButton
           ↳ android.widget.CheckBox
             ↳ androidx.appcompat.widget.AppCompatCheckBox
               ↳ com.google.android.material.checkbox.MaterialCheckBox


A class that creates a Material Themed CheckBox.

This class uses attributes from the Material Theme to style a CheckBox. It behaves similarly to AppCompatCheckBox, but with color changes and the support of the indeterminate state, and an independent error state.

The checkbox is composed of an app:buttonCompat button drawable (the squared icon) and an app:buttonIcon icon drawable (the checkmark icon) layered on top of it. Their colors can be customized via app:buttonTint and app:buttonIconTint respectively.

If setting a custom app:buttonCompat, make sure to also set app:buttonIcon if an icon is desired. The checkbox does not support having a custom app:buttonCompat and preserving the default app:buttonIcon checkmark at the same time.

For more information, see the component developer guidance and design guidelines.

Summary

Nested classes

interface MaterialCheckBox.OnCheckedStateChangedListener

Callback interface invoked when one of three independent checkbox states change. 

interface MaterialCheckBox.OnErrorChangedListener

Callback interface invoked when the checkbox error state changes. 

XML attributes

MaterialCheckBox_buttonIcon  
MaterialCheckBox_buttonIconTint  
MaterialCheckBox_buttonIconTintMode  
MaterialCheckBox_errorAccessibilityLabel  
MaterialCheckBox_errorShown  

Constants

int STATE_CHECKED

The checked state of the checkbox.

int STATE_INDETERMINATE

The indeterminate state of the checkbox.

int STATE_UNCHECKED

The unchecked state of the checkbox.

Inherited constants

Inherited fields

Public constructors

MaterialCheckBox(Context context)
MaterialCheckBox(Context context, AttributeSet attrs)
MaterialCheckBox(Context context, AttributeSet attrs, int defStyleAttr)

Public methods

void addOnCheckedStateChangedListener(MaterialCheckBox.OnCheckedStateChangedListener listener)

Adds a MaterialCheckBox.OnCheckedStateChangedListener that will be invoked when the checkbox state changes.

void addOnErrorChangedListener(MaterialCheckBox.OnErrorChangedListener listener)

Adds a MaterialCheckBox.OnErrorChangedListener that will be invoked when the checkbox error state changes.

void clearOnCheckedStateChangedListeners()

Removes all previously added MaterialCheckBox.OnCheckedStateChangedListeners.

void clearOnErrorChangedListeners()

Remove all previously added MaterialCheckBox.OnErrorChangedListeners.

Drawable getButtonDrawable()
Drawable getButtonIconDrawable()

Returns the button icon drawable, or null if none.

ColorStateList getButtonIconTintList()

Returns the checkbox button icon's tint list.

PorterDuff.Mode getButtonIconTintMode()

Returns the blending mode used to apply the tint to the button icon drawable.

ColorStateList getButtonTintList()
int getCheckedState()

Returns the current checkbox state.

CharSequence getErrorAccessibilityLabel()

Returns the accessibility label used for the error state announcement.

boolean isCenterIfNoTextEnabled()

Returns true if this MaterialCheckBox will center the checkbox icon when there is no text.

boolean isChecked()
boolean isErrorShown()

Returns whether the checkbox is on error state.

boolean isUseMaterialThemeColors()

Returns true if this MaterialCheckBox defaults to colors from a Material Theme.

void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info)
void onRestoreInstanceState(Parcelable state)
Parcelable onSaveInstanceState()
void removeOnCheckedStateChangedListener(MaterialCheckBox.OnCheckedStateChangedListener listener)

Removes a listener that was previously added via addOnCheckedStateChangedListener(OnCheckedStateChangedListener)

void removeOnErrorChangedListener(MaterialCheckBox.OnErrorChangedListener listener)

Remove a listener that was previously added via addOnErrorChangedListener(OnErrorChangedListener)

void setButtonDrawable(int resId)
void setButtonDrawable(Drawable drawable)
void setButtonIconDrawable(Drawable drawable)

Sets the button icon drawable of the checkbox.

void setButtonIconDrawableResource(int resId)

Sets the button icon drawable of the checkbox.

void setButtonIconTintList(ColorStateList tintList)

Sets the checkbox button icon's tint list, if an icon is present.

void setButtonIconTintMode(PorterDuff.Mode tintMode)

Specifies the blending mode used to apply the tint specified by setButtonIconTintList(ColorStateList)} to the button icon drawable.

void setButtonTintList(ColorStateList tintList)
void setButtonTintMode(PorterDuff.Mode tintMode)
void setCenterIfNoTextEnabled(boolean centerIfNoTextEnabled)

Sets whether this MaterialCheckBox should center the checkbox icon when there is no text.

void setChecked(boolean checked)
void setCheckedState(int checkedState)

Sets the MaterialCheckBox.CheckedState of the checkbox.

void setEnabled(boolean enabled)
void setErrorAccessibilityLabel(CharSequence errorAccessibilityLabel)

Sets the accessibility label to be used for the error state announcement by screen readers.

void setErrorAccessibilityLabelResource(int resId)

Sets the accessibility label to be used for the error state announcement by screen readers.

void setErrorShown(boolean errorShown)

Sets whether the checkbox should be on error state.

void setOnCheckedChangeListener(CompoundButton.OnCheckedChangeListener listener)
void setStateDescription(CharSequence stateDescription)
void setUseMaterialThemeColors(boolean useMaterialThemeColors)

Forces the MaterialCheckBox to use colors from a Material Theme.

void toggle()

Protected methods

void onAttachedToWindow()
int[] onCreateDrawableState(int extraSpace)
void onDraw(Canvas canvas)

Inherited methods

XML attributes

MaterialCheckBox_buttonIcon

Related methods:

MaterialCheckBox_buttonIconTint

Related methods:

MaterialCheckBox_buttonIconTintMode

Related methods:

MaterialCheckBox_errorAccessibilityLabel

Related methods:

MaterialCheckBox_errorShown

Related methods:

Constants

STATE_CHECKED

public static final int STATE_CHECKED

The checked state of the checkbox.

Constant Value: 1 (0x00000001)

STATE_INDETERMINATE

public static final int STATE_INDETERMINATE

The indeterminate state of the checkbox.

Constant Value: 2 (0x00000002)

STATE_UNCHECKED

public static final int STATE_UNCHECKED

The unchecked state of the checkbox. A checkbox is unchecked by default.

Constant Value: 0 (0x00000000)

Public constructors

MaterialCheckBox

public MaterialCheckBox (Context context)

Parameters
context Context

MaterialCheckBox

public MaterialCheckBox (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

MaterialCheckBox

public MaterialCheckBox (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

Public methods

addOnCheckedStateChangedListener

public void addOnCheckedStateChangedListener (MaterialCheckBox.OnCheckedStateChangedListener listener)

Adds a MaterialCheckBox.OnCheckedStateChangedListener that will be invoked when the checkbox state changes.

Components that add a listener should take care to remove it when finished via removeOnCheckedStateChangedListener(OnCheckedStateChangedListener).

Parameters
listener MaterialCheckBox.OnCheckedStateChangedListener: listener to add

addOnErrorChangedListener

public void addOnErrorChangedListener (MaterialCheckBox.OnErrorChangedListener listener)

Adds a MaterialCheckBox.OnErrorChangedListener that will be invoked when the checkbox error state changes.

Components that add a listener should take care to remove it when finished via removeOnErrorChangedListener(OnErrorChangedListener).

Parameters
listener MaterialCheckBox.OnErrorChangedListener: listener to add

clearOnCheckedStateChangedListeners

public void clearOnCheckedStateChangedListeners ()

Removes all previously added MaterialCheckBox.OnCheckedStateChangedListeners.

clearOnErrorChangedListeners

public void clearOnErrorChangedListeners ()

Remove all previously added MaterialCheckBox.OnErrorChangedListeners.

getButtonDrawable

public Drawable getButtonDrawable ()

Returns
Drawable

getButtonIconDrawable

public Drawable getButtonIconDrawable ()

Returns the button icon drawable, or null if none.

This method expects that the icon will be the second layer of a two-layer drawable.

Related XML Attributes:

Returns
Drawable

getButtonIconTintList

public ColorStateList getButtonIconTintList ()

Returns the checkbox button icon's tint list.

Related XML Attributes:

Returns
ColorStateList

getButtonIconTintMode

public PorterDuff.Mode getButtonIconTintMode ()

Returns the blending mode used to apply the tint to the button icon drawable.

Returns
PorterDuff.Mode

getButtonTintList

public ColorStateList getButtonTintList ()

Returns
ColorStateList

getCheckedState

public int getCheckedState ()

Returns the current checkbox state.

Returns
int

getErrorAccessibilityLabel

public CharSequence getErrorAccessibilityLabel ()

Returns the accessibility label used for the error state announcement.

Related XML Attributes:

Returns
CharSequence

isCenterIfNoTextEnabled

public boolean isCenterIfNoTextEnabled ()

Returns true if this MaterialCheckBox will center the checkbox icon when there is no text.

Returns
boolean

isChecked

public boolean isChecked ()

Returns
boolean

isErrorShown

public boolean isErrorShown ()

Returns whether the checkbox is on error state.

Related XML Attributes:

Returns
boolean

isUseMaterialThemeColors

public boolean isUseMaterialThemeColors ()

Returns true if this MaterialCheckBox defaults to colors from a Material Theme.

Returns
boolean

onInitializeAccessibilityNodeInfo

public void onInitializeAccessibilityNodeInfo (AccessibilityNodeInfo info)

Parameters
info AccessibilityNodeInfo

onRestoreInstanceState

public void onRestoreInstanceState (Parcelable state)

Parameters
state Parcelable

onSaveInstanceState

public Parcelable onSaveInstanceState ()

Returns
Parcelable

removeOnCheckedStateChangedListener

public void removeOnCheckedStateChangedListener (MaterialCheckBox.OnCheckedStateChangedListener listener)

Removes a listener that was previously added via addOnCheckedStateChangedListener(OnCheckedStateChangedListener)

Parameters
listener MaterialCheckBox.OnCheckedStateChangedListener: listener to remove

removeOnErrorChangedListener

public void removeOnErrorChangedListener (MaterialCheckBox.OnErrorChangedListener listener)

Remove a listener that was previously added via addOnErrorChangedListener(OnErrorChangedListener)

Parameters
listener MaterialCheckBox.OnErrorChangedListener: listener to remove

setButtonDrawable

public void setButtonDrawable (int resId)

Parameters
resId int

setButtonDrawable

public void setButtonDrawable (Drawable drawable)

Parameters
drawable Drawable

setButtonIconDrawable

public void setButtonIconDrawable (Drawable drawable)

Sets the button icon drawable of the checkbox.

The icon will be layered above the button drawable set by setButtonDrawable(Drawable).

Related XML Attributes:

Parameters
drawable Drawable: the icon drawable to be set

setButtonIconDrawableResource

public void setButtonIconDrawableResource (int resId)

Sets the button icon drawable of the checkbox.

The icon will be layered above the button drawable set by setButtonDrawable(Drawable).

Related XML Attributes:

Parameters
resId int: resource id of the drawable to set, or 0 to clear and remove the icon

setButtonIconTintList

public void setButtonIconTintList (ColorStateList tintList)

Sets the checkbox button icon's tint list, if an icon is present.

This method expects that the icon will be the second layer of a two-layer drawable.

Related XML Attributes:

Parameters
tintList ColorStateList: the tint to set on the button icon

setButtonIconTintMode

public void setButtonIconTintMode (PorterDuff.Mode tintMode)

Specifies the blending mode used to apply the tint specified by setButtonIconTintList(ColorStateList)} to the button icon drawable. The default mode is PorterDuff.Mode.SRC_IN.

Related XML Attributes:

Parameters
tintMode PorterDuff.Mode: the blending mode used to apply the tint

setButtonTintList

public void setButtonTintList (ColorStateList tintList)

Parameters
tintList ColorStateList

setButtonTintMode

public void setButtonTintMode (PorterDuff.Mode tintMode)

Parameters
tintMode PorterDuff.Mode

setCenterIfNoTextEnabled

public void setCenterIfNoTextEnabled (boolean centerIfNoTextEnabled)

Sets whether this MaterialCheckBox should center the checkbox icon when there is no text. Default is true.

Parameters
centerIfNoTextEnabled boolean

setChecked

public void setChecked (boolean checked)

Parameters
checked boolean

setCheckedState

public void setCheckedState (int checkedState)

Sets the MaterialCheckBox.CheckedState of the checkbox.

Parameters
checkedState int: the checked, unchecked, or indeterminate state to be set

See also:

setEnabled

public void setEnabled (boolean enabled)

Parameters
enabled boolean

setErrorAccessibilityLabel

public void setErrorAccessibilityLabel (CharSequence errorAccessibilityLabel)

Sets the accessibility label to be used for the error state announcement by screen readers.

Related XML Attributes:

Parameters
errorAccessibilityLabel CharSequence: the error announcement

setErrorAccessibilityLabelResource

public void setErrorAccessibilityLabelResource (int resId)

Sets the accessibility label to be used for the error state announcement by screen readers.

Related XML Attributes:

Parameters
resId int: resource ID of the error announcement text

setErrorShown

public void setErrorShown (boolean errorShown)

Sets whether the checkbox should be on error state. If true, the error color will be applied to the checkbox.

Related XML Attributes:

Parameters
errorShown boolean: whether the checkbox should be on error state.

See also:

setOnCheckedChangeListener

public void setOnCheckedChangeListener (CompoundButton.OnCheckedChangeListener listener)

Parameters
listener CompoundButton.OnCheckedChangeListener

setStateDescription

public void setStateDescription (CharSequence stateDescription)

Parameters
stateDescription CharSequence

setUseMaterialThemeColors

public void setUseMaterialThemeColors (boolean useMaterialThemeColors)

Forces the MaterialCheckBox to use colors from a Material Theme. Overrides any specified ButtonTintList. If set to false, sets the tints to null.

Parameters
useMaterialThemeColors boolean

toggle

public void toggle ()

Protected methods

onAttachedToWindow

protected void onAttachedToWindow ()

onCreateDrawableState

protected int[] onCreateDrawableState (int extraSpace)

Parameters
extraSpace int

Returns
int[]

onDraw

protected void onDraw (Canvas canvas)

Parameters
canvas Canvas