3.5.2.5. API of Components
Common
  • unwrap() - returns client-specific component instance (Vaadin or Swing component). Can be used in client module to simplify invocation of underlying API, see Working with Vaadin Components section.

    com.vaadin.ui.TextField vTextField = textField.unwrap(com.vaadin.ui.TextField.class);
  • unwrapComposition() - returns the outmost external container of client-specific component instance. Can be used in client module to simplify invocation of underlying API.

Available for all components.

Buffered
  • commit() - updates all changes made since the previous commit to the data source.

  • discard() - discards all changes since last commit. The object updates its value from the data source.

  • isModified() - returns true if the object value has been modified since it was last updated from the data source.

if (textArea.isModified()) {
    textArea.commit();
}

Available for components:

Collapsable
  • addExpandedStateChangeListener() - adds the listener implementing the ExpandedStateChangeListener interface to intercept the component’s expanded state change events.

    @Subscribe("groupBox")
    protected void onGroupBoxExpandedStateChange(Collapsable.ExpandedStateChangeEvent event) {
        notifications.create()
                .withCaption("Expanded: " + groupBox.isExpanded())
                .show();
    }

    Available for components:

ComponentContainer
  • add() - adds child component to the container.

  • remove() - removes the child component from the container.

  • removeAll() - removes all children components from te container.

  • getOwnComponent() - returns the component directly owned by this container.

  • getComponent() - returns the component belonging to the whole components tree below this container.

  • getComponentNN() - returns the component belonging to the whole components tree below this container. Throws an exception if not found.

  • getOwnComponents() - returns all components directly owned by this container.

  • getComponents() - returns all components belonging to the whole components tree below this container.

Available for components:

OrderedContainer
  • indexOf() - returns the index of a given component in an ordered container.

Available for components:

HasContextHelp
  • setContextHelpText() - sets context help text. If set, then a special icon will be added for a field, see contextHelpText.

  • setContextHelpTextHtmlEnabled() - defines if context help text should be rendered as HTML, see contextHelpTextHtmlEnabled.

  • setContextHelpIconClickHandler() - sets a context help icon click handler. Click handler has priority over context help text, i.e. no tooltip with context help text will be shown if the click handler is set.

textArea.setContextHelpIconClickHandler(contextHelpIconClickEvent ->
        dialogs.createMessageDialog()
                .withCaption("Title")
                .withMessage("Message body")
                .withType(Dialogs.MessageType.CONFIRMATION)
                .show()
);

Available for almost all components:

HasSettings
  • applySettings() - restores the last user settings for this component.

  • saveSettings() - saves current user settings for this component.

Available for components:

HasUserOriginated
  • isUserOriginated() - provides information of the event origin. Returns true if this event was triggered by user interaction, on the client side, or false if it was triggered programmatically, on the server side.

    Usage example:

    @Subscribe("customersTable")
    protected void onCustomersTableSelection(Table.SelectionEvent<Customer> event) {
        if (event.isUserOriginated())
            notifications.create()
                    .withCaption("You selected " + event.getSelected().size() + " customers")
                    .show();
    }

The isUserOriginated() method is available for the following events:

HasValue
  • addValueChangeListener() - adds the listener implementing the ValueChangeListener interface to intercept the component’s value changes.

    @Inject
    private TextField<String> textField;
    @Inject
    private Notifications notifications;
    
    @Subscribe
    protected void onInit(InitEvent event) {
        textField.addValueChangeListener(stringValueChangeEvent ->
                notifications.create()
                        .withCaption("Before: " + stringValueChangeEvent.getPrevValue() +
                                ". After: " + stringValueChangeEvent.getValue())
                        .show());
    }

    For the same purpose, you can subscribe to a dedicated event of a component, for example:

    @Subscribe("textField")
    protected void onTextFieldValueChange(HasValue.ValueChangeEvent<String> event) {
        notifications.create()
                .withCaption("Before: " + event.getPrevValue() +
                        ". After: " + event.getValue())
                .show();
    }

See also UserOriginated.

Available for components:

LayoutClickNotifier
  • addLayoutClickListener() - adds the listener implementing the LayoutClickListener interface to intercept the clicks on the component area.

    vbox.addLayoutClickListener(layoutClickEvent ->
        notifications.create()
                .withCaption("Clicked")
                .show());

    For the same purpose, you can subscribe to a dedicated event of a component, for example:

    @Subscribe("vbox")
    protected void onVboxLayoutClick(LayoutClickNotifier.LayoutClickEvent event) {
        notifications.create()
                .withCaption("Clicked")
                .show();
    }

Available for components:

HasMargin
  • setMargin() - sets the margins for the component.

    • Sets margins on all sides of the component:

      vbox.setMargin(true);
    • Sets margins only on the top and the bottom of the component:

      vbox.setMargin(true, false, true, false);
    • Creates new instance of MarginInfo configuration class:

      vbox.setMargin(new MarginInfo(true, false, false, true));
  • getMargin() - returns margin configuration as an instance of MarginInfo class.

HasOuterMargin
  • setOuterMargin() - sets the outer margins outside the border of the component.

    • Sets outer margins on all sides of the component:

      groupBox.setOuterMargin(true);
    • Sets outer margins only on the top and the bottom of the component:

      groupBox.setOuterMargin(true, false, true, false);
    • Creates new instance of MarginInfo configuration class:

      groupBox.setOuterMargin(new MarginInfo(true, false, false, true));
  • getOuterMargin() - returns outer margin configuration as an instance of MarginInfo class.

Available for component:

HasSpacing
  • setSpacing() - adds space between the component and its child components.

    vbox.setSpacing(true);

Available for components:

ShortcutNotifier
  • addShortcutAction() - adds an action which is triggered when the user presses a given key combination.

    cssLayout.addShortcutAction(new ShortcutAction("SHIFT-A", shortcutTriggeredEvent ->
            notifications.create()
                    .withCaption("SHIFT-A action")
                    .show()));

Available for components: