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"

(Step-by-step Guide)
(Step-by-step Guide)
Line 119: Line 119:
 
The following instructions allow you to create a new hyperlink contributor:
 
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.navigation
+
# Add the following dependencies to MANIFEST.MF:<syntaxhighlight lang="java">org.eclipse.papyrus.infra.gmfdiag.navigation
 
org.eclipse.papyrus.uml.navigation</syntaxhighlight>
 
org.eclipse.papyrus.uml.navigation</syntaxhighlight>
 
# Create a navigable element:<syntaxhighlight lang="java">
 
# Create a navigable element:<syntaxhighlight lang="java">

Revision as of 09:49, 4 May 2016

Overview

Papyrus has a navigation system where the user can navigate to different diagrams, and Model Explorer semantic elements, when some notation elements are clicked. The navigation system also offers the possibility to add hyperlinks to notation elements. Some noticeable characteristics of the current navigation system are the following:

  • Hyperlinks appear in diagram assistant.
  • Hyperlinks management button appears in diagram assistant.
  • Double Click on a notation element goes to its default hyperlink(s), if there are any.
  • Hyperlinks management menu lets the user create hyperlinks, assign default hyperlinks, and assign heuristics to "try" to "go somewhere" (?) when a notation element without default hyperlinks is double clicked. (Note that the heuristic functionality is broken and not clearly defined currently.)
  • Alt+Click on a notation element goes to its navigable element (e.g. return type for an Operation).
  • Diagram shortcuts in diagrams allow to navigate to a particular diagram.

The following section describes the planned changes to the navigation system.

Short Term Work

Navigation Menu

The navigation menu (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:

  • 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.
  • 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:

Papyrus Navigation Menu
.

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".

When the navigable element is clicked, a sub-menu appears. It shows 3 kinds of button:

  • A Model Explorer button to show the navigable element in the Model Explorer
  • 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:

Papyrus Navigation Alt Sub-Menu
.

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.

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.

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:

  • 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 (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 (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 should 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)

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.

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

Sections below show how to use the API to customize the navigation.

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 use this, 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 SpecialTypeNavigableElement extends GenericNavigableElement {
 public SpecialTypeNavigableElement(/*...*/) { // 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 type" + getElementLabel() + "..."; // The convention is to return a string like this
 }

 

 @Override
 public String getDescription() {
   return "Go to the special type:" + 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 SpecialTypeNavigationContributor implements NavigationContributor {
 public List<NavigableElement> getNavigableElements(Object fromElement) {
   List<NavigableElement> result = new LinkedList<NavigableElement>();

 

   /* You can check if the Object is a particular UML type for example.
      You can then add instances of "SpecialTypeNavigableElement" to the list
      of navigable elements that will be returned. */

 

   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: "SpecialTypeNavigationContributor" 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 SpecialTypeNavigationContributor whose id is "oep.specialTypeNavigationContributor"):
    IPreferenceStore preferences = Activator.getDefault().getPreferenceStore();
String key = "oep.specialTypeNavigationContributor" + ".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, example:
    • Create
      public class MyHyperlinkContributor implements HyperlinkContributor
    • Write method
      List<Hyperlink> getHyperlink(Object fromElement)
      You can check if the fromElement is a particular UML type for example. You can use the ViewerSearchService to search views containing a particular semantic element.
  4. In plugin.xml, add the following extension:
    org.eclipse.papyrus.infra.hyperlink.hyperlinkContributor
  5. Right click > New > contributor
  6. Fill info
    • Id: an arbitrary text
    • Contributor: reference to the class that will contribute automatic hyperlinks. Exemple "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
  7. (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=404945"

Back to the top