Package com.vaadin.ui

Class AbstractSelect

    • Constructor Detail

      • AbstractSelect

        public AbstractSelect()
        Creates an empty Select. The caption is not used.

      • AbstractSelect

        public AbstractSelect​(String caption)
        Creates an empty Select with caption.

      • AbstractSelect

        public AbstractSelect​(String caption,
                      Container dataSource)
        Creates a new select that is connected to a data-source.
        Parameters:
        caption - the Caption of the component.
        dataSource - the Container datasource to be selected from by this select.

      • AbstractSelect

        public AbstractSelect​(String caption,
                      Collection<?> options)
        Creates a new select that is filled from a collection of option values.
        Parameters:
        caption - the Caption of this field.
        options - the Collection containing the options.

    • Method Detail

      • changeVariables

        public void changeVariables​(Object source,
                            Map<String,​Object> variables)
        Invoked when the value of a variable has changed.
        Specified by:
        changeVariables in interface VariableOwner
        Parameters:
        source - the Source of the variable change. This is the origin of the event. For example in Web Adapter this is the request.
        variables - the Mapping from variable names to new variable values.
        See Also:
        AbstractComponent#changeVariables(java.lang.Object, java.util.Map)

      • setNewItemHandler

        public void setNewItemHandler​(AbstractSelect.NewItemHandler newItemHandler)
        TODO refine doc Setter for new item handler that is called when user adds new item in newItemAllowed mode.
        Parameters:
        newItemHandler -

      • getVisibleItemIds

        public Collection<?> getVisibleItemIds()
        Gets the visible item ids. In Select, this returns list of all item ids, but can be overriden in subclasses if they paint only part of the items to the terminal or null if no items is visible.

      • getType

        public Class<?> getType()
        Returns the type of the property. getValue and setValue methods must be compatible with this type: one can safely cast getValue to given type and pass any variable assignable to this type as a parameter to setValue.
        Specified by:
        getType in interface Property<Object>
        Specified by:
        getType in class AbstractField<Object>
        Returns:
        the Type of the property.

      • getItem

        public Item getItem​(Object itemId)
        Gets the item from the container with given id. If the container does not contain the requested item, null is returned.
        Specified by:
        getItem in interface Container
        Parameters:
        itemId - the item id.
        Returns:
        the item from the container.

      • getItemIds

        public Collection<?> getItemIds()
        Gets the item Id collection from the container.
        Specified by:
        getItemIds in interface Container
        Returns:
        the Collection of item ids.

      • getContainerPropertyIds

        public Collection<?> getContainerPropertyIds()
        Gets the property Id collection from the container.
        Specified by:
        getContainerPropertyIds in interface Container
        Returns:
        the Collection of property ids.

      • size

        public int size()
        Gets the number of items in the container.
        Specified by:
        size in interface Container
        Returns:
        the Number of items in the container.
        See Also:
        Container.size()

      • containsId

        public boolean containsId​(Object itemId)
        Tests, if the collection contains an item with given id.
        Specified by:
        containsId in interface Container
        Parameters:
        itemId - the Id the of item to be tested.
        Returns:
        boolean indicating if the Container holds the specified Item

      • addItem

        public Object addItem()
               throws UnsupportedOperationException
        Creates a new item into container with container managed id. The id of the created new item is returned. The item can be fetched with getItem() method. if the creation fails, null is returned.
        Specified by:
        addItem in interface Container
        Returns:
        the Id of the created item or null in case of failure.
        Throws:
        UnsupportedOperationException - if adding an item without an explicit item ID is not supported by the container
        See Also:
        Container.addItem()

      • addItem

        public Item addItem​(Object itemId)
             throws UnsupportedOperationException
        Create a new item into container. The created new item is returned and ready for setting property values. if the creation fails, null is returned. In case the container already contains the item, null is returned. This functionality is optional. If the function is unsupported, it always returns null.
        Specified by:
        addItem in interface Container
        Parameters:
        itemId - the Identification of the item to be created.
        Returns:
        the Created item with the given id, or null in case of failure.
        Throws:
        UnsupportedOperationException - if adding an item with an explicit item ID is not supported by the container
        See Also:
        Container.addItem(java.lang.Object)

      • addItems

        public void addItems​(Object... itemId)
              throws UnsupportedOperationException
        Adds given items with given item ids to container.
        Parameters:
        itemId - item identifiers to be added to underlying container
        Throws:
        UnsupportedOperationException - if the underlying container don't support adding items with identifiers
        Since:
        7.2

      • addItems

        public void addItems​(Collection<?> itemIds)
              throws UnsupportedOperationException
        Adds given items with given item ids to container.
        Parameters:
        itemIds - item identifiers to be added to underlying container
        Throws:
        UnsupportedOperationException - if the underlying container don't support adding items with identifiers
        Since:
        7.2

      • removeItem

        public boolean removeItem​(Object itemId)
                   throws UnsupportedOperationException
        Description copied from interface: Container
        Removes the Item identified by ItemId from the Container.

        Containers that support filtering should also allow removing an item that is currently filtered out.

        This functionality is optional.

        Specified by:
        removeItem in interface Container
        Parameters:
        itemId - ID of the Item to remove
        Returns:
        true if the operation succeeded, false if not
        Throws:
        UnsupportedOperationException - if the container does not support removing individual items

      • sanitizeSelection

        public void sanitizeSelection()
        Checks that the current selection is valid, i.e. the selected item ids exist in the container. Updates the selection if one or several selected item ids are no longer available in the container.

      • isMultiSelect

        public boolean isMultiSelect()
        Is the select in multiselect mode? In multiselect mode
        Returns:
        the Value of property multiSelect.

      • setMultiSelect

        public void setMultiSelect​(boolean multiSelect)
        Sets the multiselect mode. Setting multiselect mode false may lose selection information: if selected items set contains one or more selected items, only one of the selected items is kept as selected. Subclasses of AbstractSelect can choose not to support changing the multiselect mode, and may throw UnsupportedOperationException.
        Parameters:
        multiSelect - the New value of property multiSelect.

      • isNewItemsAllowed

        public boolean isNewItemsAllowed()
        Does the select allow adding new options by the user. If true, the new options can be added to the Container. The text entered by the user is used as id. Note that data-source must allow adding new items.
        Returns:
        True if additions are allowed.

      • setNewItemsAllowed

        public void setNewItemsAllowed​(boolean allowNewOptions)
        Enables or disables possibility to add new options by the user.
        Parameters:
        allowNewOptions - the New value of property allowNewOptions.

      • setItemCaption

        public void setItemCaption​(Object itemId,
                           String caption)
        Override the caption of an item. Setting caption explicitly overrides id, item and index captions.
        Parameters:
        itemId - the id of the item to be recaptioned.
        caption - the New caption.

      • getItemCaption

        public String getItemCaption​(Object itemId)
        Gets the caption of an item. The caption is generated as specified by the item caption mode. See setItemCaptionMode() for more details.
        Parameters:
        itemId - the id of the item to be queried.
        Returns:
        the caption for specified item.

      • setItemIcon

        public void setItemIcon​(Object itemId,
                        Resource icon)
        Sets the icon for an item.
        Parameters:
        itemId - the id of the item to be assigned an icon.
        icon - the icon to use or null.

      • getItemIcon

        public Resource getItemIcon​(Object itemId)
        Gets the item icon.
        Parameters:
        itemId - the id of the item to be assigned an icon.
        Returns:
        the icon for the item or null, if not specified.

      • getItemCaptionMode

        public AbstractSelect.ItemCaptionMode getItemCaptionMode()
        Gets the item caption mode.

        The mode can be one of the following ones:

        • ITEM_CAPTION_MODE_EXPLICIT_DEFAULTS_ID : Items Id-objects toString is used as item caption. If caption is explicitly specified, it overrides the id-caption.
        • ITEM_CAPTION_MODE_ID : Items Id-objects toString is used as item caption.
        • ITEM_CAPTION_MODE_ITEM : Item-objects toString is used as item caption.
        • ITEM_CAPTION_MODE_INDEX : The index of the item is used as item caption. The index mode can only be used with the containers implementing Container.Indexed interface.
        • ITEM_CAPTION_MODE_EXPLICIT : The item captions must be explicitly specified.
        • ITEM_CAPTION_MODE_PROPERTY : The item captions are read from property, that must be specified with setItemCaptionPropertyId.
        The ITEM_CAPTION_MODE_EXPLICIT_DEFAULTS_ID is the default mode.

        Returns:
        the One of the modes listed above.

      • setItemCaptionPropertyId

        public void setItemCaptionPropertyId​(Object propertyId)
        Sets the item caption property.

        Setting the id to a existing property implicitly sets the item caption mode to ITEM_CAPTION_MODE_PROPERTY. If the object is in ITEM_CAPTION_MODE_PROPERTY mode, setting caption property id null resets the item caption mode to ITEM_CAPTION_EXPLICIT_DEFAULTS_ID.

        Note that the type of the property used for caption must be String

        Setting the property id to null disables this feature. The id is null by default

        .
        Parameters:
        propertyId - the id of the property.

      • getItemCaptionPropertyId

        public Object getItemCaptionPropertyId()
        Gets the item caption property.
        Returns:
        the Id of the property used as item caption source.

      • setItemIconPropertyId

        public void setItemIconPropertyId​(Object propertyId)
                           throws IllegalArgumentException
        Sets the item icon property.

        If the property id is set to a valid value, each item is given an icon got from the given property of the items. The type of the property must be assignable to Resource.

        Note : The icons set with setItemIcon function override the icons from the property.

        Setting the property id to null disables this feature. The id is null by default

        .
        Parameters:
        propertyId - the id of the property that specifies icons for items or null
        Throws:
        IllegalArgumentException - If the propertyId is not in the container or is not of a valid type

      • getItemIconPropertyId

        public Object getItemIconPropertyId()
        Gets the item icon property.

        If the property id is set to a valid value, each item is given an icon got from the given property of the items. The type of the property must be assignable to Icon.

        Note : The icons set with setItemIcon function override the icons from the property.

        Setting the property id to null disables this feature. The id is null by default

        .
        Returns:
        the Id of the property containing the item icons.

      • getListeners

        public Collection<?> getListeners​(Class<?> eventType)
        Description copied from class: AbstractClientConnector
        Returns all listeners that are registered for the given event type or one of its subclasses.
        Overrides:
        getListeners in class AbstractClientConnector
        Parameters:
        eventType - The type of event to return listeners for.
        Returns:
        A collection with all registered listeners. Empty if no listeners are found.

      • firePropertySetChange

        protected void firePropertySetChange()
        Fires the property set change event.

      • fireItemSetChange

        protected void fireItemSetChange()
        Fires the item set change event.

      • isEmpty

        public boolean isEmpty()
        For multi-selectable fields, also an empty collection of values is considered to be an empty field.
        Specified by:
        isEmpty in interface Field<Object>
        Overrides:
        isEmpty in class AbstractField<Object>
        Returns:
        true if the field is empty, false otherwise

      • setNullSelectionAllowed

        public void setNullSelectionAllowed​(boolean nullSelectionAllowed)
        Allow or disallow empty selection by the user. If the select is in single-select mode, you can make an item represent the empty selection by calling setNullSelectionItemId(). This way you can for instance set an icon and caption for the null selection item.
        Parameters:
        nullSelectionAllowed - whether or not to allow empty selection
        See Also:
        setNullSelectionItemId(Object), isNullSelectionAllowed()

      • isNullSelectionAllowed

        public boolean isNullSelectionAllowed()
        Checks if null empty selection is allowed by the user.
        Returns:
        whether or not empty selection is allowed
        See Also:
        setNullSelectionAllowed(boolean)

      • getNullSelectionItemId

        public Object getNullSelectionItemId()
        Returns the item id that represents null value of this select in single select mode.

        Data interface does not support nulls as item ids. Selecting the item identified by this id is the same as selecting no items at all. This setting only affects the single select mode.

        Returns:
        the Object Null value item id.
        See Also:
        setNullSelectionItemId(Object), isSelected(Object), select(Object)

      • setNullSelectionItemId

        public void setNullSelectionItemId​(Object nullSelectionItemId)
        Sets the item id that represents null value of this select.

        Data interface does not support nulls as item ids. Selecting the item identified by this id is the same as selecting no items at all. This setting only affects the single select mode.

        Parameters:
        nullSelectionItemId - the nullSelectionItemId to set.
        See Also:
        getNullSelectionItemId(), isSelected(Object), select(Object)

      • readDesign

        public void readDesign​(org.jsoup.nodes.Element design,
                       DesignContext context)
        Description copied from interface: Component
        Reads the component state from the given design.

        The component is responsible not only for updating its own state but also for ensuring that its children update their state based on the design.

        It is assumed that the component is in its default state when this method is called. Reading should only take into consideration attributes specified in the design and not reset any unspecified attributes to their defaults.

        This method must not modify the design.

        Specified by:
        readDesign in interface Component
        Overrides:
        readDesign in class AbstractField<Object>
        Parameters:
        design - The element to obtain the state from
        context - The DesignContext instance used for parsing the design

      • readItems

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

      • readItem

        protected Object readItem​(org.jsoup.nodes.Element child,
                          Set<String> 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.
        Since:
        7.5.0

      • writeDesign

        public void writeDesign​(org.jsoup.nodes.Element design,
                        DesignContext context)
        Description copied from interface: Component
        Writes the component state to the given design.

        The component is responsible not only for writing its own state but also for ensuring that its children write their state to the design.

        This method must not modify the component state.

        Specified by:
        writeDesign in interface Component
        Overrides:
        writeDesign in class AbstractField<Object>
        Parameters:
        design - The element to write the component state to. Any previous attributes or child nodes are not cleared.
        context - The DesignContext instance used for writing the design

      • writeItems

        protected void writeItems​(org.jsoup.nodes.Element design,
                          DesignContext context)
        Writes the data source items to a design. Hierarchical select components should override this method to only write the root items.
        Parameters:
        design - the element into which to insert the items
        context - the DesignContext instance used in writing
        Since:
        7.5.0

      • writeItem

        protected org.jsoup.nodes.Element writeItem​(org.jsoup.nodes.Element design,
                                            Object itemId,
                                            DesignContext context)
        Writes a data source Item to a design. Hierarchical select components should override this method to recursively write any child items as well.
        Parameters:
        design - the element into which to insert the item
        itemId - the id of the item to write
        context - the DesignContext instance used in writing
        Returns:
        Since:
        7.5.0

      • getState

        protected AbstractSelectState 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 AbstractField<Object>
        Returns:
        updated component shared state