Navigation_services

Modelio v4.0

In Modelio, when the user selects an element in the model explorer for example, the property view is automatically updated to display the properties of the selected element.

The underlying mechanism is based on 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.

The navigation service can be used by a module to either fire navigation event or to listen to them:

The navigation service interface is INavigationService.
The INavigationService instance can be obtained from the IModuleContext of the module via IModelioServices.

The navigation service API provides functions to:

Fire navigation events to change the current selection in Modelio
React to changes of the current selection in Modelio

A short commented 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
 8IModuleContext ctx = MyModule.getInstance().getModuleContext();
 9IModelingSession session = moduleContext.getModelingSession();
10
11// Get the INavigationService
12INavigationService navigationService = moduleContext.getModelioServices().getNavigationService();
13
14// Iterate all model roots
15for (MObject rootObj : session.getModel().getModelRoots()) {
16    if (rootObj instanceof Project) {
17
18        // Get the root package
19        Package root = ((Project) rootObj).getModel();
20
21        // Fire a navigation event to the root package
22        navigationService.fireNavigate(root);
23
24        break;
25    }
26}

line 8,9: the classical way to get the module context and the modeling session
line 12: here we get the navigation service instance via modelio services
line 15: looping on all roots until one of them is a Project instance
line 22: fire the navigation event indicating root as the target. Modelio will react by making of root the current selection
line 24: this break instruction ends the loop as we do not want to navigate to all roots

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

Modelio browser and property view will always try to react to navigation events by selecting the navigated element in their views (only if the target element is displayable by their views).

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:

Provide an implementation of the INavigationListener interface
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  IModuleCOntext ctx = MyModule.getInstance().getModuleContext;
22  INavigationService navigationService = ctx.getModelioSerices().getNavigationService();
23
24  // Register the listener
25  MyListener listener = new MyListener();
26  navigationService.addNavigationListener(listener);
27

line 7: declare a navigation listener class implementing the INavigationListener interface
line 10: redefine the navigateTo(List<MObject>) method for multiple selection if you plan to manage multiple selection
line 15: redefine the navigateTo(MObject) method for single selection if you plan to manage single selection
line 21,22: get the navigation service instance
line 25: create an instance of your navigation listener class. Note that you might want to keep a reference on this instance to later be able to remove your listener. Here a simple local variable is used to keep the code fragment simple.
line 26: register your instance of your navigation listener class to the navigation service.

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 that it is mandatory.