Back to the FAQ

Navigation services

Modelio v3

In Modelio, when the user selects an element in the model explorer for example, the property view is automatically updated to display the proerties of the selected element. The underlying mechanism is based on so-called Modelio’s Navigation services. The model explorer actually fires a navigation event which is transmitted to the registered navigation listeners, the property view in our example.

Modelio API navigation services can be used by a module to either fire navigation event or to listen to them.

The Navigation service

Using the Modelio navigation services is quite straigthforward.

  1. get the Modelio navigation service object INavigationService from the modeling session
  2. call one of the INavigationServiceprovided methods

Firing navigation events

A short code example will tell more than a long explanation.

 1import org.modelio.api.app.navigation.INavigationListener;
 2import org.modelio.api.app.navigation.INavigationService;
 3import org.modelio.api.model.IModelingSession;
 4import org.modelio.metamodel.mda.Project;
 5import org.modelio.metamodel.uml.statik.Package;
 6import org.modelio.vcore.smkernel.mapi.MObject;
 7         
 8IModelingSession session = Modelio.getInstance().getModelingSession();
 9
10// Get the INavigationService
11INavigationService navigationService = Modelio.getInstance().getNavigationService();
12
13// Iterate all model roots
14for (MObject rootObj : session.getModel().getModelRoots()) {
15    if (rootObj instanceof Project) {
16
17        // Get the root package
18        Package root = ((Project) rootObj).getModel();
19
20        // Fire a navigation event to the root package
21        navigationService.fireNavigate(root);
22    }
23}

Note that you can navigate to any model element, just remember that a navigation event is just an indication or a kind of wish and that navigation listeners remain free to process or not the navigation event you fired.

Listening to navigation events

Navigation listeners receive the navigation events that are fired in the application, whoever fired them. This means that, as a listener, you will be notified of any navigation event you could fire! So firing navigation event while processing a received navigation event is probably a bad idea without tricky precautions…

To become a navigation listener you simply have to:

  1. implement the INavigationListener interface
  2. register this implementation as a listener in the navigation service
 1import org.modelio.api.app.navigation.INavigationListener;
 2import org.modelio.api.app.navigation.INavigationService;
 3import org.modelio.api.model.IModelingSession;
 4import org.modelio.vcore.smkernel.mapi.MObject;
 5
 6
 7static class MyListener implements INavigationListener {
 8
 9    @Override
10    public void navigateTo(List<MObject> selection) {
11        System.out.println("Multiple selection navigation event received!");
12    }
13
14    @Override
15    public void navigateTo(MObject target) {
16        System.out.println("navigation event received!");
17    }
18}
19         
20  // Get the INavigationService
21  INavigationService navigationService = Modelio.getInstance().getNavigationService();
22      
23  // Register the listener
24  MyListener listener = new MyListener();
25  navigationService.addNavigationListener(listener);
26

Later on you can remove your registered listener at any time by calling the removeNavigationListener(INavigationListener listener) method of INavigationService. Note that, in any case, you are responsible for removing your registered listeners (for example when your module stops) and it is mandatory.

The INavigationListener interface defines two methods:

  • navigateTo(MObject target) for navigation to a single element
  • navigateTo(List<MObject> selection) for navigation to multiple elements at once.