com.vaadin.ui.MultiSelect Maven / Gradle / Ivy
/*
* Copyright (C) 2000-2024 Vaadin Ltd
*
* This program is available under Vaadin Commercial License and Service Terms.
*
* See for the full
* license.
*/
package com.vaadin.ui;
import java.util.Arrays;
import java.util.Collections;
import java.util.LinkedHashSet;
import java.util.Objects;
import java.util.Set;
import java.util.stream.Stream;
import com.vaadin.data.HasValue;
import com.vaadin.event.selection.MultiSelectionListener;
import com.vaadin.shared.Registration;
/**
* Multi selection component which allows to select and deselect multiple items.
*
* @author Vaadin Ltd
*
* @param
* the type of the items to select
*
* @since 8.0
*
*/
public interface MultiSelect extends HasValue> {
/**
* Adds the given items to the set of currently selected items.
*
* By default this does not clear any previous selection. To do that, use
* {@link #deselectAll()}.
*
* If the all the items were already selected, this is a NO-OP.
*
* This is a short-hand for {@link #updateSelection(Set, Set)} with nothing
* to deselect.
*
* @param items
* to add to selection, not {@code null}
*/
public default void select(T... items) {
Objects.requireNonNull(items);
Stream.of(items).forEach(Objects::requireNonNull);
updateSelection(new LinkedHashSet<>(Arrays.asList(items)),
Collections.emptySet());
}
/**
* Removes the given items from the set of currently selected items.
*
* If the none of the items were selected, this is a NO-OP.
*
* This is a short-hand for {@link #updateSelection(Set, Set)} with nothing
* to select.
*
* @param items
* to remove from selection, not {@code null}
*/
public default void deselect(T... items) {
Objects.requireNonNull(items);
Stream.of(items).forEach(Objects::requireNonNull);
updateSelection(Collections.emptySet(),
new LinkedHashSet<>(Arrays.asList(items)));
}
/**
* Updates the selection by adding and removing the given items from it.
*
* If all the added items were already selected and the removed items were
* not selected, this is a NO-OP.
*
* Duplicate items (in both add & remove sets) are ignored and removed
* from the sets.
*
* @param addedItems
* the items to add, not {@code null}
* @param removedItems
* the items to remove, not {@code null}
*/
public void updateSelection(Set addedItems, Set removedItems);
/**
* Returns an immutable set of the currently selected items. It is safe to
* invoke other {@code SelectionModel} methods while iterating over the set.
*
* Implementation note: the iteration order of the items in the
* returned set should be well-defined and documented by the implementing
* class.
*
* @return the items in the current selection, not null
*/
public Set getSelectedItems();
/**
* Deselects all currently selected items.
*/
public default void deselectAll() {
getSelectedItems().forEach(this::deselect);
}
/**
* Returns whether the given item is currently selected.
*
* @param item
* the item to check, not null
* @return {@code true} if the item is selected, {@code false} otherwise
*/
public default boolean isSelected(T item) {
return getSelectedItems().contains(item);
}
/**
* Adds a selection listener that will be called when the selection is
* changed either by the user or programmatically.
*
* @param listener
* the value change listener, not {@code null}
* @return a registration for the listener
*/
public Registration addSelectionListener(
MultiSelectionListener listener);
/**
* MultiSelect empty value should always be an empty set by default and not
* {@code null}.
*
* @return An empty set, not {@code null}
*/
@Override
public default Set getEmptyValue() {
return Collections.emptySet();
}
}