com.vaadin.ui

Class AbstractMultiSelect<T>

java.lang.Object

com.vaadin.server.AbstractClientConnector

com.vaadin.ui.AbstractComponent

com.vaadin.ui.AbstractListing<T>

com.vaadin.ui.AbstractMultiSelect<T>

Type Parameters:

T - item type

All Implemented Interfaces:

HasItems<T>, HasValue<Set<T>>, ContextClickEvent.ContextClickNotifier, MethodEventSource, ClientConnector, Sizeable, Connector, Component, Component.Focusable, MultiSelect<T>, Serializable

Direct Known Subclasses:

CheckBoxGroup, ListSelect, TwinColSelect

public abstract class AbstractMultiSelect<T>
extends AbstractListing<T>
implements MultiSelect<T>

Base class for listing components that allow selecting multiple items.

Sends selection information individually for each item.

Since:

8.0

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class com.vaadin.ui.AbstractListing

AbstractListing.AbstractListingExtension<T>

Nested classes/interfaces inherited from interface com.vaadin.data.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<V>

Nested classes/interfaces inherited from interface com.vaadin.ui.Component

Component.ErrorEvent, Component.Event, Component.Focusable, Component.Listener

Nested classes/interfaces inherited from interface com.vaadin.server.ClientConnector

ClientConnector.AttachEvent, ClientConnector.AttachListener, ClientConnector.ConnectorErrorEvent, ClientConnector.DetachEvent, ClientConnector.DetachListener

Nested classes/interfaces inherited from interface com.vaadin.server.Sizeable

Sizeable.Unit

Field Summary

Fields inherited from class com.vaadin.ui.AbstractComponent

DESIGN_ATTR_PLAIN_TEXT

Fields inherited from interface com.vaadin.server.Sizeable

SIZE_UNDEFINED, UNITS_CM, UNITS_EM, UNITS_EX, UNITS_INCH, UNITS_MM, UNITS_PERCENTAGE, UNITS_PICAS, UNITS_PIXELS, UNITS_POINTS

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	AbstractMultiSelect() Creates a new multi select with an empty data provider.

Method Summary

Modifier and Type	Method and Description
Registration	addSelectionListener(MultiSelectionListener<T> listener) Adds a selection listener that will be called when the selection is changed either by the user or programmatically.
Registration	addValueChangeListener(HasValue.ValueChangeListener<Set<T>> listener) Adds a value change listener.
protected void	deselect(Set<T> items, boolean userOriginated) Removes the given items.
protected void	deselect(T item, boolean userOriginated) Deselects the given item.
void	deselectAll() Deselects all currently selected items.
protected Collection<String>	getCustomAttributes() Returns a collection of attributes that should not be handled by the basic implementation of the AbstractComponent.readDesign(Element, DesignContext) and AbstractComponent.writeDesign(Element, DesignContext) methods.
ItemCaptionGenerator<T>	getItemCaptionGenerator() Gets the item caption generator that is used to produce the strings shown in the combo box for each item.
protected SerializablePredicate<T>	getItemEnabledProvider() Returns the item enabled provider for this multiselect.
Set<T>	getSelectedItems() Returns an immutable set of the currently selected items.
protected AbstractMultiSelectState	getState() Returns the shared state bean with information to be sent from the server to the client.
protected AbstractMultiSelectState	getState(boolean markAsDirty) Returns the shared state for this connector.
Set<T>	getValue() Returns the current value of this object which is an immutable set of the currently selected items.
boolean	isReadOnly() Returns the read-only status from the state of this AbstractComponent.
boolean	isRequiredIndicatorVisible() Checks whether the required indicator is visible or not.
boolean	isSelected(T item) Returns whether the given item is currently selected.
protected T	readItem(org.jsoup.nodes.Element child, Set<T> selected, DesignContext context) Reads an Item from a design and inserts it into the data source.
protected void	readItems(org.jsoup.nodes.Element design, DesignContext context) Reads the data source items from the design.
protected void	select(T item, boolean userOriginated) Selects the given item.
void	setItemCaptionGenerator(ItemCaptionGenerator<T> itemCaptionGenerator) Sets the item caption generator that is used to produce the strings shown in the combo box for each item.
protected void	setItemEnabledProvider(SerializablePredicate<T> itemEnabledProvider) Sets the item enabled predicate for this multiselect.
void	setReadOnly(boolean readOnly) Sets the read-only status in the state of this AbstractComponent.
void	setRequiredIndicatorVisible(boolean visible) Sets the visibility of the required indicator.
void	setValue(Set<T> value) Sets the value of this object which is a set of items to select.
void	updateSelection(Set<T> addedItems, Set<T> removedItems) Updates the selection by adding and removing the given items from it.
protected void	updateSelection(Set<T> addedItems, Set<T> removedItems, boolean userOriginated) Updates the selection by adding and removing the given items.
protected org.jsoup.nodes.Element	writeItem(org.jsoup.nodes.Element design, T item, DesignContext context) Writes a data source Item to a design.

Methods inherited from class com.vaadin.ui.AbstractListing

addDataGenerator, deserializeDeclarativeRepresentation, doReadDesign, doWriteDesign, focus, getDataCommunicator, getItemIconGenerator, getTabIndex, internalGetDataProvider, internalSetDataProvider, internalSetDataProvider, readDesign, readItem, removeDataGenerator, serializeDeclarativeRepresentation, setItemIconGenerator, setTabIndex, writeDesign, writeItems

Methods inherited from class com.vaadin.ui.AbstractComponent

addContextClickListener, addListener, addShortcutListener, addStyleName, attach, beforeClientResponse, detach, findAncestor, fireComponentErrorEvent, fireComponentEvent, getActionManager, getCaption, getComponentError, getData, getDebugId, getDescription, getErrorMessage, getHeight, getHeightUnits, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getWidth, getWidthUnits, isCaptionAsHtml, isConnectorEnabled, isEnabled, isOrHasAncestor, isResponsive, isVisible, removeContextClickListener, removeListener, removeShortcutListener, removeStyleName, setCaption, setCaptionAsHtml, setComponentError, setData, setDebugId, setDescription, setDescription, setEnabled, setHeight, setHeight, setHeightUndefined, setIcon, setId, setLocale, setParent, setPrimaryStyleName, setResponsive, setSizeFull, setSizeUndefined, setStyleName, setVisible, setWidth, setWidth, setWidthUndefined

Methods inherited from class com.vaadin.server.AbstractClientConnector

addAttachListener, addDetachListener, addExtension, addListener, addListener, addListener, addMethodInvocationToQueue, createState, encodeState, equals, fireEvent, getAllChildrenIterable, getConnectorId, getErrorHandler, getExtensions, getListeners, getResource, getRpcManager, getRpcProxy, getSession, getStateType, getUI, handleConnectorRequest, hashCode, hasListeners, isAttached, isThis, markAsDirty, markAsDirtyRecursive, registerRpc, registerRpc, removeAttachListener, removeDetachListener, removeExtension, removeListener, removeListener, removeListener, removeListener, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler, setResource, updateDiffstate

Methods inherited from class java.lang.Object

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

Methods inherited from interface com.vaadin.ui.MultiSelect

deselect, getEmptyValue, select

Methods inherited from interface com.vaadin.data.HasValue

clear, getDefaultValidator, getOptionalValue, isEmpty

Methods inherited from interface com.vaadin.data.HasItems

getDataProvider, setItems, setItems, setItems

Methods inherited from interface com.vaadin.ui.Component

addListener, addStyleName, addStyleNames, attach, getCaption, getDescription, getIcon, getId, getLocale, getParent, getPrimaryStyleName, getStyleName, getUI, isEnabled, isVisible, removeListener, removeStyleName, removeStyleNames, setCaption, setEnabled, setIcon, setId, setParent, setPrimaryStyleName, setStyleName, setStyleName, setVisible

Methods inherited from interface com.vaadin.server.ClientConnector

addAttachListener, addDetachListener, beforeClientResponse, detach, encodeState, getErrorHandler, getExtensions, getRpcManager, getStateType, handleConnectorRequest, isAttached, isConnectorEnabled, markAsDirty, markAsDirtyRecursive, removeAttachListener, removeDetachListener, removeExtension, requestRepaint, requestRepaintAll, retrievePendingRpcCalls, setErrorHandler

Methods inherited from interface com.vaadin.shared.Connector

getConnectorId

Methods inherited from interface com.vaadin.server.Sizeable

getHeight, getHeightUnits, getWidth, getWidthUnits, setHeight, setHeight, setHeightUndefined, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthUndefined

Constructor Detail

AbstractMultiSelect

protected AbstractMultiSelect()

Creates a new multi select with an empty data provider.

Method Detail

addSelectionListener

public Registration addSelectionListener(MultiSelectionListener<T> listener)

Adds a selection listener that will be called when the selection is changed either by the user or programmatically.

Specified by:

addSelectionListener in interface MultiSelect<T>

Parameters:

listener - the value change listener, not null

Returns:

a registration for the listener

getItemCaptionGenerator

public ItemCaptionGenerator<T> getItemCaptionGenerator()

Description copied from class: AbstractListing

Gets the item caption generator that is used to produce the strings shown in the combo box for each item.

Overrides:

getItemCaptionGenerator in class AbstractListing<T>

Returns:

the item caption generator used, not null

setItemCaptionGenerator

public void setItemCaptionGenerator(ItemCaptionGenerator<T> itemCaptionGenerator)

Description copied from class: AbstractListing

Sets the item caption generator that is used to produce the strings shown in the combo box for each item. By default, String.valueOf(Object) is used.

Overrides:

setItemCaptionGenerator in class AbstractListing<T>

Parameters:

itemCaptionGenerator - the item caption provider to use, not null

getValue

public Set<T> getValue()

Returns the current value of this object which is an immutable set of the currently selected items.

The call is delegated to getSelectedItems()

Specified by:

getValue in interface HasValue<Set<T>>

Returns:

the current selection

See Also:

getSelectedItems(), SelectionModel.getSelectedItems()

setValue

public void setValue(Set<T> value)

Sets the value of this object which is a set of items to select. If the new value is not equal to getValue(), fires a value change event. May throw IllegalArgumentException if the value is not acceptable.

The method effectively selects the given items and deselects previously selected. The call is delegated to SelectionModel.Multi.updateSelection(Set, Set).

Specified by:

setValue in interface HasValue<Set<T>>

Parameters:

value - the items to select, not null

Throws:

NullPointerException - if the value is invalid

See Also:

SelectionModel.Multi.updateSelection(Set, Set)

addValueChangeListener

public Registration addValueChangeListener(HasValue.ValueChangeListener<Set<T>> listener)

Adds a value change listener. The listener is called when the selection set of this multi select is changed either by the user or programmatically.

Specified by:

addValueChangeListener in interface HasValue<Set<T>>

Parameters:

listener - the value change listener, not null

Returns:

a registration for the listener

See Also:

addSelectionListener(MultiSelectionListener)

getItemEnabledProvider

protected SerializablePredicate<T> getItemEnabledProvider()

Returns the item enabled provider for this multiselect.

Implementation note: Override this method and setItemEnabledProvider(SerializablePredicate) as public and invoke super methods to support this feature in the multiselect component.

Returns:

the item enabled provider, not null

See Also:

setItemEnabledProvider(SerializablePredicate)

setItemEnabledProvider

protected void setItemEnabledProvider(SerializablePredicate<T> itemEnabledProvider)

Sets the item enabled predicate for this multiselect. The predicate is applied to each item to determine whether the item should be enabled ( true) or disabled (false). Disabled items are displayed as grayed out and the user cannot select them. The default predicate always returns true (all the items are enabled).

Implementation note: Override this method and getItemEnabledProvider() as public and invoke super methods to support this feature in the multiselect component.

Parameters:

itemEnabledProvider - the item enabled provider to set, not null

setRequiredIndicatorVisible

public void setRequiredIndicatorVisible(boolean visible)

Description copied from class: AbstractComponent

Sets the visibility of the required indicator. NOTE: Does not apply for all components!.

If the component supports the required indicator (state extends AbstractFieldState), then expose this method and AbstractComponent.isRequiredIndicatorVisible() as public in the component and call this method.

This method will throw a IllegalStateException if the component state (returned by AbstractComponent.getState()) does not inherit AbstractFieldState.

Specified by:

setRequiredIndicatorVisible in interface HasValue<Set<T>>

Overrides:

setRequiredIndicatorVisible in class AbstractComponent

Parameters:

visible - true to make the required indicator visible, false if not

isRequiredIndicatorVisible

public boolean isRequiredIndicatorVisible()

Description copied from class: AbstractComponent

Checks whether the required indicator is visible or not. NOTE: Does not apply for all components!.

This method will throw a IllegalStateException if the component state (returned by AbstractComponent.getState()) does not inherit AbstractFieldState.

Specified by:

isRequiredIndicatorVisible in interface HasValue<Set<T>>

Overrides:

isRequiredIndicatorVisible in class AbstractComponent

Returns:

true if visible, false if not

See Also:

AbstractComponent.setRequiredIndicatorVisible(boolean)

getState

protected AbstractMultiSelectState getState()

Description copied from class: AbstractComponent

Returns the shared state bean with information to be sent from the server to the client. Subclasses should override this method and set any relevant fields of the state returned by super.getState().

Overrides:

getState in class AbstractListing<T>

Returns:

updated component shared state

getState

protected AbstractMultiSelectState getState(boolean markAsDirty)

Description copied from class: AbstractClientConnector

Returns the shared state for this connector.

Overrides:

getState in class AbstractListing<T>

Parameters:

markAsDirty - true if the connector should automatically be marked dirty, false otherwise

Returns:

The shared state for this connector. Never null.

See Also:

AbstractClientConnector.getState()

setReadOnly

public void setReadOnly(boolean readOnly)

Description copied from class: AbstractComponent

Sets the read-only status in the state of this AbstractComponent. This method should be made public in Components that implement HasValue.

Specified by:

setReadOnly in interface HasValue<Set<T>>

Overrides:

setReadOnly in class AbstractComponent

Parameters:

readOnly - a boolean value specifying whether the component is put read-only mode or not

isReadOnly

public boolean isReadOnly()

Description copied from class: AbstractComponent

Returns the read-only status from the state of this AbstractComponent. This method should be made public in Components that implement HasValue.

Specified by:

isReadOnly in interface HasValue<Set<T>>

Overrides:

isReadOnly in class AbstractComponent

Returns:

true if state has read-only on; false if not

See Also:

AbstractComponent.setReadOnly(boolean)

updateSelection

public void updateSelection(Set<T> addedItems,
                            Set<T> removedItems)

Description copied from interface: MultiSelect

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.

Specified by:

updateSelection in interface MultiSelect<T>

Parameters:

addedItems - the items to add, not null

removedItems - the items to remove, not null

updateSelection

protected void updateSelection(Set<T> addedItems,
                               Set<T> removedItems,
                               boolean userOriginated)

Updates the selection by adding and removing the given items.

Parameters:

addedItems - the items added to selection, not null

removedItems - the items removed from selection, not null

userOriginated - true if this was used originated, false if not

getSelectedItems

public Set<T> getSelectedItems()

Description copied from interface: MultiSelect

Returns an immutable set of the currently selected items. It is safe to invoke other 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.

Specified by:

getSelectedItems in interface MultiSelect<T>

Returns:

the items in the current selection, not null

deselectAll

public void deselectAll()

Description copied from interface: MultiSelect

Deselects all currently selected items.

Specified by:

deselectAll in interface MultiSelect<T>

isSelected

public boolean isSelected(T item)

Description copied from interface: MultiSelect

Returns whether the given item is currently selected.

Specified by:

isSelected in interface MultiSelect<T>

Parameters:

item - the item to check, not null

Returns:

true if the item is selected, false otherwise

deselect

protected void deselect(T item,
                        boolean userOriginated)

Deselects the given item. If the item is not currently selected, does nothing.

Parameters:

item - the item to deselect, not null

userOriginated - true if this was used originated, false if not

deselect

protected void deselect(Set<T> items,
                        boolean userOriginated)

Removes the given items. Any item that is not currently selected, is ignored. If none of the items are selected, does nothing.

Parameters:

items - the items to deselect, not null

userOriginated - true if this was used originated, false if not

select

protected void select(T item,
                      boolean userOriginated)

Selects the given item. Depending on the implementation, may cause other items to be deselected. If the item is already selected, does nothing.

Parameters:

item - the item to select, not null

userOriginated - true if this was used originated, false if not

getCustomAttributes

protected Collection<String> getCustomAttributes()

Description copied from class: AbstractComponent

Returns a collection of attributes that should not be handled by the basic implementation of the AbstractComponent.readDesign(Element, DesignContext) and AbstractComponent.writeDesign(Element, DesignContext) methods. Typically these are handled in a custom way in the overridden versions of the above methods

Overrides:

getCustomAttributes in class AbstractComponent

Returns:

the collection of attributes that are not handled by the basic implementation

writeItem

protected org.jsoup.nodes.Element writeItem(org.jsoup.nodes.Element design,
                                            T item,
                                            DesignContext context)

Description copied from class: AbstractListing

Writes a data source Item to a design. Hierarchical select components should override this method to recursively write any child items as well.

Overrides:

writeItem in class AbstractListing<T>

Parameters:

design - the element into which to insert the item

item - the item to write

context - the DesignContext instance used in writing

Returns:

a JSOUP element representing the item

readItems

protected void readItems(org.jsoup.nodes.Element design,
                         DesignContext context)

Description copied from class: AbstractListing

Reads the data source items from the design.

Specified by:

readItems in class AbstractListing<T>

Parameters:

design - The element to obtain the state from

context - The DesignContext instance used for parsing the design

readItem

protected T readItem(org.jsoup.nodes.Element child,
                     Set<T> selected,
                     DesignContext context)

Reads an Item from a design and inserts it into the data source. Hierarchical select components should override this method to recursively recursively read any child items as well.

Parameters:

child - a child element representing the item

selected - A set accumulating selected items. If the item that is read is marked as selected, its item id should be added to this set.

context - the DesignContext instance used in parsing

Returns:

the item id of the new item

Throws:

DesignException - if the tag name of the child element is not option.