Skip to main content

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.

Jump to: navigation, search

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

(→‎Overview)
Line 1: Line 1:
−
== Overview ==
+
== Overview and Video ==
  
−
This page describes the navigation feature of Papyrus implemented in Neon.
+
This page describes the navigation feature of Papyrus implemented in Neon. [https://youtu.be/OsOnOLu8dXk The YouTube video] guides you step-by-step in using the navigation feature. Sections below only describe succinctly the navigation feature.
  
−
== Short Term Work ==
+
== Navigation Menus ===
  
−
=== Navigation Menu ===
+
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 navigation menu ([https://git.eclipse.org/r/#/c/47354/ Gerrit 47354]) is a popup menu. It is shown when the user Alt+Hovers over a notation element in a view. Navigation and hyperlink systems are integrated into the navigation menu menu. The navigation menu has three kinds of default buttons:
+
[[File:papyrus_nav_alt_menu.png|thumb|center|470px|alt=Papyrus Navigation Alt-Menu]]
  
−
* Navigable element: a button which represents a UML element that can be show in other views or the Model Explorer. The button lets the user choose where to show the UML element.
+
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:
−
* Hyperlink: a button representing a user created hyperlink
+
−
* Modify hyperlink button: a button to open the hyperlinks management menu
+
−
* More button: a button to make dynamic buttons appear (more on this later)
+
  
−
The figure below shows the 4 kinds of default buttons in the navigation menu:
+
[[File:papyrus_nav_popup_menu.png|thumb|center|711px|alt=Papyrus Navigation Context Menu]]
  
−
[[File:papyrus_nav_alt_menu.png|thumb|center|470px|alt=Papyrus Navigation Menu]] .
+
The user may choose the available navigation targets in the preferences menu. The figure below shows some implemented targets:
  
−
Here Operation "op1" of "MyClass" is Alt+Hovered over. The menu shows the return type navigable element of "op1", the navigable element "op1" itself, a hyperlink created for "op1" (points to an ActivityDiagram), the button to modify hyperlinks for "op1", and finally the button to see dynamic buttons for "op1".
+
[[File:papyrus_hyperlink_preferences.png|thumb|center|711px|alt=Papyrus Navigation Target Preferences]]
  
−
When the navigable element is clicked, a sub-menu appears. It shows 3 kinds of button:
+
== Hyperlinks Proposition ==
  
−
* A Model Explorer button to show the navigable element in the Model Explorer
+
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:
−
* One-to-several view buttons to navigate to opened views where the navigable element appears
+
−
* A "More..." button to show closed views in which the navigable element appears
+
  
−
For example when the return type navigable element of "op1" is clicked, the following sub-menu appears:
+
[[File:papyrus_hyperlink_menu.png|thumb|center|711px|alt=Papyrus Proposed Hyperlinks Menu]]
  
−
[[File:papyrus_nav_alt_submenu.png|thumb|center|711px|alt=Papyrus Navigation Alt Sub-Menu]] .
+
The user may choose the hyperlinks proposition strategies in the preferences menu. The figure below shows some implemented strategies:
  
−
Here the sub-menu shows four buttons. The first button shows the return type of "op1" in the Model Explorer. The second (resp. third) button shows the return type of "op1", named "MyEnumeration", in opened view "DatatypesAndEnumeration" (resp. "EnumerationsOnly"). Finally the fourth button makes closed views appear, where the return type of "op1" is present.
+
[[File:papyrus_hyperlink_preferences.png|thumb|center|711px|alt=Papyrus Hyperlink Preferences]]
  
−
Besides the default buttons, there are also dynamic buttons. When a dynamic button is clicked on, a sub-menu appears showing some navigable elements related to the element that triggered the navigation menu. The behavior of each navigable element in the sub-menu is the same as a navigable element in the navigation menu.
+
== Misc. UI Enhancements ==
  
−
The dynamic buttons are contributed by plugin extension. The user may choose which extensions to activate, within the preference menu of Papyrus. Some examples of default extensions in Papyrus are:
+
Some other UI enhancements are implemented:
−
 
+
−
* Parents: parents of the element
+
−
* Children: children of the element
+
−
* Types: other elements typed by the type
+
−
* Views: all views in which the element appears
+
−
* Behaviors: behaviors owned by the classifier
+
−
* Containers: packages or classifiers (in case of nested classes) that contain the element
+
−
* Etc...
+
−
 
+
−
The navigation menu is also integrated into the Model Explorer view. It should be integrated into the Properties view.
+
−
 
+
−
=== Default Hyperlink Proposition ===
+
−
 
+
−
When the user double-clicks on a graphical element we navigate to its default hyperlink. If there aren't any default hyperlink(s), hyperlinks are proposed ([https://git.eclipse.org/r/#/c/47282/ Gerrit 47282]) according to the element that was double-clicked, and a particular hyperlink proposition algorithm for the element. If there is only one proposed hyperlink, we navigate to it. If there are several, the user may choose one particular.
+
−
 
+
−
The proposed hyperlinks do not persist, i.e. there are not saved in the notation model. The hyperlinks proposition algorithms are contributed via the new hyperlink extension framework. This functionality replaces the heuristic tab of the old hyperlink menu.
+
−
 
+
−
=== Misc. UI Enhancements ===
+
−
 
+
−
Some other UI enhancements are planned:
+
  
 
* Integration in Eclipse history to navigate to the previous/next diagram (even in different models) in the order they were opened ([https://git.eclipse.org/r/#/c/46228/ Gerrit 46228])
 
* Integration in Eclipse history to navigate to the previous/next diagram (even in different models) in the order they were opened ([https://git.eclipse.org/r/#/c/46228/ Gerrit 46228])
 
* Toolbar arrows to navigate between opened Papyrus diagram tabs ([https://git.eclipse.org/r/#/c/51264/ Gerrit 51264])
 
* Toolbar arrows to navigate between opened Papyrus diagram tabs ([https://git.eclipse.org/r/#/c/51264/ Gerrit 51264])
 
* Key bindings (CTRL+(SHIFT+)TAB) to navigate between opened Papyrus diagram tabs ([https://git.eclipse.org/r/#/c/46192/ Gerrit 46192])
 
* Key bindings (CTRL+(SHIFT+)TAB) to navigate between opened Papyrus diagram tabs ([https://git.eclipse.org/r/#/c/46192/ Gerrit 46192])
−
* Diagram shortcuts should show a preview of the diagram on mouse hover ([https://git.eclipse.org/r/#/c/47035/ Gerrit 47035])
+
* Diagram shortcuts show a preview of the diagram on mouse hover ([https://git.eclipse.org/r/#/c/47035/ Gerrit 47035])
 
* Clicking on a search result that's a semantic element, navigates to the element in the model explorer ([https://git.eclipse.org/r/#/c/52726/ Gerrit 52726])
 
* Clicking on a search result that's a semantic element, navigates to the element in the model explorer ([https://git.eclipse.org/r/#/c/52726/ Gerrit 52726])
 
* Hyperlink pointing to a document (resp. website) has the document's default icon (resp. website's favicon) (in navigation alt menu patch)
 
* Hyperlink pointing to a document (resp. website) has the document's default icon (resp. website's favicon) (in navigation alt menu patch)
−
 
−
== Long Term Work ==
 
−
 
−
=== Navigation Graph ===
 
−
 
−
''This section is a draft.'' The navigation graph represents relationships between the elements of a user's model. The navigation graph is described by the user through a DSML, offered by Papyrus. The DSML can be implemented as a UML profile. In the navigation graph, each vertex is a UML metaclass or a stereotype. Each edge indicates that there is some kind of relationship between two metaclasses or stereotypes.
 
−
 
−
For example the user can have a navigation graph where there are two vertices: <<Car>> and <<Wheel>>. There is an edge between <<Car>> and <<Wheel>> called "OwnedWheels". This example navigation graph can be interpreted by Papyrus. The navigation menu for <<Car>> would then have a dynamic button called "OwnerWheels".
 
−
 
−
This feature is planned for post-Mars.
 
−
<!--Section draft, first ideas:
 
−
* Representation of model as a graph
 
−
* Vertices would be (diagrams, navigable elements, etc... ?), and edges would be (hyperlink, UML semantic relationship, etc... ?)
 
−
* A new DSML can be proposed to describe the graph and its entities (profile, Ecore, other?)
 
−
* A new Papyrus diagram can be contributed to visualize the graph
 
−
* The graph can be used to generate a navigation strategy (e.g. automatic generation of UI arrows and their behavior)
 
−
* The navigation strategy can be used to create a timed/controlled presentation of the model, i.e. start at a vertex, navigate automatically/manually from vertex to vertex.-->
 
−
 
−
=== Hyperlink Graph ===
 
−
 
−
''This section is a draft.'' The hyperlink graph represents the whole notation model (i.e. views) as a graph. Each vertex is a view. Each edge is a hyperlink between two views. The user can visualize the hyperlink graph through a special kind of diagram to Papyrus.
 
−
 
−
Through the diagram that represents the hyperlink graph, the user may also create a presentation. A presentation lets the user navigate through vertices of the hyperlink graph, i.e. starting with a chosen initial view, the user goes from views to views. In the presentation, transition between vertices can either be automatic and timed, or by clicking on some UI button.
 
−
 
−
This feature is planned for post-Mars.
 
  
 
== Developer Documentation ==
 
== Developer Documentation ==
  
−
Sections below show how to use the API to customize navigation and hyperlink.
+
Sections below show how to use the API to contribute to the navigation menus and hyperlinks proposition strategies.
  
 
=== Navigation API ===
 
=== Navigation API ===

Revision as of 12:29, 9 May 2016

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:

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:

Papyrus Navigation Context Menu

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

Papyrus Navigation Target Preferences

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:

Papyrus Proposed Hyperlinks Menu

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

Papyrus Hyperlink Preferences

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:

  1. Create a plugin
  2. Add the following dependencies to MANIFEST.MF:
    org.eclipse.papyrus.infra.gmfdiag.navigation
org.eclipse.papyrus.uml.navigation
  1. 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
}
  1. 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;
 }
}
  1. In plugin.xml, add the following extension:
    org.eclipse.papyrus.infra.services.navigation.navigationContributor
  2. Right click > New > contributor
  3. 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
  4. (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.

Hyperlink API

API Overview

The hyperlink API has the following:

Step-by-step Guide

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

  1. Create a plugin
  2. Add the following dependency to MANIFEST.MF:
    org.eclipse.papyrus.infra.gmfdiag.hyperlink
  3. 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; } }
  1. In plugin.xml, add the following extension:
    org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor
  2. Right click > New > contributor
  3. 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
  4. (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.

Bugzilla References

Retrieved from "https://wiki.eclipse.org/index.php?title=Papyrus/Neon_Work_Description/Improvements/Navigation&oldid=405030"

Back to the top