3.5.1.1.2. 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 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();
    }
  • getSettings() - returns the Settings object that can be used to read or write custom settings associated with the screen for the current user.

  • saveSettings() - saves the screen settings represented by the Settings object. This method is called automatically if cuba.gui.manualScreenSettingsSaving application property is set to false (which is the default).

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

    In InitEvent and AfterInitEvent listeners, this method returns null. In 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 cuba.gui.useSaveConfirmation 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(() -> {
            // this flag is used for returning correct outcome on subsequent screen closing
            commitActionPerformed = true;
            // perform actions after the data has been saved
        });
    }

    The default implementation of the commit() method shows a notification about successful commit. You can switch it off using the setShowSaveNotification(false) method on screen initialization.

  • 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("\\d");

@Override
protected void validateAdditionalRules(ValidationErrors errors) {
    if (getEditedEntity().getAddress().getCity() != null) {
        if (pattern.matcher(getEditedEntity().getAddress().getCity()).find()) {
            errors.add("City name cannot contain digits");
        }
    }
    super.validateAdditionalRules(errors);
}
Methods of MasterDetailScreen
  • getEditedEntity() - when the screen is in edit mode, returns an instance of the entity being edited. It’s the instance which 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.