5.5.1.3.2. AbstractWindow

AbstractWindow is a subclass of AbstractFrame and defines the following methods:

  • getDialogOptions() – returns a DialogOptions object to control geometry and behaviour of the screen when it is opened as a dialog (WindowManager.OpenType.DIALOG). These options can be set when the screen is initialized as well as can be changed at a runtime. See the examples below.

    Setting the width and height:

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

    Setting the dialog position on the screen:

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

    Making the dialog closeable by click on outside area:

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

    Making the dialog non-modal and resizable:

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

    Defining whether the dialog should be maximized across the screen:

    getDialogOptions().setMaximized(true);

    Specifying that the screen should always be opened as a dialog regardless of what WindowManager.OpenType was selected in the calling code:

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

  • setContentSwitchMode() - defines how the managed main TabSheet should switch a tab with the given window: hide it or unload its content.

    Three options are available:

    • DEFAULT - the switch mode is determined by the managed main TabSheet mode, defined in the cuba.web.managedMainTabSheetMode application property.

    • HIDE - the tab content should be hidden not considering the TabSheet mode.

    • UNLOAD - tab content should be unloaded not considering the TabSheet mode.

  • saveSettings() - saves the screen settings of the current user to the database when the screen is closed.

    For example, the screen contains a checkBox showPanel that manages some panel’s visibility. In the following method we create an XML element for the checkBox, then add an attribute showPanel containing the checkBox value to this element, and finally we save the settings element to the XML descriptor for the current user in the database:

    @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() - restores settings saved in the database for the current user when the screen is opened.

    This method can be overridden to restore custom settings. For example, in the method below we get the XML element of the checkBox from the previous example, then we make sure the required attribute is not null, and if it isn’t, we set the restored value to the checkBox:

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

    Another example of managing settings is the standard Server Log screen from the Administration menu of CUBA application that automatically saves and restores recently opened log files.

  • ready() - a template method that can be implemented in controller to intercept the moment of screen opening. It is invoked when the screen is fully initialized and opened.

  • validateAll() – validates a screen. The default implementation calls validate() for all screen components implementing the Component.Validatable interface, collects information about exceptions and displays corresponding message. Method returns false, if any exceptions were found; and true otherwise.

    This method should be overridden only if it is required to override screen validation procedure completely. It is sufficient to implement a special template method – postValidate(), if validation should be just supplemented.

  • postValidate() – a template method that can be implemented in controller for additional screen validation. The method stores validation errors information in ValidationErrors object which is passed to it. Afterwards this information is displayed together with the errors of standard validation. For example:

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

  • close() – closes this screen.

    The method accepts string value, which is then passed to preClose() template method and to CloseListener listeners. Thus, the information about the reason why the window was closed can be obtained from the code that initiated the closing event. It is recommended to use the following constants for closing edit screens: Window.COMMIT_ACTION_ID after committing changes, Window.CLOSE_ACTION_ID – without committing changes.

    If any of the datasources contains unsaved changes, a dialog with a corresponding message will be displayed before the screen is closed. Notification type may be adjusted using the cuba.gui.useSaveConfirmation application property.

    A variant of close() method with force = true parameter closes the screen without calling preClose() and without a notification regardless of any unsaved changes.

    close() method returns true, if the screen is closed successfully, and false – if closing procedure was interrupted.

  • preClose() is a template method which can be implemented in a controller to intercept the moment when the window closes. The method receives a string value provided by the closing initiator when invoking close() method.

    If the preClose() method returns false, the window closing process is interrupted.

  • addBeforeCloseWithCloseButtonListener() - adds a listener to be notified when a screen is closed with one of the following approaches: the screen’s close button, bread crumbs, or TabSheet tabs' close actions (Close, Close All, Close Others). To prevent a user from closing a window accidentally, invoke the preventWindowClose() method of BeforeCloseEvent:

    addBeforeCloseWithCloseButtonListener(BeforeCloseEvent::preventWindowClose);

  • addBeforeCloseWithShortcutListener - adds a listener to be notified when a screen is closed with a close shortcut (for example, Esc button). To prevent a user from closing a window accidentally, invoke the preventWindowClose() method of BeforeCloseEvent:

    addBeforeCloseWithShortcutListener(BeforeCloseEvent::preventWindowClose);
API

addBeforeCloseWithCloseButtonListener() - addBeforeCloseWithShortcutListener() - applySettings() - close() - setContentSwitchMode() - getDialogOptions() - postValidate() - preClose() - ready() - saveSettings() - validateAll()