可视化组件 API - CUBA 框架开发者手册

3.5.2.5. 可视化组件 API

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

支持此接口的组件：

CheckBox - CurrencyField - DateField - DatePicker - FileUploadField - LookupField - LookupPickerField - MaskedField - PasswordField - PickerField - RichTextArea - SearchPickerField - SuggestionPickerField - TextArea - TextField - TimeField

Collapsable-可折叠接口

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

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

支持此接口的组件：

Filter - GroupBoxLayout

ComponentContainer-组件容器接口

add(component) - 添加子组件到容器。

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

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

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

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

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

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

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

支持此接口的组件：

Accordion - BoxLayout - CssLayout - FieldGroup - Form - Frame - GridLayout - GroupBoxLayout - HtmlBoxLayout - ScrollBoxLayout - SplitPanel - TabSheet

OrderedContainer-有序容器接口

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

支持此接口的组件：

BoxLayout - CssLayout - Frame - GroupBoxLayout - ScrollBoxLayout -

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

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

Accordion - BoxLayout - BrowserFrame - ButtonsPanel - Calendar - CheckBox - CheckBoxGroup - ColorPicker - CssLayout - CurrencyField - DataGrid - DateField - DatePicker - Embedded - FieldGroup - FileUploadField - Filter - Form - GridLayout - GroupBoxLayout - GroupTable - HtmlBoxLayout - Image - JavaScriptComponent - Label - LookupField - LookupPickerField - MaskedField - OptionsGroup - OptionsList - PasswordField - PickerField - PopupView - ProgressBar - RadioButtonGroup - RichTextArea - ScrollBoxLayout - SearchPickerField - Slider - SourceCodeEditor - SplitPanel - SuggestionField - SuggestionPickerField - Table - TabSheet - TextArea - TextField - TimeField - TokenList - Tree - TreeDataGrid - TreeTable - TwinColumn

HasSettings-用户设置接口

applySettings() - 恢复上次用户使用该组件的设置。
saveSettings() - 保存当前用户对该组件的设置。

支持此接口的组件：

DataGrid - Filter - GroupBoxLayout - SplitPanel - Table - TextArea

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 和 Tree，
ColumnCollapsingChangeEvent，所属组件： DataGrid，
ColumnReorderEvent，所属组件： DataGrid，
ColumnResizeEvent，所属组件： DataGrid，
ExpandedStateChangeEvent，所属组件： Filter 和 GroupBoxLayout (参阅 Collapsable)，
ExpandEvent，所属组件： TreeDataGrid 和 Tree，
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();
}

支持此接口的组件：

ButtonsPanel - BoxLayout - CssLayout - GridLayout

HasMargin-容器边距接口

setMargin() - 设置容器外边框和容器内容之间的边距。
- 设置组件所有方向的边距：
  vbox.setMargin(true);
- 只设置上边距和下边距：
  vbox.setMargin(true, false, true, false);
- 创建 MarginInfo 配置类实例来设置边距：
  vbox.setMargin(new MarginInfo(true, false, false, true));
getMargin() - 以 MarginInfo 实例的方式返回组件的边距设置。

支持此接口的组件：

BoxLayout - Filter - Frame - GridLayout ScrollBoxLayout

HasOuterMargin-组件外边距接口

setOuterMargin() - 设置组件外边框外的边距。
- 设置所有方向的外边距：
  groupBox.setOuterMargin(true);
- 只设置组件上下外边距：
  groupBox.setOuterMargin(true, false, true, false);
- 创建 MarginInfo 配置类实例来设置外边距：
  groupBox.setOuterMargin(new MarginInfo(true, false, false, true));
getOuterMargin() - 以 MarginInfo 实例的方式返回组件的外边距设置。

支持此接口的组件：

GroupBoxLayout

HasSpacing-留白接口

setSpacing() - 在这个组件和他的子组件之间添加一些空白。
```
vbox.setSpacing(true);
```

支持此接口的组件：

BoxLayout - ButtonsPanel - Frame - GridLayout GroupBoxLayout - ScrollBoxLayout

ShortcutNotifier-快捷键接口

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

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

支持此接口的组件：

BoxLayout - ButtonsPanel - CssLayout - GridLayout - GroupBoxLayout - ScrollBoxLayout