Package com.flowingcode.vaadin.addons.togglebutton

Class ToggleButton

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.AbstractField<ToggleButton,Boolean>

com.flowingcode.vaadin.addons.togglebutton.ToggleButton

All Implemented Interfaces:

AttachNotifier, BlurNotifier<ToggleButton>, DetachNotifier, Focusable<ToggleButton>, FocusNotifier<ToggleButton>, HasAriaLabel, HasElement, HasEnabled, HasHelper, HasLabel, HasSize, HasStyle, HasTheme, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>, HasThemeVariant<ToggleButtonVariant>, HasTooltip, HasValidationProperties, Serializable

@Tag("fc-toggle-button")
@JsModule("./fc-toggle-button.js")
@CssImport("./styles/fc-toggle-button.css")
public class ToggleButton
extends AbstractField<ToggleButton,Boolean>
implements HasSize, HasLabel, HasAriaLabel, HasTooltip, HasHelper, HasValidationProperties, Focusable<ToggleButton>, HasThemeVariant<ToggleButtonVariant>

A toggle button component built on the core Vaadin Switch, with support for customizable labels and icons on both sides.

The switch itself (value, keyboard, focus, ARIA role and state, read-only and disabled behavior) is provided by an inner Switch. This component adds the field label, the side labels and icons, label highlighting, helper text, error message and theme variants around it. All of them are rendered as regular (light DOM) elements, so the switch can reference them for accessibility and they can be styled from the application.

The field label, helper text, error message and required indicator are implemented here on purpose, even though Switch has its own. The ones in Switch render next to the track, which would place them inside the row, between the side labels and icons. The inner switch is still marked as required (for aria-required) and invalid, and is linked to these elements with aria-labelledby and aria-describedby.

Since:

1.0.0

See Also:

• Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

AbstractField.ComponentValueChangeEvent<C extends Component,V>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

BlurNotifier.BlurEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

FocusNotifier.FocusEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>

Constructor Summary

Constructors

Constructor	Description
ToggleButton()	Creates a new toggle button with an initial value of false.
ToggleButton(boolean initialValue)	Creates a new toggle button with the given initial value.
ToggleButton(String label)	Creates a new toggle button with the given label and an initial value of false.
ToggleButton(String label, boolean initialValue)	Creates a new toggle button with the given label and initial value.

Method Summary

Modifier and Type	Method	Description
Registration	addBlurListener(ComponentEventListener<BlurNotifier.BlurEvent<ToggleButton>> listener)
Registration	addFocusListener(ComponentEventListener<FocusNotifier.FocusEvent<ToggleButton>> listener)
SignalBinding<String>	bindHelperText(Signal<String> helperText)	Binds the helper text to a signal.
SignalBinding<Boolean>	bindReadOnly(Signal<Boolean> readOnly)
SignalBinding<Boolean>	bindRequiredIndicatorVisible(Signal<Boolean> requiredIndicatorVisible)
void	blur()
void	focus()
void	focus(FocusOption... options)
Optional<String>	getAriaLabel()
Optional<String>	getAriaLabelledBy()
String	getErrorMessage()
Component	getHelperComponent()
String	getHelperText()
String	getLabel()
int	getTabIndex()
Tooltip	getTooltip()
boolean	isInvalid()
void	setAriaLabel(String ariaLabel)
void	setAriaLabelledBy(String ariaLabelledBy)
void	setErrorMessage(String errorMessage)
void	setHelperComponent(Component component)
void	setHelperText(String helperText)
void	setInvalid(boolean invalid)
ToggleButton	setItemLabelGenerator(ItemLabelGenerator<Boolean> itemLabelGenerator)	Sets a generator that provides labels for the checked (true) and unchecked (false) states.
void	setLabel(String label)
ToggleButton	setLeftIcon(Component icon)	Sets the icon displayed on the left side of the toggle switch.
ToggleButton	setLeftLabel(String label)	Sets the label displayed on the left side of the toggle switch.
protected void	setPresentationValue(Boolean value)
void	setReadOnly(boolean readOnly)
void	setRequiredIndicatorVisible(boolean requiredIndicatorVisible)
ToggleButton	setRightIcon(Component icon)	Sets the icon displayed on the right side of the toggle switch.
ToggleButton	setRightLabel(String label)	Sets the label displayed on the right side of the toggle switch.
void	setTabIndex(int tabIndex)
Tooltip	setTooltipText(String text)
void	setValue(Boolean value)	Sets the checked state of the toggle.
ToggleButton	withHighlightLabel()	Enables label highlighting: the label on the active side is shown using the color of the active theme variant (PRIMARY, SUCCESS, WARNING, ERROR, or CONTRAST), falling back to the primary color when no color variant is set.
ToggleButton	withIconsInside()	Places icons adjacent to the switch and labels on the outer edges, producing the layout [left-label] [left-icon] [switch] [right-icon] [right-label].
ToggleButton	withIconsOutside()	Restores the default layout where icons are on the outer edges and labels are adjacent to the switch: [left-icon] [left-label] [switch] [right-label] [right-icon].
ToggleButton	withoutHighlightLabel()	Disables label highlighting so both labels are rendered with the same color regardless of the toggle state.

Methods inherited from class com.vaadin.flow.component.AbstractField

addValueChangeListener, bindValue, getEmptyValue, getValue, isEmpty, setModelValue, valueEquals

Methods inherited from class com.vaadin.flow.component.Component

addListener, bindVisible, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTestId, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onAttach, onDetach, onEnabledStateChanged, removeFromParent, scrollIntoView, scrollIntoView, set, setElement, setId, setTestId, setVisible, whenAttached

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.Focusable

addFocusShortcut

Methods inherited from interface com.vaadin.flow.component.HasAriaLabel

setAriaLabelledBy

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasEnabled

bindEnabled, isEnabled, setEnabled

Methods inherited from interface com.vaadin.flow.component.HasSize

bindHeight, bindWidth, getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, bindClassName, bindClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Methods inherited from interface com.vaadin.flow.component.HasTheme

addThemeName, addThemeNames, bindThemeName, bindThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

Methods inherited from interface com.vaadin.flow.component.shared.HasThemeVariant

addThemeVariants, bindThemeVariant, bindThemeVariants, removeThemeVariants, setThemeVariant, setThemeVariants, setThemeVariants

Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip

setTooltipMarkdown

Methods inherited from interface com.vaadin.flow.component.HasValidation

setManualValidation

Methods inherited from interface com.vaadin.flow.component.HasValue

clear, getOptionalValue

Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

isReadOnly, isRequiredIndicatorVisible

Constructor Details

ToggleButton

public ToggleButton()

Creates a new toggle button with an initial value of false.

ToggleButton

public ToggleButton(boolean initialValue)

Creates a new toggle button with the given initial value.

Parameters:

initialValue - the initial checked state

Since:

1.0.0

ToggleButton

public ToggleButton(String label)

Creates a new toggle button with the given label and an initial value of false.

Parameters:

label - the label text shown above the toggle

Since:

1.0.0

ToggleButton

public ToggleButton(String label,
 boolean initialValue)

Creates a new toggle button with the given label and initial value.

Parameters:

label - the label text shown above the toggle

initialValue - the initial checked state

Since:

1.0.0

Method Details

setValue

public void setValue(Boolean value)

Sets the checked state of the toggle.

Specified by:

setValue in interface HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

Overrides:

setValue in class AbstractField<ToggleButton,Boolean>

Parameters:

value - the new value; must not be null

Throws:

NullPointerException - if value is null

setPresentationValue

protected void setPresentationValue(Boolean value)

Specified by:

setPresentationValue in class AbstractField<ToggleButton,Boolean>

setReadOnly

public void setReadOnly(boolean readOnly)

Specified by:

setReadOnly in interface HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

Specified by:

setReadOnly in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

setRequiredIndicatorVisible

public void setRequiredIndicatorVisible(boolean requiredIndicatorVisible)

Specified by:

setRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

Specified by:

setRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

bindReadOnly

public SignalBinding<Boolean> bindReadOnly(Signal<Boolean> readOnly)

Specified by:

bindReadOnly in interface HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

Specified by:

bindReadOnly in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

bindRequiredIndicatorVisible

public SignalBinding<Boolean> bindRequiredIndicatorVisible(Signal<Boolean> requiredIndicatorVisible)

Specified by:

bindRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

Specified by:

bindRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<ToggleButton,Boolean>,Boolean>

setLabel

public void setLabel(String label)

Specified by:

setLabel in interface HasLabel

getLabel

public String getLabel()

Specified by:

getLabel in interface HasLabel

setAriaLabel

public void setAriaLabel(String ariaLabel)

Specified by:

setAriaLabel in interface HasAriaLabel

getAriaLabel

public Optional<String> getAriaLabel()

Specified by:

getAriaLabel in interface HasAriaLabel

setAriaLabelledBy

public void setAriaLabelledBy(String ariaLabelledBy)

Specified by:

setAriaLabelledBy in interface HasAriaLabel

getAriaLabelledBy

public Optional<String> getAriaLabelledBy()

Specified by:

getAriaLabelledBy in interface HasAriaLabel

focus

public void focus()

Specified by:

focus in interface Focusable<ToggleButton>

focus

public void focus(FocusOption... options)

Specified by:

focus in interface Focusable<ToggleButton>

blur

public void blur()

Specified by:

blur in interface Focusable<ToggleButton>

addFocusListener

public Registration addFocusListener(ComponentEventListener<FocusNotifier.FocusEvent<ToggleButton>> listener)

Specified by:

addFocusListener in interface FocusNotifier<ToggleButton>

addBlurListener

public Registration addBlurListener(ComponentEventListener<BlurNotifier.BlurEvent<ToggleButton>> listener)

Specified by:

addBlurListener in interface BlurNotifier<ToggleButton>

setTabIndex

public void setTabIndex(int tabIndex)

Specified by:

setTabIndex in interface Focusable<ToggleButton>

getTabIndex

public int getTabIndex()

Specified by:

getTabIndex in interface Focusable<ToggleButton>

setTooltipText

public Tooltip setTooltipText(String text)

Specified by:

setTooltipText in interface HasTooltip

getTooltip

public Tooltip getTooltip()

Specified by:

getTooltip in interface HasTooltip

setHelperText

public void setHelperText(String helperText)

Specified by:

setHelperText in interface HasHelper

getHelperText

public String getHelperText()

Specified by:

getHelperText in interface HasHelper

bindHelperText

public SignalBinding<String> bindHelperText(Signal<String> helperText)

Binds the helper text to a signal. The helper is shown only while the text is not blank, and linked to the switch with aria-describedby.

Specified by:

bindHelperText in interface HasHelper

Parameters:

helperText - the signal to bind the helper text to; must not be null

Returns:

the signal binding

setHelperComponent

public void setHelperComponent(Component component)

Specified by:

setHelperComponent in interface HasHelper

getHelperComponent

public Component getHelperComponent()

Specified by:

getHelperComponent in interface HasHelper

setErrorMessage

public void setErrorMessage(String errorMessage)

Specified by:

setErrorMessage in interface HasValidation

Specified by:

setErrorMessage in interface HasValidationProperties

getErrorMessage

public String getErrorMessage()

Specified by:

getErrorMessage in interface HasValidation

Specified by:

getErrorMessage in interface HasValidationProperties

setInvalid

public void setInvalid(boolean invalid)

Specified by:

setInvalid in interface HasValidation

Specified by:

setInvalid in interface HasValidationProperties

isInvalid

public boolean isInvalid()

Specified by:

isInvalid in interface HasValidation

Specified by:

isInvalid in interface HasValidationProperties

setItemLabelGenerator

public ToggleButton setItemLabelGenerator(ItemLabelGenerator<Boolean> itemLabelGenerator)

Sets a generator that provides labels for the checked (true) and unchecked (false) states. The generator is called with the state value and its result is used as the right label for true and the left label for false.

Parameters:

itemLabelGenerator - the label generator; must not be null

Returns:

this instance for method chaining

Since:

1.0.0

withHighlightLabel

public ToggleButton withHighlightLabel()

Enables label highlighting: the label on the active side is shown using the color of the active theme variant (PRIMARY, SUCCESS, WARNING, ERROR, or CONTRAST), falling back to the primary color when no color variant is set. The inactive-side label is dimmed.

Returns:

this instance for method chaining

Since:

1.0.0

withIconsInside

public ToggleButton withIconsInside()

Places icons adjacent to the switch and labels on the outer edges, producing the layout [left-label] [left-icon] [switch] [right-icon] [right-label].

By default the order is [left-icon] [left-label] [switch] [right-label] [right-icon].

Returns:

this instance for method chaining

Since:

1.0.0

withIconsOutside

public ToggleButton withIconsOutside()

Restores the default layout where icons are on the outer edges and labels are adjacent to the switch: [left-icon] [left-label] [switch] [right-label] [right-icon].

Returns:

this instance for method chaining

Since:

1.0.0

withoutHighlightLabel

public ToggleButton withoutHighlightLabel()

Disables label highlighting so both labels are rendered with the same color regardless of the toggle state.

Returns:

this instance for method chaining

Since:

1.0.0

setLeftLabel

public ToggleButton setLeftLabel(String label)

Sets the label displayed on the left side of the toggle switch.

Parameters:

label - the left label text

Returns:

this instance for method chaining

Since:

1.0.0

setRightLabel

public ToggleButton setRightLabel(String label)

Sets the label displayed on the right side of the toggle switch.

Parameters:

label - the right label text

Returns:

this instance for method chaining

Since:

1.0.0

setLeftIcon

public ToggleButton setLeftIcon(Component icon)

Sets the icon displayed on the left side of the toggle switch.

Parameters:

icon - the component to use as the left icon

Returns:

this instance for method chaining

Since:

1.0.0

setRightIcon

public ToggleButton setRightIcon(Component icon)

Sets the icon displayed on the right side of the toggle switch.

Parameters:

icon - the component to use as the right icon

Returns:

this instance for method chaining

Since:

1.0.0