Contact us
Create app
com.vaadin.ui.

Interface Component

    • Method Detail

      • getStyleName

        String getStyleName()

        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.

        Returns:

        the style name or a space-separated list of user-defined style names of the component

        See Also:

        setStyleName(String), addStyleName(String), removeStyleName(String)

      • setStyleName

        void setStyleName​(String style)

        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.

        Parameters:

        style - the new style or styles of the component as a space-separated list

        See Also:

        getStyleName(), addStyleName(String), removeStyleName(String)

      • setStyleName

        default void setStyleName​(String style,
                          boolean add)

        Adds or removes a style name. Multiple styles can be specified as a space-separated list of style names. If the add parameter is true, the style name is added to the component. If the add parameter is false, the style name is removed from the component.

        Functionally this is equivalent to using addStyleName(String) or removeStyleName(String)

        Parameters:

        style - the style name to be added or removed

        add - true to add the given style, false to remove it

        Since:

        8.5

        See Also:

        addStyleName(String), removeStyleName(String)

      • addStyleName

        void addStyleName​(String style)

        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;}

        Parameters:

        style - the new style to be added to the component

        See Also:

        getStyleName(), setStyleName(String), removeStyleName(String)

      • removeStyleName

        void removeStyleName​(String style)

        Removes one or more style names from component. Multiple styles can be specified as a space-separated list of style names.

        The parameter must be a valid CSS style name. Only user-defined style names added with addStyleName() or setStyleName() can be removed; built-in style names defined in Vaadin or GWT can not be removed.

        Parameters:

        style - the style name or style names to be removed

        See Also:

        getStyleName(), setStyleName(String), addStyleName(String)

      • getPrimaryStyleName

        String getPrimaryStyleName()

        Gets the primary style name of the component. See setPrimaryStyleName(String) for a better description of the primary stylename.

        Returns:

        the primary style name

      • setPrimaryStyleName

        void setPrimaryStyleName​(String style)

        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.

        Parameters:

        style - The new primary style name

      • isEnabled

        boolean isEnabled()

        Tests whether the component is enabled or not. A user can not interact with disabled components. Disabled components are rendered in a style that indicates the status, usually in gray color. Children of a disabled component are also disabled. Components are enabled by default.

        As a security feature, all updates for disabled components are blocked on the server-side.

        Note that this method only returns the status of the component and does not take parents into account. Even though this method returns true the component can be disabled to the user if a parent is disabled.

        Returns:

        true if the component and its parent are enabled, false otherwise.

        See Also:

        VariableOwner.isEnabled()

      • setEnabled

        void setEnabled​(boolean enabled)

        Enables or disables the component. The user can not interact with disabled components, which are shown with a style that indicates the status, usually shaded in light gray color. Components are enabled by default. 

         Button enabled = new Button("Enabled");
 enabled.setEnabled(true); // The default
 layout.addComponent(enabled);

 Button disabled = new Button("Disabled");
 disabled.setEnabled(false);
 layout.addComponent(disabled);

        Parameters:

        enabled - a boolean value specifying if the component should be enabled or not

      • isVisible

        boolean isVisible()

        Tests the visibility property of the component.

        Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent. Making a component invisible through this property can alter the positioning of other components.

        A component is visible only if all its parents are also visible. This is not checked by this method though, so even if this method returns true, the component can be hidden from the user because a parent is set to invisible.

        Returns:

        true if the component has been set to be visible in the user interface, false if not

        See Also:

        setVisible(boolean), attach()

      • setVisible

        void setVisible​(boolean visible)

        Sets the visibility of the component.

        Visible components are drawn in the user interface, while invisible ones are not. The effect is not merely a cosmetic CSS change - no information about an invisible component will be sent to the client. The effect is thus the same as removing the component from its parent. 

         TextField readonly = new TextField("Read-Only");
 readonly.setValue("You can't see this!");
 readonly.setVisible(false);
 layout.addComponent(readonly);

        A component is visible only if all of its parents are also visible. If a component is explicitly set to be invisible, changes in the visibility of its parents will not change the visibility of the component.

        Parameters:

        visible - the boolean value specifying if the component should be visible after the call or not.

        See Also:

        isVisible()

      • setParent

        void setParent​(HasComponents parent)

        Sets the parent connector of the component.

        This method automatically calls attach() if the component becomes attached to the session, regardless of whether it was attached previously. Conversely, if the component currently is attached to the session, ClientConnector.detach() is called for the connector before attaching it to a new parent.

        This method is rarely called directly. ComponentContainer.addComponent(Component) or a HasComponents specific method is normally used for adding components to a parent and the used method will call this method implicitly.

        Parameters:

        parent - the parent connector

        Throws:

        IllegalStateException - if a parent is given even though the connector already has a parent

      • getParent

        HasComponents getParent()

        Gets the parent component of the component.

        Components can be nested but a component can have only one parent. A component that contains other components, that is, can be a parent, should usually inherit the ComponentContainer interface.

        Specified by:

        getParent in interface ClientConnector

        Specified by:

        getParent in interface Connector

        Returns:

        the parent component

      • getCaption

        String getCaption()

        Gets the caption of the component.

        See setCaption(String) for a detailed description of the caption.

        Returns:

        the caption of the component or null if the caption is not set.

        See Also:

        setCaption(String)

      • setCaption

        void setCaption​(String caption)

        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.

        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

      • getIcon

        Resource getIcon()

        Gets the icon resource of the component.

        See setIcon(Resource) for a detailed description of the icon.

        Returns:

        the icon resource of the component or null if the component has no icon

        See Also:

        setIcon(Resource)

      • setIcon

        void setIcon​(Resource icon)

        Sets the icon of the component.

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

        The image is loaded by the browser from a resource, typically a ThemeResource. 

         // Component with an icon from a custom theme
 TextField name = new TextField("Name");
 name.setIcon(new ThemeResource("icons/user.png"));
 layout.addComponent(name);

 // Component with an icon from another theme ('runo')
 Button ok = new Button("OK");
 ok.setIcon(new ThemeResource("../runo/icons/16/ok.png"));
 layout.addComponent(ok);

        The icon 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 icons left-aligned above the contained components, while the FormLayout component shows the icons on the left side of the vertically laid components, with the icons and their associated components left-aligned in their own columns. The CustomComponent does not manage the icon of its composition root, so if the root component has an icon, it will not be rendered.

        An icon will be rendered inside an HTML element that has the v-icon CSS style class. The containing layout may enclose an icon and a caption inside elements related to the caption, such as v-caption .

        Parameters:

        icon - the icon of the component. If null, no icon is shown and it does not normally take any space.

        See Also:

        getIcon(), setCaption(String)

      • getUI

        UI getUI()

        Gets the UI the component is attached to.

        If the component is not attached to a UI through a component containment hierarchy, null is returned.

        Specified by:

        getUI in interface ClientConnector

        Returns:

        the UI of the component or null if it is not attached to a UI

      • attach

        void attach()

        Notifies the connector that it is connected to a VaadinSession (and therefore also to a UI).

        The caller of this method is setParent(HasComponents) if the parent is itself already attached to the session. If not, the parent will call the ClientConnector.attach() for all its children when it is attached to the session. This method is always called before the connector's data is sent to the client-side for the first time.

        The attachment logic is implemented in AbstractClientConnector.

        Reimplementing the attach() method is useful for tasks that need to get a reference to the parent, window, or application object with the getParent() and getUI() methods. A component does not yet know these objects in the constructor, so in such case, the methods will return null. For example, the following is invalid: 

         public class AttachExample extends CustomComponent {
     public AttachExample() {
         // ERROR: We can't access the application object yet.
         ClassResource r = new ClassResource("smiley.jpg",
                 getApplication());
         Embedded image = new Embedded("Image:", r);
         setCompositionRoot(image);
     }
 }

        Adding a component to an application triggers calling the attach() method for the component. Correspondingly, removing a component from a container triggers calling the ClientConnector.detach() method. If the parent of an added component is already connected to the application, the attach() is called immediately from setParent(HasComponents). 

         public class AttachExample extends CustomComponent {
     public AttachExample() {
     }

     @Override
     public void attach() {
         super.attach(); // Must call.

         // Now we know who ultimately owns us.
         ClassResource r = new ClassResource("smiley.jpg",
                 getApplication());
         Embedded image = new Embedded("Image:", r);
         setCompositionRoot(image);
     }
 }

        Specified by:

        attach in interface ClientConnector

      • getLocale

        Locale getLocale()

        Gets the locale of the component.

        If a component does not have a locale set, the locale of its parent is returned, and so on. Eventually, if no parent has locale set, the locale of the application is returned. If the application does not have a locale set, it is determined by Locale.getDefault().

        As the component must be attached before its locale can be acquired, using this method in the internationalization of component captions, etc. is generally not feasible. For such use case, we recommend using an otherwise acquired reference to the application locale.

        Returns:

        Locale of this component or null if the component and none of its parents has a locale set and the component is not yet attached to an application.

      • setId

        void setId​(String id)

        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.

        Parameters:

        id - An alphanumeric id

      • getId

        String getId()

        Gets currently set debug identifier.

        Returns:

        current id, null if not set

      • getDescription

        String getDescription()

        Gets the components description, used in tooltips and can be displayed directly in certain other components such as forms. The description can be used to briefly describe the state of the component to the user. The description string may contain certain XML tags:

        Tag Description Example
        <b> bold bold text
        <i> italic italic text
        <u> underlined underlined text
        <br> linebreak N/A
        <ul>
        <li>item1
        <li>item1
        </ul>        		 item list
        • item1
        • item2

        These tags may be nested.

        Returns:

        component's description String

      • readDesign

        void readDesign​(org.jsoup.nodes.Element design,
                DesignContext designContext)

        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.

        Parameters:

        design - The element to obtain the state from

        designContext - The DesignContext instance used for parsing the design

        Since:

        7.4

      • writeDesign

        void writeDesign​(org.jsoup.nodes.Element design,
                 DesignContext designContext)

        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.

        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

        Since:

        7.4

      • addListener

        Registration addListener​(Component.Listener listener)

        Registers a new (generic) component event listener for the component. 

         class Listening extends CustomComponent implements Listener {
     // Stored for determining the source of an event
     Button ok;

     Label status; // For displaying info about the event

     public Listening() {
         VerticalLayout layout = new VerticalLayout();

         // Some miscellaneous component
         TextField name = new TextField("Say it all here");
         name.addListener(this);
         layout.addComponent(name);

         // Handle button clicks as generic events instead
         // of Button.ClickEvent events
         ok = new Button("OK");
         ok.addListener(this);
         layout.addComponent(ok);

         // For displaying information about an event
         status = new Label("");
         layout.addComponent(status);

         setCompositionRoot(layout);
     }

     public void componentEvent(Event event) {
         // Act according to the source of the event
         if (event.getSource() == ok)
             getWindow().showNotification("Click!");

         status.setValue(
                 "Event from " + event.getSource().getClass().getName()
                         + ": " + event.getClass().getName());
     }
 }

 Listening listening = new Listening();
 layout.addComponent(listening);

        Parameters:

        listener - the new Listener to be registered.

        Returns:

        a registration object for removing this listener

        Since:

        8.0

        See Also:

        Component.Event, Registration