Package com.vaadin.ui

Class Tree<T>

    • Constructor Detail

      • Tree

        public Tree()
        Constructs a new Tree Component.

      • Tree

        public Tree​(String caption)
        Constructs a new Tree Component with given caption.
        Parameters:
        caption - the caption for component

      • Tree

        public Tree​(String caption,
            TreeData<T> treeData)
        Constructs a new Tree Component with given caption and TreeData.
        Parameters:
        caption - the caption for component
        treeData - the tree data for component

      • Tree

        public Tree​(String caption,
            HierarchicalDataProvider<T,​?> dataProvider)
        Constructs a new Tree Component with given caption and HierarchicalDataProvider.
        Parameters:
        caption - the caption for component
        dataProvider - the hierarchical data provider for component

      • Tree

        public Tree​(HierarchicalDataProvider<T,​?> dataProvider)
        Constructs a new Tree Component with given HierarchicalDataProvider.
        Parameters:
        dataProvider - the hierarchical data provider for component

    • Method Detail

      • createTreeGrid

        protected TreeGrid<T> createTreeGrid()
        Create inner TreeGrid object. May be overridden in subclasses.
        Returns:
        new TreeGrid

      • setDataProvider

        public void setDataProvider​(DataProvider<T,​?> dataProvider)
        Description copied from interface: HasDataProvider
        Sets the data provider for this listing. The data provider is queried for displayed items as needed.
        Specified by:
        setDataProvider in interface HasDataProvider<T>
        Parameters:
        dataProvider - the data provider, not null

      • fireExpandEvent

        protected void fireExpandEvent​(T item,
                               boolean userOriginated)
        Fires an expand event with given item.
        Parameters:
        item - the expanded item
        userOriginated - whether the expand was triggered by a user interaction or the server

      • fireCollapseEvent

        protected void fireCollapseEvent​(T item,
                                 boolean userOriginated)
        Fires a collapse event with given item.
        Parameters:
        item - the collapsed item
        userOriginated - whether the collapse was triggered by a user interaction or the server

      • expand

        public void expand​(T... items)
        Expands the given items.

        If an item is currently expanded, does nothing. If an item does not have any children, does nothing.

        Parameters:
        items - the items to expand

      • expand

        public void expand​(Collection<T> items)
        Expands the given items.

        If an item is currently expanded, does nothing. If an item does not have any children, does nothing.

        Parameters:
        items - the items to expand

      • expandRecursively

        public void expandRecursively​(Collection<T> items,
                              int depth)
        Expands the given items and their children recursively until the given depth.

        depth describes the maximum distance between a given item and its descendant, meaning that expandRecursively(items, 0) expands only the given items while expandRecursively(items, 2) expands the given items as well as their children and grandchildren.

        Parameters:
        items - the items to expand recursively
        depth - the maximum depth of recursion
        Since:
        8.4

      • collapse

        public void collapse​(T... items)
        Collapse the given items.

        For items that are already collapsed, does nothing.

        Parameters:
        items - the collection of items to collapse

      • collapse

        public void collapse​(Collection<T> items)
        Collapse the given items.

        For items that are already collapsed, does nothing.

        Parameters:
        items - the collection of items to collapse

      • collapseRecursively

        public void collapseRecursively​(Collection<T> items,
                                int depth)
        Collapse the given items and their children recursively until the given depth.

        depth describes the maximum distance between a given item and its descendant, meaning that collapseRecursively(items, 0) collapses only the given items while collapseRecursively(items, 2) collapses the given items as well as their children and grandchildren.

        Parameters:
        items - the items to expand recursively
        depth - the maximum depth of recursion
        Since:
        8.4

      • isExpanded

        public boolean isExpanded​(T item)
        Returns whether a given item is expanded or collapsed.
        Parameters:
        item - the item to check
        Returns:
        true if the item is expanded, false if collapsed

      • getSelectedItems

        public Set<T> getSelectedItems()
        This method is a shorthand that delegates to the currently set selection model.
        Returns:
        set of selected items
        See Also:
        getSelectionModel()

      • getSelectionModel

        public SelectionModel<T> getSelectionModel()
        Returns the selection model for this Tree.
        Returns:
        the selection model, not null

      • setItemCaptionGenerator

        public void setItemCaptionGenerator​(ItemCaptionGenerator<T> captionGenerator)
        Sets the item caption generator that is used to produce the strings shown as the text for each item. By default, String.valueOf(Object) is used.
        Parameters:
        captionGenerator - the item caption provider to use, not null

      • setItemIconGenerator

        public void setItemIconGenerator​(IconGenerator<T> iconGenerator)
        Sets the item icon generator that is used to produce custom icons for items. The generator can return null for items with no icon.
        Parameters:
        iconGenerator - the item icon generator to set, not null
        Throws:
        NullPointerException - if itemIconGenerator is null
        See Also:
        IconGenerator

      • setItemCollapseAllowedProvider

        public void setItemCollapseAllowedProvider​(ItemCollapseAllowedProvider<T> provider)
        Sets the item collapse allowed provider for this Tree. The provider should return true for any item that the user can collapse.

        Note: This callback will be accessed often when sending data to the client. The callback should not do any costly operations.

        Parameters:
        provider - the item collapse allowed provider, not null

      • setStyleGenerator

        public void setStyleGenerator​(StyleGenerator<T> styleGenerator)
        Sets the style generator that is used for generating class names for items in this tree. Returning null from the generator results in no custom style name being set.
        Parameters:
        styleGenerator - the item style generator to set, not null
        Throws:
        NullPointerException - if styleGenerator is null
        See Also:
        StyleGenerator

      • setItemDescriptionGenerator

        public void setItemDescriptionGenerator​(DescriptionGenerator<T> descriptionGenerator)
        Sets the description generator that is used for generating tooltip descriptions for items.
        Parameters:
        descriptionGenerator - the item description generator to set, or null to remove a previously set generator
        Since:
        8.2

      • setItemDescriptionGenerator

        public void setItemDescriptionGenerator​(DescriptionGenerator<T> descriptionGenerator,
                                        ContentMode contentMode)
        Sets the description generator that is used for generating HTML tooltip descriptions for items.
        Parameters:
        descriptionGenerator - the item description generator to set, or null to remove a previously set generator
        contentMode - how client should interpret textual values
        Since:
        8.4

      • getItemCaptionGenerator

        public ItemCaptionGenerator<T> getItemCaptionGenerator()
        Gets the item caption generator.
        Returns:
        the item caption generator

      • getItemIconGenerator

        public IconGenerator<T> getItemIconGenerator()
        Gets the item icon generator.
        Returns:
        the item icon generator
        See Also:
        IconGenerator

      • getItemCollapseAllowedProvider

        public ItemCollapseAllowedProvider<T> getItemCollapseAllowedProvider()
        Gets the item collapse allowed provider.
        Returns:
        the item collapse allowed provider

      • getStyleGenerator

        public StyleGenerator<T> getStyleGenerator()
        Gets the style generator.
        Returns:
        the item style generator
        See Also:
        StyleGenerator

      • getItemDescriptionGenerator

        public DescriptionGenerator<T> getItemDescriptionGenerator()
        Gets the item description generator.
        Returns:
        the item description generator
        Since:
        8.2

      • setCaption

        public void setCaption​(String caption)
        Description copied from interface: Component
        Sets the caption of the component.

        A caption is an explanatory textual label accompanying a user interface component, usually shown above, left of, or inside the component. Icon (see setIcon() is closely related to caption and is usually displayed horizontally before or after it, depending on the component and the containing layout.

        The caption can usually also be given as the first parameter to a constructor, though some components do not support it. 

         RichTextArea area = new RichTextArea();
 area.setCaption("You can edit stuff here");
 area.setValue("<h1>Helpful Heading</h1>"
         + "<p>All this is for you to edit.</p>");

        The contents of a caption are automatically quoted, so no raw HTML can be rendered in a caption. The validity of the used character encoding, usually UTF-8, is not checked.

        The caption of a component is, by default, managed and displayed by the layout component or component container in which the component is placed. For example, the VerticalLayout component shows the captions left-aligned above the contained components, while the FormLayout component shows the captions on the left side of the vertically laid components, with the captions and their associated components left-aligned in their own columns. The CustomComponent does not manage the caption of its composition root, so if the root component has a caption, it will not be rendered. Some components, such as Button and Panel, manage the caption themselves and display it inside the component.

        Specified by:
        setCaption in interface Component
        Overrides:
        setCaption in class Composite
        Parameters:
        caption - the new caption for the component. If the caption is null, no caption is shown and it does not normally take any space

      • getStyleName

        public String getStyleName()
        Description copied from interface: Component
        Gets all user-defined CSS style names of a component. If the component has multiple style names defined, the return string is a space-separated list of style names. Built-in style names defined in Vaadin or GWT are not returned.

        The style names are returned only in the basic form in which they were added; each user-defined style name shows as two CSS style class names in the rendered HTML: one as it was given and one prefixed with the component-specific style name. Only the former is returned.

        Specified by:
        getStyleName in interface Component
        Overrides:
        getStyleName in class Composite
        Returns:
        the style name or a space-separated list of user-defined style names of the component
        See Also:
        Component.setStyleName(String), Component.addStyleName(String), Component.removeStyleName(String)

      • setStyleName

        public void setStyleName​(String style)
        Description copied from interface: Component
        Sets one or more user-defined style names of the component, replacing any previous user-defined styles. Multiple styles can be specified as a space-separated list of style names. The style names must be valid CSS class names and should not conflict with any built-in style names in Vaadin or GWT. 
         Label label = new Label("This text has a lot of style");
 label.setStyleName("myonestyle myotherstyle");

        Each style name will occur in two versions: one as specified and one that is prefixed with the style name of the component. For example, if you have a Button component and give it "mystyle" style, the component will have both "mystyle" and "v-button-mystyle" styles. You could then style the component either with: 

         .myonestyle {background: blue;}

        or 

         .v-button-myonestyle {background: blue;}

        It is normally a good practice to use addStyleName() rather than this setter, as different software abstraction layers can then add their own styles without accidentally removing those defined in other layers.

        Specified by:
        setStyleName in interface Component
        Overrides:
        setStyleName in class Composite
        Parameters:
        style - the new style or styles of the component as a space-separated list
        See Also:
        Component.getStyleName(), Component.addStyleName(String), Component.removeStyleName(String)

      • addStyleName

        public void addStyleName​(String style)
        Description copied from interface: Component
        Adds one or more style names to this component. Multiple styles can be specified as a space-separated list of style names. The style name will be rendered as a HTML class name, which can be used in a CSS definition. 
         Label label = new Label("This text has style");
 label.addStyleName("mystyle");

        Each style name will occur in two versions: one as specified and one that is prefixed with the style name of the component. For example, if you have a Button component and give it "mystyle" style, the component will have both "mystyle" and "v-button-mystyle" styles. You could then style the component either with: 

         .mystyle {font-style: italic;}

        or 

         .v-button-mystyle {font-style: italic;}
        Specified by:
        addStyleName in interface Component
        Overrides:
        addStyleName in class Composite
        Parameters:
        style - the new style to be added to the component
        See Also:
        Component.getStyleName(), Component.setStyleName(String), Component.removeStyleName(String)

      • setPrimaryStyleName

        public void setPrimaryStyleName​(String style)
        Description copied from interface: Component
        Changes the primary style name of the component.

        The primary style name identifies the component when applying the CSS theme to the Component. By changing the style name all CSS rules targeted for that style name will no longer apply, and might result in the component not working as intended.

        To preserve the original style of the component when changing to a new primary style you should make your new primary style inherit the old primary style using the SASS @include directive. See more in the SASS tutorials.

        Specified by:
        setPrimaryStyleName in interface Component
        Overrides:
        setPrimaryStyleName in class Composite
        Parameters:
        style - The new primary style name

      • setId

        public void setId​(String id)
        Description copied from interface: Component
        Adds an unique id for component that is used in the client-side for testing purposes. Keeping identifiers unique is the responsibility of the programmer.
        Specified by:
        setId in interface Component
        Overrides:
        setId in class Composite
        Parameters:
        id - An alphanumeric id

      • getId

        public String getId()
        Description copied from interface: Component
        Gets currently set debug identifier.
        Specified by:
        getId in interface Component
        Overrides:
        getId in class Composite
        Returns:
        current id, null if not set

      • setCaptionAsHtml

        public void setCaptionAsHtml​(boolean captionAsHtml)
        Description copied from class: AbstractComponent
        Sets whether the caption is rendered as HTML.

        If set to true, the captions are rendered in the browser as HTML and the developer is responsible for ensuring no harmful HTML is used. If set to false, the caption is rendered in the browser as plain text.

        The default is false, i.e. to render that caption as plain text.

        Overrides:
        setCaptionAsHtml in class Composite
        Parameters:
        captionAsHtml - true if the captions are rendered as HTML, false if rendered as plain text

      • isCaptionAsHtml

        public boolean isCaptionAsHtml()
        Description copied from class: AbstractComponent
        Checks whether captions are rendered as HTML

        The default is false, i.e. to render that caption as plain text.

        Overrides:
        isCaptionAsHtml in class Composite
        Returns:
        true if the captions are rendered as HTML, false if rendered as plain text

      • setDescription

        public void setDescription​(String description,
                           ContentMode mode)
        Description copied from class: AbstractComponent
        Sets the component's description using given content mode. See AbstractComponent.getDescription() for more information on what the description is.

        If the content mode is ContentMode.HTML the description is displayed as HTML in tooltips or directly in certain components so care should be taken to avoid creating the possibility for HTML injection and possibly XSS vulnerabilities.

        Overrides:
        setDescription in class Composite
        Parameters:
        description - the new description string for the component.
        mode - the content mode for the description

      • getErrorMessage

        public ErrorMessage getErrorMessage()
        Description copied from class: AbstractComponent
        Gets the error message for this component.
        Overrides:
        getErrorMessage in class Composite
        Returns:
        ErrorMessage containing the description of the error state of the component or null, if the component contains no errors. Extending classes should override this method if they support other error message types such as validation errors or buffering errors. The returned error message contains information about all the errors.

      • setComponentError

        public void setComponentError​(ErrorMessage componentError)
        Description copied from class: AbstractComponent
        Sets the component's error message. The message may contain certain XML tags, for more information see ErrorMessage.
        Overrides:
        setComponentError in class Composite
        Parameters:
        componentError - the new ErrorMessage of the component.

      • setRowHeight

        public void setRowHeight​(double rowHeight)
        Sets the height of a row. If -1 (default), the row height is calculated based on the theme for an empty row before the Tree is displayed.
        Parameters:
        rowHeight - The height of a row in pixels or -1 for automatic calculation

      • getContentMode

        public ContentMode getContentMode()
        Gets the currently set content mode of the item captions of this Tree.
        Returns:
        the content mode of the item captions of this Tree
        Since:
        8.1.3
        See Also:
        ContentMode

      • setContentMode

        public void setContentMode​(ContentMode contentMode)
        Sets the content mode of the item caption.
        Parameters:
        contentMode - the content mode
        See Also:
        ContentMode

      • isAutoRecalculateWidth

        public boolean isAutoRecalculateWidth()
        Returns the current state of automatic width recalculation.
        Returns:
        true if enabled; false if disabled
        Since:
        8.1.1

      • setAutoRecalculateWidth

        public void setAutoRecalculateWidth​(boolean autoRecalculateWidth)
        Sets the automatic width recalculation on or off. This feature is on by default.
        Parameters:
        autoRecalculateWidth - true to enable recalculation; false to turn it off
        Since:
        8.1.1

      • writeDesign

        public void writeDesign​(org.jsoup.nodes.Element design,
                        DesignContext designContext)
        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 AbstractComponent
        Parameters:
        design - The element to write the component state to. Any previous attributes or child nodes are not cleared.
        designContext - The DesignContext instance used for writing the design

      • readDesign

        public void readDesign​(org.jsoup.nodes.Element design,
                       DesignContext designContext)
        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 AbstractComponent
        Parameters:
        design - The element to obtain the state from
        designContext - The DesignContext instance used for parsing the design

      • deserializeDeclarativeRepresentation

        protected T deserializeDeclarativeRepresentation​(String item)
        Deserializes a string to a data item. Used when reading from the declarative format of this Tree.

        Default implementation is able to handle only String as an item type. There will be a ClassCastException if T is not a String.

        Parameters:
        item - string to deserialize
        Returns:
        deserialized item
        Throws:
        ClassCastException - if type T is not a String
        Since:
        8.1.3
        See Also:
        serializeDeclarativeRepresentation(Object)

      • serializeDeclarativeRepresentation

        protected String serializeDeclarativeRepresentation​(T item)
        Serializes an item to a string. Used when saving this Tree to its declarative format.

        Default implementation delegates a call to item.toString().

        Parameters:
        item - a data item
        Returns:
        string representation of the item.
        Since:
        8.1.3
        See Also:
        deserializeDeclarativeRepresentation(String)

      • scrollTo

        public void scrollTo​(int row)
              throws IllegalArgumentException
        Scrolls to a certain item, using ScrollDestination.ANY.

        If the item has an open details row, its size will also be taken into account.

        Parameters:
        row - zero based index of the item to scroll to in the current view.
        Throws:
        IllegalArgumentException - if the provided row is outside the item range
        Since:
        8.2

      • scrollTo

        public void scrollTo​(int row,
                     ScrollDestination destination)
        Scrolls to a certain item, using user-specified scroll destination.

        If the item has an open details row, its size will also be taken into account.

        Parameters:
        row - zero based index of the item to scroll to in the current view.
        destination - value specifying desired position of scrolled-to row, not null
        Throws:
        IllegalArgumentException - if the provided row is outside the item range
        Since:
        8.2

      • scrollToStart

        public void scrollToStart()
        Scrolls to the beginning of the first data row.
        Since:
        8.2

      • scrollToEnd

        public void scrollToEnd()
        Scrolls to the end of the last data row.
        Since:
        8.2

      • setTabIndex

        public void setTabIndex​(int tabIndex)
        Description copied from interface: Component.Focusable
        Sets the tabulator index of the Focusable component. The tab index property is used to specify the order in which the fields are focused when the user presses the Tab key. Components with a defined tab index are focused sequentially first, and then the components with no tab index. 
         Form loginBox = new Form();
 loginBox.setCaption("Login");
 layout.addComponent(loginBox);

 // Create the first field which will be focused
 TextField username = new TextField("User name");
 loginBox.addField("username", username);

 // Set focus to the user name
 username.focus();

 TextField password = new TextField("Password");
 loginBox.addField("password", password);

 Button login = new Button("Login");
 loginBox.getFooter().addComponent(login);

 // An additional component which natural focus order would
 // be after the button.
 CheckBox remember = new CheckBox("Remember me");
 loginBox.getFooter().addComponent(remember);

 username.setTabIndex(1);
 password.setTabIndex(2);
 remember.setTabIndex(3); // Different than natural place
 login.setTabIndex(4);

        After all focusable user interface components are done, the browser can begin again from the component with the smallest tab index, or it can take the focus out of the page, for example, to the location bar.

        If the tab index is not set (is set to zero), the default tab order is used. The order is somewhat browser-dependent, but generally follows the HTML structure of the page.

        A negative value means that the component is completely removed from the tabulation order and can not be reached by pressing the Tab key at all.

        Specified by:
        setTabIndex in interface Component.Focusable
        Parameters:
        tabIndex - the tab order of this component. Indexes usually start from 1. Zero means that default tab order should be used. A negative value means that the field should not be included in the tabbing sequence.
        See Also:
        Component.Focusable.getTabIndex()