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)

@@ Line 7: / Line 7: @@
 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:
-[[File:papyrus_nav_alt_menu.png|thumb|center|200px|alt=Papyrus Navigation Alt-Menu]]
+[[File:papyrus_nav_alt_menu.png|frame|center|alt=Papyrus Navigation 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:
-[[File:papyrus_nav_popup_menu.png|thumb|center|908px|alt=Papyrus Navigation Context Menu]]
+[[File:papyrus_nav_popup_menu.png|frame|center|alt=Papyrus Navigation Context Menu]]
 The user may choose the available navigation targets in the preferences menu. The figure below shows some implemented targets:
-[[File:papyrus_navigation_preferences.png|thumb|center|671px|alt=Papyrus Navigation Target Preferences]]
+[[File:papyrus_navigation_preferences.png|frame|center|alt=Papyrus Navigation Target Preferences]]
 == Hyperlinks Proposition ==
@@ Line 21: / Line 32: @@
 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:
-[[File:papyrus_hyperlink_menu.png|thumb|center|391px|alt=Papyrus Proposed Hyperlinks Menu]]
+[[File:papyrus_hyperlink_menu.png|frame|center|alt=Papyrus Proposed Hyperlinks Menu]]
 The user may choose the hyperlinks proposition strategies in the preferences menu. The figure below shows some implemented strategies:
-[[File:papyrus_hyperlink_preferences.png|thumb|center|822px|alt=Papyrus Hyperlink Preferences]]
+[[File:papyrus_hyperlink_preferences.png|frame|center|alt=Papyrus Hyperlink Preferences]]
 == Misc. UI Enhancements ==
@@ Line 59: / Line 76: @@
 The following instructions allow you to create a new hyperlink contributor:
-# Create a plugin
+* Create a plugin
-# Add the following dependencies to MANIFEST.MF:<syntaxhighlight lang="java">org.eclipse.papyrus.infra.gmfdiag.navigation
+* Add the following dependencies to MANIFEST.MF:
-org.eclipse.papyrus.uml.navigation</syntaxhighlight>
+<syntaxhighlight lang="java">
-# Create a navigable element:<syntaxhighlight lang="java">
+org.eclipse.papyrus.infra.gmfdiag.navigation
+org.eclipse.papyrus.uml.navigation
+</syntaxhighlight>
+* Create a navigable element:
+<syntaxhighlight lang="java">
 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
@@ Line 79: / Line 100: @@
    // You can also overwrite other methods of GenericNavigableElement
-}</syntaxhighlight>
+}
-# Create a navigation contributor:<syntaxhighlight lang="java">
+</syntaxhighlight>
+* Create a navigation contributor:
+<syntaxhighlight lang="java">
 public class SpecialTargetNavigationContributor implements NavigationContributor {
    public List<NavigableElement> getNavigableElements(Object fromElement) {
@@ Line 93: / Line 116: @@
      return result;
    }
-}</syntaxhighlight>
+}
-# In plugin.xml, add the following extension:<syntaxhighlight lang="java">org.eclipse.papyrus.infra.services.navigation.navigationContributor</syntaxhighlight>
+</syntaxhighlight>
-# Right click > New > contributor
+* In plugin.xml, add the following extension:
-# Fill info
+<syntaxhighlight lang="java">
-#* Id: an arbitrary string
+org.eclipse.papyrus.infra.services.navigation.navigationContributor
-#* Contributor: reference to the class that will contribute navigable elements. Example: "SpecialTargetNavigationContributor" created beforehand.
+</syntaxhighlight>
-#* Label: how this contributor is displayed in preferences (for activation/deactivation)
+* Right click > New > contributor
-#* Description: tooltip displayed when the mouse hovers over this contributor in the preferences
+* Fill info
-# (Optional) Activate/deactivate a hyperlink contributor programmatically (example for "SpecialTargetNavigationContributor" whose id is "oep.specialTargetNavigationContributor"):<syntaxhighlight lang="java">
+** 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"):
+<syntaxhighlight lang="java">
 IPreferenceStore preferences = Activator.getDefault().getPreferenceStore();
 String key = "oep.specialTargetNavigationContributor" + ".isActive";
-preferences.setValue(key, true) // or false  to deactivate
+preferences.setValue(key, true); // or false  to deactivate
 </syntaxhighlight>
@@ Line 128: / Line 156: @@
 The following instructions allow you to create a new hyperlink contributor:
-# Create a plugin
+* Create a plugin
-# Add the following dependency to MANIFEST.MF:<syntaxhighlight lang="java">org.eclipse.papyrus.infra.gmfdiag.hyperlink</syntaxhighlight>
+* Add the following dependency to MANIFEST.MF:
-# Create a hyperlink contributor:<syntaxhighlight lang="java">
+<syntaxhighlight lang="java">org.eclipse.papyrus.infra.gmfdiag.hyperlink</syntaxhighlight>
+* Create a hyperlink contributor:
+<syntaxhighlight lang="java">
 public class MyHyperlinkContributor implements HyperlinkContributor {
    public List<HyperLinkObject> getHyperlinks(Object fromElement) {
@@ Line 140: / Line 170: @@
      return hyperlinks;
    }
-}</syntaxhighlight>
+}
-# In plugin.xml, add the following extension:<syntaxhighlight lang="java">org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor</syntaxhighlight>
+</syntaxhighlight>
-# Right click > New > contributor
+* In plugin.xml, add the following extension:
-# Fill info
+<syntaxhighlight lang="java">org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor</syntaxhighlight>
-#* Id: an arbitrary text
+* Right click > New > contributor
-#* Contributor: reference to the class that will contribute hyperlinks. Example: "MyHyperlinkContributor" created beforehand.
+* Fill info
-#* Label: how this contributor is displayed in preferences (for activation/deactivation)
+** Id: an arbitrary text
-#* Description: tooltip displayed when the mouse hovers over this contributor in the preferences
+** Contributor: reference to the class that will contribute hyperlinks. Example: "MyHyperlinkContributor" created beforehand.
-# (Optional) Activate/deactivate a hyperlink contributor programmatically (example for MyHyperlinkContributor whose id is "oep.myHyperlinkContributor"):<syntaxhighlight lang="java">
+** 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"):
+<syntaxhighlight lang="java">
 IPreferenceStore preferences = Activator.getDefault().getPreferenceStore();
 String key = "oep.myHyperlinkContributor" + ".isActive";

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

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

Latest revision as of 08:25, 18 January 2017

Contents

Overview and Video

Navigation Menus

Hyperlinks Proposition

Misc. UI Enhancements

Developer Documentation

Navigation API

Step-by-step Guide

Real Example

Hyperlink API

API Overview

Step-by-step Guide

Real Example

Bugzilla References

Breadcrumbs

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

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

Latest revision as of 08:25, 18 January 2017

Contents

Overview and Video

Navigation Menus

Hyperlinks Proposition

Misc. UI Enhancements

Developer Documentation

Navigation API

Step-by-step Guide

Real Example

Hyperlink API

API Overview

Step-by-step Guide

Real Example

Bugzilla References