Difference between revisions of "Papyrus/Neon Work Description/Improvements/Navigation"

Latest revision as of 08:25, 18 January 2017

Overview and Video

This page describes the navigation feature of Papyrus implemented in Neon. The YouTube video guides you step-by-step in using the navigation feature. Sections below only describe succinctly the navigation feature.

Navigation Menus

By alt-hovering over an element, in a diagram or the model explorer, a menu pops up. This menu is called the alt-menu. The menu shows commands to navigate to some targets, which are related element or the hovered element itself (in another representation). When clicking on a command, corresponding to a target, we navigate to: (1) first representation of the target found in a(nother) diagram, or (2) the target in the model explorer if the first rule found nothing. The alt-menu also shows user-defined hyperlinks pointing to diagrams, local documents, or websites. The figure below shows the alt-menu:

The goal of the alt-menu is to navigate quickly to a target, with the user having to go through too many choices. The user may also navigate by right-clicking on an element in a diagram or the model explorer. This opens up a context menu. He can then choose where to navigate to for a selected target. The figure below shows the context menu:

The user may choose the available navigation targets in the preferences menu. The figure below shows some implemented targets:

Hyperlinks Proposition

When the user double-clicks on an element in a diagram, we navigate to its default hyperlink. If there aren't any default hyperlink(s), hyperlinks are proposed according to some pre-defined strategies. If there is only one proposed hyperlink, we navigate to it. If there are several, the user may choose one. The figure below shows the menu to choose a proposed hyperlink:

The user may choose the hyperlinks proposition strategies in the preferences menu. The figure below shows some implemented strategies:

Misc. UI Enhancements

Some other UI enhancements are implemented:

• Integration in Eclipse history to navigate to the previous/next diagram (even in different models) in the order they were opened (Gerrit 46228)
• Toolbar arrows to navigate between opened Papyrus diagram tabs (Gerrit 51264)
• Key bindings (CTRL+(SHIFT+)TAB) to navigate between opened Papyrus diagram tabs (Gerrit 46192)
• Diagram shortcuts show a preview of the diagram on mouse hover (Gerrit 47035)
• Clicking on a search result that's a semantic element, navigates to the element in the model explorer (Gerrit 52726)
• Hyperlink pointing to a document (resp. website) has the document's default icon (resp. website's favicon) (in navigation alt menu patch)

Developer Documentation

Sections below show how to use the API to contribute to the navigation menus and hyperlinks proposition strategies.

Navigation API

The navigation API has the following:

• Interface org.eclipse.papyrus.infra.services.navigation.service.ExtendedNavigableElement
  • Classes that implement this interface are navigable elements, i.e. something that wraps a semantic element, that let us navigate to some other object
  • You probably shouldn't implement this directly, but the following class:
• Class org.eclipse.papyrus.uml.navigation.navigableElement.GenericNavigableElement
  • A generic navigable element. Your own navigable element should probably extend this class, unless you know what you are doing. :)
• Extension point org.eclipse.papyrus.infra.services.navigation.navigationContributor
  • Specify extensions that will contribute navigable elements
• Interface org.eclipse.papyrus.infra.services.navigation.service.NavigationContributor
  • Classes that implement this interface contribute navigable elements
  • The "getNavigableElements(Object)" method returns navigable elements according to the context represented by the object passed as parameter. (You do not need to handle how to pass the object, only what to do with it)

Step-by-step Guide

The following instructions allow you to create a new hyperlink contributor:

• Create a plugin
• Add the following dependencies to MANIFEST.MF:

org.eclipse.papyrus.infra.gmfdiag.navigation
org.eclipse.papyrus.uml.navigation

• Create a navigable element:

public class SpecialTargetNavigableElement extends GenericNavigableElement {
  public SpecialTargetNavigableElement(/*...*/) { // Write a constructor that will call "super(Element elt)" where "elt" is the semantic element that this navigable element wraps
    super(/*...*/);
  }
 
  @Override
  public String getLabel() {
    return "Go to special target" + getElementLabel() + "..."; // The convention is to return a string like this
  }
 
  @Override
  public String getDescription() {
    return "Go to the special target:" + getElementLabel(); // The convention is to return a string like this
  }
 
  // You can also overwrite other methods of GenericNavigableElement
}

• Create a navigation contributor:

public class SpecialTargetNavigationContributor implements NavigationContributor {
  public List<NavigableElement> getNavigableElements(Object fromElement) {
    List<NavigableElement> result = new LinkedList<NavigableElement>();
 
    /* You can check if fromElement is a particular UML type for example.
       You can then add instances of "SpecialTargetNavigableElement" to the list
       of navigable elements that will be returned. What you wrap with
       the navigable element is up to you. Usually we wrap an element related to
       fromElement. */
 
    return result;
  }
}

• In plugin.xml, add the following extension:

org.eclipse.papyrus.infra.services.navigation.navigationContributor

• Right click > New > contributor
• Fill info
  • Id: an arbitrary string
  • Contributor: reference to the class that will contribute navigable elements. Example: "SpecialTargetNavigationContributor" created beforehand.
  • Label: how this contributor is displayed in preferences (for activation/deactivation)
  • Description: tooltip displayed when the mouse hovers over this contributor in the preferences
• (Optional) Activate/deactivate a hyperlink contributor programmatically (example for "SpecialTargetNavigationContributor" whose id is "oep.specialTargetNavigationContributor"):

IPreferenceStore preferences = Activator.getDefault().getPreferenceStore();
String key = "oep.specialTargetNavigationContributor" + ".isActive";
preferences.setValue(key, true); // or false  to deactivate

Real Example

An example of a hyperlink contributor is available below. This contributor creates automatic hyperlinks for a class that has inner classes shown in its inner class diagrams.

• /org.eclipse.papyrus.uml.navigation/src/org/eclipse/papyrus/uml/navigation/navigableElement/TargetNavigableElement.java
• /org.eclipse.papyrus.uml.navigation/src/org/eclipse/papyrus/uml/navigation/navigableElement/RelationshipNavigationContributor.java
• /org.eclipse.papyrus.uml.navigation/plugin.xml (line 48)

Hyperlink API

API Overview

The hyperlink API has the following:

• Extension point org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor
  • Specify extensions that will contribute hyperlinks
• Interface org.eclipse.papyrus.infra.hyperlink.service.HyperlinkContributor
  • Classes that implement this interface may contribute hyperlinks
  • The "getHyperlink(Object)" method returns a list of hyperlinks according to the context represented by the object that is passed as parameter. (You do not need to handle how to pass the object, only what to do with it)

Step-by-step Guide

The following instructions allow you to create a new hyperlink contributor:

• Create a plugin
• Add the following dependency to MANIFEST.MF:

org.eclipse.papyrus.infra.gmfdiag.hyperlink

• Create a hyperlink contributor:

public class MyHyperlinkContributor implements HyperlinkContributor {
  public List<HyperLinkObject> getHyperlinks(Object fromElement) {
    ArrayList<HyperLinkObject> hyperlinks = new ArrayList<HyperLinkObject>();
    /* You can check if fromElement is a particular UML type for example.
       You can use the org.eclipse.papyrus.infra.services.viewersearch.impl.ViewerSearchService
       to search views containing a particular semantic element.
       See Real Example section for an example on how to use the ViewerSearchService */
    return hyperlinks;
  }
}

• In plugin.xml, add the following extension:

org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor

• Right click > New > contributor
• Fill info
  • Id: an arbitrary text
  • Contributor: reference to the class that will contribute hyperlinks. Example: "MyHyperlinkContributor" created beforehand.
  • Label: how this contributor is displayed in preferences (for activation/deactivation)
  • Description: tooltip displayed when the mouse hovers over this contributor in the preferences
• (Optional) Activate/deactivate a hyperlink contributor programmatically (example for MyHyperlinkContributor whose id is "oep.myHyperlinkContributor"):

IPreferenceStore preferences = Activator.getDefault().getPreferenceStore();
String key = "oep.myHyperlinkContributor" + ".isActive";
preferences.setValue(key, true) // or false  to deactivate

Real Example

An example of a hyperlink contributor is available below. This contributor creates automatic hyperlinks for a class that has inner classes shown in its inner class diagrams.

• /org.eclipse.papyrus.uml.diagram.clazz/custom-src/org/eclipse/papyrus/uml/diagram/clazz/custom/hyperlink/InnerClassHyperlinkContributor.java
• /org.eclipse.papyrus.uml.diagram.clazz/plugin.xml (line 1733)

Bugzilla References

• Bug 463589 - Navigation Alt Menu
• Bug 462005 - Navigation to baseclass and subclass missing
• Bug 461746 - The navigation service should browse all available diagrams - not only the current one
• Bug 407733 - Papyrus shall support navigation history with back and next buttons
• Bug 463687 - Not possible to see and click-to-navigate to opposite elements across links in Model Explorer
• Bug 471697 - Toolbar buttons to go to next/previous diagram in active window
• Bug 465122 - Keys to traverse opened tabs in editor
• Bug 465886 - Double-click default action
• Bug 466294 - Preview on mouse hover
• Bug 467017 - Local file URI should be relative
• Bug 473763 - Clicking on a ModelMatch should navigate to the Model Explorer rather than a View
• Bug 465697 - AbstractNattableWidgetManager does not compare real objects in revealElement
• Bug 473763 - Clicking on a ModelMatch should navigate to the Model Explorer rather than a View
• Bug 491077 - Make the current alt-navigation menu easier to access