3.5.2.5. 可视化组件 API
通用
  • unwrap() - 返回针对不同客户端的组件实例(Vaadin 或者 Swing 组件)。可以在 Client 模块简化底层 API 的调用,参考 使用 Vaadin 组件 章节。

    com.vaadin.ui.TextField vTextField = textField.unwrap(com.vaadin.ui.TextField.class);
  • unwrapComposition() - 返回针对不同客户端的最外层的外部包裹容器(external container)。可以在 Client 模块简化底层 API 的调用。

这两个方法支持所有可视化组件。

Buffered-缓冲写入模式接口
  • commit() - 从上次更新之后的所有改动更新到数据源。

  • discard() - 从上次更新之后所有的改动都废弃掉。对象会从数据源更新数据。

  • isModified() - 如果从上次更新后这个对象有过改动,这个方法会返回 true

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

支持此接口的组件:

Collapsable-可折叠接口
  • addExpandedStateChangeListener() - 添加实现了 ExpandedStateChangeListener 接口的监听器来拦截组件的展开状态变化事件。

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

    支持此接口的组件:

ComponentContainer-组件容器接口
  • add(component) - 添加子组件到容器。

  • remove(component) - 从容器移除子组件。

  • removeAll() - 移除容器内所有组件。

  • getOwnComponent(id) - 返回直接拥有(directly owned)的组件。

  • getComponent(id) - 返回这个容器下面组件树的一个组件。

  • getComponentNN(id) - 返回这个容器下面组件树的一个组件。如果没找到,会抛出异常。

  • getOwnComponents() - 返回这个容器直接拥有的所有组件。

  • getComponents() - 返回这个容器下的组件树的所有组件。

支持此接口的组件:

OrderedContainer-有序容器接口
  • indexOf() - 返回给定组件在有序容器中的索引位置。

支持此接口的组件:

HasContextHelp-内容提示接口
  • setContextHelpText() - 设置内容提示文本。如果设置的话,会为字段添加一个特殊的图标,参阅: contextHelpText

  • setContextHelpTextHtmlEnabled() - 定义是否用 HTML 渲染内容提示文本。参阅: contextHelpTextHtmlEnabled

  • setContextHelpIconClickHandler() - 设置内容提示图标点击处理函数。点击处理函数比 context help text 优先级高,也就是说,如果点击处理函数设置了的话,默认的弹出小窗便不会显示。

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

几乎所有组件都支持此接口:

HasSettings-用户设置接口
  • applySettings() - 恢复上次用户使用该组件的设置。

  • saveSettings() - 保存当前用户对该组件的设置。

支持此接口的组件:

HasUserOriginated-事件来源接口
  • isUserOriginated() - 提供事件来源的信息。如果事件是在客户端通过用户交互触发,则返回 true。如果是在服务端以编程方式触发,则返回 false

    用例示范:

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

isUserOriginated() 方法支持对以下事件进行跟踪:

  • CollapseEvent,所属组件: TreeDataGrid

  • ColumnCollapsingChangeEvent,所属组件: DataGrid

  • ColumnReorderEvent,所属组件: DataGrid

  • ColumnResizeEvent,所属组件: DataGrid

  • ExpandedStateChangeEvent,所属组件: FilterGroupBoxLayout (参阅 Collapsable),

  • ExpandEvent,所属组件: TreeDataGrid

  • SelectedTabChangeEvent,所属组件: TabSheet

  • SelectionEvent,所属组件: DataGrid

  • SelectionEvent,所属组件: Table

  • SortEvent,所属组件: DataGrid

  • SplitPositionChangeEvent,所属组件: SplitPanel

  • ValueChangeEvent,所属组件:所有实现了 HasValue 接口的组件 (参阅: ValueChangeListener)。

HasValue-有值处理接口
  • addValueChangeListener() - 添加实现了 ValueChangeListener 接口的监听器来拦截组件的值变化事件。

    @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());
    }

    为了达到相同的目的,也可以订阅组件特定的事件,示例:

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

也可参阅 UserOriginated.

支持此接口的组件:

LayoutClickNotifier-布局点击通知接口
  • addLayoutClickListener() - 添加实现了 LayoutClickListener 接口的监听器拦截鼠标在组件区域点击事件。

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

    为了达到相同的目的,也可以订阅组件特定的事件,示例:

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

支持此接口的组件:

HasMargin-容器边距接口
  • setMargin() - 设置容器外边框和容器内容之间的边距。

    • 设置组件所有方向的边距:

      vbox.setMargin(true);
    • 只设置上边距和下边距:

      vbox.setMargin(true, false, true, false);
    • 创建 MarginInfo 配置类实例来设置边距:

      vbox.setMargin(new MarginInfo(true, false, false, true));
  • getMargin() - 以 MarginInfo 实例的方式返回组件的边距设置。

支持此接口的组件:

HasOuterMargin-组件外边距接口
  • setOuterMargin() - 设置组件外边框外的边距。

    • 设置所有方向的外边距:

      groupBox.setOuterMargin(true);
    • 只设置组件上下外边距:

      groupBox.setOuterMargin(true, false, true, false);
    • 创建 MarginInfo 配置类实例来设置外边距:

      groupBox.setOuterMargin(new MarginInfo(true, false, false, true));
  • getOuterMargin() - 以 MarginInfo 实例的方式返回组件的外边距设置。

支持此接口的组件:

HasSpacing-留白接口
  • setSpacing() - 在这个组件和他的子组件之间添加一些空白。

    vbox.setSpacing(true);

支持此接口的组件:

ShortcutNotifier-快捷键接口
  • addShortcutAction() - 添加一个操作,当用户按下配置的快捷键组合的时候触发。

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

支持此接口的组件: