3.6.1.3.2. AbstractWindow

这是旧版本的 API。对于从 7.0 开始的新 API,请参阅 界面控制器

AbstractWindowAbstractFrame 的子类,定义下列方法:

  • getDialogOptions() – 返回一个 DialogOptions - 对话框选项 对象,在界面以对话框模式(WindowManager.OpenType.DIALOG)打开的时候用来控制窗口的几何属性以及行为。这些选项可以在界面初始化的时候设置,也可以在运行时设置。参考下面的例子。

    设置宽度和高度:

    @Override
    public void init(Map<String, Object> params) {
        getDialogOptions().setWidth("480px").setHeight("320px");
    }

    设置对话框在界面中的位置:

    getDialogOptions()
            .setPositionX(100)
            .setPositionY(100);

    设置对话框可通过点击外部区域关闭:

    getDialogOptions().setModal(true).setCloseOnClickOutside(true);

    设置对话框非模态(non-modal)打开,并且可改变大小:

    @Override
    public void init(Map<String, Object> params) {
        getDialogOptions().setModal(false).setResizable(true);
    }

    设置对话框打开时候最大化:

    getDialogOptions().setMaximized(true);

    设置界面总是按照对话框的方式打开,不论在调用时 WindowManager.OpenType 参数是如何选择:

    @Override
    public void init(Map<String, Object> params) {
        getDialogOptions().setForceDialog(true);
    }
  • setContentSwitchMode() - 定义在指定的窗口中 主 tab 标签应当怎样切换标签页:隐藏还是清除界面内容。

    有三个可选项:

    • DEFAULT - 切换模式由 TabSheet 模式 cuba.web.managedMainTabSheetMode 应用程序属性定义。

    • HIDE - 不考虑 TabSheet 的模式,直接隐藏。

    • UNLOAD - 不考虑 TabSheet 的模式,清除界面内容。

  • saveSettings() - 界面关闭时,保存当前用户对界面的设置到数据库。

    比如,界面包含一个复选框 showPanel 用来管理某个面板是否可见。在下面的方法中,为复选框创建一个 XML 元素,然后用这个组件的值添加一个 showPanel 属性,最后为当前用户保存 XML 描述的 settings 元素内容到数据库:

    @Inject
    private CheckBox showPanel;
    
    @Override
    public void saveSettings() {
        boolean showPanelValue = showPanel.getValue();
        Element xmlDescriptor = getSettings().get(showPanel.getId());
        xmlDescriptor.addAttribute("showPanel", String.valueOf(showPanelValue));
        super.saveSettings();
    }
  • applySettings() - 当界面打开时,为当前用户恢复数据库保存的设置。

    这个方法可以被重写用来保存自定义设置。比如,在下面的方法中,取到上面例子中复选框的 XML 元素,然后确保需要的属性不是 null,之后将恢复的值设置到复选框上:

    @Override
    public void applySettings(Settings settings) {
        super.applySettings(settings);
        Element xmlDescriptor = settings.get(showPanel.getId());
        if (xmlDescriptor.attribute("showPanel") != null) {
            showPanel.setValue(Boolean.parseBoolean(xmlDescriptor.attributeValue("showPanel")));
        }
    }

    另一个管理设置的例子就是应用程序内的 Administration - 管理 菜单的标准 Server Log - 服务器日志 界面,它能自动保存和恢复最近打开的日志文件。

  • ready() - 控制器中可以实现的一个模板方法,用来拦截界面打开动作。当界面全部初始化完毕并且打开之后会调用这个方法。

  • validateAll() – 验证一个界面。方法默认实现就是对所有实现了 Component.Validatable 接口的界面组件调用 validate() 方法,然后搜集异常的信息,并且显示相应的消息。如果有任何异常,方法会返回 false,否则返回 true

    只有在需要完全重写界面验证过程的情况下,才需要重写这个方法。如果需要补充额外的验证,实现一个特殊的模板方法就足够了 - postValidate()

  • postValidate() – 可以在控制器实现的模板方法,用来做额外的界面验证。这个方法将验证错误信息保存在传给它的参数 ValidationErrors 对象内。之后,这些错误信息会跟标准验证的错误信息一起显示,示例:

    private Pattern pattern = Pattern.compile("\\d");
    
    @Override
    protected void postValidate(ValidationErrors errors) {
        if (getItem().getAddress().getCity() != null) {
            if (pattern.matcher(getItem().getAddress().getCity()).find()) {
                errors.add("City name can't contain digits");
            }
        }
    }
  • showValidationErrors() - 显示验证错误警告。可以重写这个方法来更改默认的警告行为。通知类型可以通过 cuba.gui.validationNotificationType 应用程序属性来定义。

    @Override
    public void showValidationErrors(ValidationErrors errors) {
        super.showValidationErrors(errors);
    }
  • close() – 关闭当前界面。

    这个方法可以传入字符串参数,这个参数然后传递给 preClose() 模板方法,再传递给 CloseListener 监听器。因此,关于窗口关闭原因的信息可以通过发起关闭事件的代码获得。推荐使用这些常量来关闭编辑界面:提交改动后使用 Window.COMMIT_ACTION_ID,不提交改动的话使用 Window.CLOSE_ACTION_ID

    如果任何数据源包含没保存的改动,在界面关闭前会弹出窗口提示相关信息。通知的类型可以通过 cuba.gui.useSaveConfirmation 应用程序属性调整。

    close() 方法还有一个带有 force = true 参数的变体,这个方法可以不调用 preClose() 就关闭界面,也不会出现关于未保存信息的对话框消息。

    如果界面顺利关闭,close() 方法返回 true。如果关闭的过程中断,则会返回 false。、

  • preClose() 控制器中可以实现的一个模板方法,用来拦截界面关闭动作。这个方法可以接收从 close() 方法传递过来的参数。

    如果关闭的过程中断,preClose() 方法会返回 false

  • addBeforeCloseWithCloseButtonListener() - 当界面通过下列方法关闭的时候添加一个关闭时的监听器:界面的关闭按钮、面包屑(bread crumbs)或者 TabSheet 标签的关闭操作(Close - 关闭, Close All - 关闭全部, Close Others - 关闭其它)。如果需要避免用户误操作关闭窗口,可以调用 BeforeCloseEvent 事件的 preventWindowClose() 方法:

    addBeforeCloseWithCloseButtonListener(BeforeCloseEvent::preventWindowClose);
  • addBeforeCloseWithShortcutListener - 当界面通过快捷键方式(比如,Esc 按钮)关闭的时候,添加一个关闭时的监听器。如果需要避免用户误操作关闭窗口,可以调用 BeforeCloseEvent 事件的 preventWindowClose() 方法:

    addBeforeCloseWithShortcutListener(BeforeCloseEvent::preventWindowClose);