Scout/Concepts/Order Annotation

The Scout documentation has been moved to https://eclipsescout.github.io/.

The Scout documentation has been moved to https://eclipsescout.github.io/.

The order annotation is a class annotation that need to be added on top of each inner class declaration to define a ranking between them.

The annotation expect a parameter (a double) that define the rank: inner classes are sorted in the ascending order.

First example

The annotation is used to define the order of the sub-menus.

In the code corresponding to this context menu, we see that each sub-menu class is annotated with @Order:

public class AddMenu extends AbstractMenu {
 
  @Override
  protected String getConfiguredText() {
    return Texts.get("Add");
  }
 
  @Order(10.0)
  public class CollectionMenu extends AbstractMenu {
 
    @Override
    protected String getConfiguredText() {
      return Texts.get("Collection");
    }
 
    @Override
    protected void execAction() throws ProcessingException {
      //... logic to add a new collection
    }
  }
 
  @Order(20.0)
  public class PictureMenu extends AbstractMenu {
 
    @Override
    protected String getConfiguredText() {
      return Texts.get("Picture");
    }
 
    @Override
    protected void execAction() throws ProcessingException {
      //... logic to add a new image
    }
  }
}

Detailed explanation

A lot of scout concepts uses a possibility of the Java programming language: declaration of inner classes. For example The Scout documentation has been moved to https://eclipsescout.github.io/. can be declared as inner classes of the The Scout documentation has been moved to https://eclipsescout.github.io/. class or of The Scout documentation has been moved to https://eclipsescout.github.io/. (like a The Scout documentation has been moved to https://eclipsescout.github.io/.). Hardcoded declaration of The Scout documentation has been moved to https://eclipsescout.github.io/. also works that way (see the example of a The Scout documentation has been moved to https://eclipsescout.github.io/.), with The Scout documentation has been moved to https://eclipsescout.github.io/. being inner classes. This pattern can also be found for the declaration of The Scout documentation has been moved to https://eclipsescout.github.io/. in a main menu.

In the source code, the inner classes are defined a precise order. This constitute what could be qualified as a declarative definition of object, near to what can be achieved with an XML syntax.

Unfortunately there is nothing like the order of two inner classes in Java. Like elements of a set, it is not possible to know witch class was defined before the other. Therefore the Scout Framework uses an Order annotation to preserve the order information at runtime.

As soon as the order of the declaration is relevant (for example to order fields in a form), an order annotation must be added on each inner class. The Order annotation has an Double parameter. This parameter define the order in which the inner classes are considered (ascending order).

Good practices

The good practices are implemented in the SDK.

Same order in the code and with the annotation

Have the same order for the declaration in source code and defined with the order annotation. Even if the order of declaration in the source code do not mean anything (it is lost during compilation), keeping it consistent with the order defined with the annotation makes the code more readable.

Let enough space between consecutive items

Do not use consecutive number for two consecutive classes. Prefer a ten by ten count. This allows to insert a new class easily.

No additional information

Do not put any information in the ordering parameter. The SDK can assign new values (changing “10, 15 and 20” into “10, 20 and 30”). Therefore any additional information put in the values might me lost. It is not a good idea to have order parameter meaning something for the developer (like in the first example separator menu ending with a seven and admin menus with a rank bigger than 1000)

See also

• The Scout documentation has been moved to https://eclipsescout.github.io/.