Screen Controller Methods

In this section, we describe some methods of screen controller base classes that can be invoked or overridden in the application code.

Methods of All Screens

  • show() - shows the screen. This method is usually used after creating the screen as described in the Opening Screens section.

  • close() - closes the screen with the passed StandardOutcome enum value or a CloseAction object. For example:

    @Subscribe("closeBtn")
public void onCloseBtnClick(Button.ClickEvent event) {
    close(StandardOutcome.CLOSE);
}

    The parameter value is propagated to the BeforeCloseEvent and AfterCloseEvent, so the information about the reason why the screen was closed can be obtained in the listeners. For more information on using these listeners, see Executing code after close and returning values.

  • getScreenData() - returns the ScreenData object that serves as a registry for all data components defined in the screen XML descriptor. You can use its loadAll() method to trigger all data loaders of the screen:

    @Subscribe
public void onBeforeShow(BeforeShowEvent event) {
    getScreenData().loadAll();
}

Methods of StandardEditor

  • getEditedEntity() - when the screen is shown, returns an instance of the entity being edited. It’s the instance that is set in the data container specified in the @EditedEntityContainer annotation.

    In the InitEvent and AfterInitEvent listeners, this method returns null. In the BeforeShowEvent listener, this method returns the instance passed to the screen for editing (later in the screen opening process the entity is reloaded and a different instance is set to the data container).

The following methods can be used to close the edit screen:

  • closeWithCommit() - validates and saves data, then closes the screen with StandardOutcome.COMMIT.

  • closeWithDiscard() - ignores any unsaved changes and closes the screen with StandardOutcome.DISCARD.

If the screen has unsaved changes in DataContext, a dialog with a corresponding message will be displayed before the screen is closed. You can adjust the notification type using the jmix.ui.screen.use-save-confirmation application property. If you use the closeWithDiscard() or close(StandardOutcome.DISCARD) methods, unsaved changes are ignored without any message.

  • commitChanges() - saves changes without closing the screen. You can call this method from a custom event listener or override the default windowCommit action listener to perform some operations after the data has been saved, for example:

    @Override
protected void commit(Action.ActionPerformedEvent event) {
    commitChanges().then(() -> {
        commitActionPerformed = true; (1)
        // ... (2)
    });
}
    1 This flag is used for returning the correct outcome on subsequent screen closing.
    2 You can perform actions after the data has been saved.

  • validateAdditionalRules() method can be overridden for additional validation before saving changes. The method should store the information about validation errors in the 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("\\s");

@Override
protected void validateAdditionalRules(ValidationErrors errors) {
    if (getEditedEntity().getNum() != null) {
        if (pattern.matcher(getEditedEntity().getNum()).find()) {
            errors.add("Number cannot contain whitespaces");
        }
    }
    super.validateAdditionalRules(errors);
}

Methods of MasterDetailScreen

  • getEditedEntity() - when the screen is in the edit mode, returns an instance of the entity being edited. It’s the instance that is set in the data container of the form component. If the screen is not in edit mode, the method throws IllegalStateException.

  • validateAdditionalRules() method can be overridden for additional validation on saving changes as described above for StandardEditor.