Screen Controller Annotations

Class-level annotations on controllers are used to provide information about screens for the framework. Some annotations are applicable to any type of screen, some of them should be used only on entity edit or lookup screens.

Common Annotations

@UiController("sample_OrderScreen")
@UiDescriptor("order-screen.xml")
@MultipleOpen
@DialogMode(forceDialog = true)
public class OrderScreen extends Screen {

  • @UiController annotation indicates that the class is a screen controller. The value of the annotation is the id of the screen. You can use it to refer to the screen from the main menu or when opening the screen programmatically.

  • @UiDescriptor annotation connects the screen controller to the XML descriptor. The value of the annotation specifies the path to the descriptor file. If the value contains a file name only, it is assumed that the file is located in the same package as the controller class.

  • @MultipleOpen annotation indicates that the screen can be opened from the main menu multiple times. By default, when a user clicks a main menu item, the framework checks if the screen of the same class and id is already opened on top of the main window tab. If such screen is found, it is closed and the new instance of the screen is opened in a new tab. When the @MultipleOpen annotation is present, no checks are performed and a new instance of the screen is simply opened in a new tab.

    You can provide your own way of checking if the screen instance is the same by overriding the isSameScreen() method in the screen controller.

  • @DialogMode annotation allows you to specify geometry and behavior of the screen when it is opened in the dialog window. It corresponds to the <dialogMode> element of the XML descriptor and can be used instead. Settings in the XML descriptor have priority over the annotation for all parameters except forceDialog. If it is set to true either in the annotation or in the XML descriptor, the screen is always opened in a dialog.

Lookup Annotations

// common annotations
@UiController("sample_Order.browse")
@UiDescriptor("order-browse.xml")
// lookup-specific annotations
@LookupComponent("ordersTable")
@PrimaryLookupScreen(Order.class)
public class OrderBrowse extends StandardLookup<Order> {

  • @LookupComponent annotation specifies an id of a UI component to be used for getting a value returned from the lookup.

    Instead of using the annotation, you can specify the lookup component programmatically by overriding the getLookupComponent() method in the screen controller.

  • @PrimaryLookupScreen annotation indicates that this screen is the default lookup screen for entities of the specified type. The annotation has greater priority than the {entity_name}.lookup / {entity_name}.browse name convention.

Editor Annotations

// common annotations
@UiController("sample_Order.edit")
@UiDescriptor("order-edit.xml")
// editor-specific annotations
@EditedEntityContainer("orderDc")
@PrimaryEditorScreen(Order.class)
public class OrderEdit extends StandardEditor<Order> {

  • @EditedEntityContainer annotation specifies a data container that contains the edited entity.

    Instead of using the annotation, you can specify the container programmatically by overriding the getEditedEntityContainer() method in the screen controller.

  • @PrimaryEditorScreen annotation indicates that this screen is the default edit screen for entities of the specified type. The annotation has greater priority than the {entity_name}.edit name convention.