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 "GEF/GEF4/Zest"

< GEF‎ | GEF4
(Moved DOT related things to GEF/GEF4/DOT)
m
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
TODO: Create a stand-alone documentation of the GEF4 Zest component here. Up to now, some documentation can already be found under [[Zest]]
+
''Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in [http://wiki.eclipse.org/GEF/GEF4/Zest the original wiki page]''.
  
''Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in [http://wiki.eclipse.org/Zest the original wiki page]''.
+
== Introduction ==
  
== GEF4 Zest ==
+
GEF4 Zest is a graph visualization component that can be used to visualize [[GEF/GEF4/Graph|GEF4 Graph]]-based graph models, applying automatic layout as provided by [[GEF/GEF4/Layout|GEF4 Layout]]. It uses JavaFX and [[GEF/GEF4/FX| GEF4 FX]] for visualization purposes and is internally based on [[GEF/GEF4/MVC|GEF4 MVC]].
  
This is a collection of documentation on Zest 2.0, the latest development version of Zest. Zest 2 is part of [[GEF/GEF4|GEF4]] and can be installed from the [[GEF/GEF4#Update_Sites|GEF4 Update Sites]]. Additional information can also be found here:
+
[[Image:GEF4Zest.FX-GraphExample.png|GEF4 Zest: ZestGraphExample]]
  
* [[Tree_Views_for_Zest | Zest 2.0 Layout API]]
+
== MVC ==
* [[Zest/DOT | Graphviz DOT support]]
+
  
== Contribute ==
+
The GEF4 MVC component is used as the framework for the viewer.
  
The Zest 2 source code is available from the [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4 Git repository]. It is also [https://github.com/eclipse/gef4 mirrored on GitHub]. There are example snippets in ''org.eclipse.gef4.zest.examples'' and tests in ''org.eclipse.gef4.zest.tests''. For instructions on contributing, see the [[GEF/Contributor Guide | GEF Contributor Guide]]. You can search for [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=4722702&classification=Tools&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Zest&product=GEF existing bugs], or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=GEF&component=Zest file a new one].
+
The ContentParts are implemented for the GEF4 Graph data model:
 +
* GraphContentPart
 +
* NodeContentPart
 +
* EdgeContentPart
  
== New subgraph rendering ==
+
== Visualization Properties ==
  
In GEF4 Zest, subgraphs can hide their contained nodes or add different types of additional information about ''pruned'' elements:  
+
The visualization is based on the attributes that are associated with graphs, nodes, or edges. The following attributes are supported:
 +
* For graphs: type, layout.
 +
* For nodes/edges: css-class, css-id, label, layout-irrelevant.
 +
* For nodes: node-rect-css-style, node-label-css-style, icon, tooltip, fisheye, hidden.
 +
* For edges: edge-curve-css-style, edge-label-css-style, edge-router, style.
  
=== LabelSubgraph ===
+
== Layout Integration ==
  
Each subgraph is represented as a separate graph item: a label showing the number of nodes contained within it. It can be subclassed to show other kinds of information.
+
The GEF4 Layout interfaces are adopted to the GEF4 Graph data model. The layout objects are constructed from a given Graph object.
  
[[Image:Zest-tree-subgraph-label.png|150px‎]]
+
=== Properties ===
  
=== TriangleSubgraph ===
+
The layout objects support a general property mechanism to exchange layout information. GEF4 Zest transfers visualization attributes (locations and sizes) to layout properties and vice versa.
  
Each subgraph is represented as a triangle. It's designed specifically to work with ''SpaceTreeLayoutAlgorithm'' (see below) and assumes that nodes ''pruned'' inside it form a tree structure. Properties of this structure are visualized by properties of the triangle. The height of the triangle corresponds to the height of the tree, the length of the triangle's base corresponds to the total number of leaves in the tree and the luminance of the triangle's color corresponds to the average number of children for each node in the tree (which can be understood as the density).
+
=== LayoutModel ===
  
[[Image:Zest-tree-subgraph-triangle.png|150px‎]]
+
The LayoutContext for a graph is stored in the LayoutModel that is associated with the corresponding GraphContentPart.
  
=== PrunedSuccessorsSubgraph ===  
+
== Eclipse Integration ==
  
Each subgraph is represented as a little label showing how many direct successors are ''pruned''.
+
GEF4 Zest provides an Eclipse ViewPart (o.e.g4.zest.fx.ui.parts.ZestFxUiView) for visualizing graph models, so that you can integrate it into the Eclipse workbench.
 
+
[[Image:Zest-tree-subgraph-successors.png|150px‎]]
+
  
 
== Migration from Zest 1.x to GEF4 Zest ==
 
== Migration from Zest 1.x to GEF4 Zest ==
  
 +
[[GEF/GEF4/Zest|GEF4 Zest]] was mostly written from scratch, replacing the Zest 1.x API as well as the provisional Zest 2.x API ( [[Tree_Views_for_Zest | Zest 2.0 Layout API]]) that was developed as an intermediate step.
 +
 +
The Zest 1.x API consists of two parts: 1) a core API for the visualization of graphs, and 2) an on-top JFace API with specific content and label providers and a viewer dedicated to displaying Zest graphs. The former has been replaced by GEF4 Zest.FX and the latter by GEF4 Zest.FX.UI.
 +
 +
=== Migration from Zest 1.x Core to GEF4 Zest.FX ===
 +
 +
In comparison to the Zest 1.x Core API, which is based on SWT/Draw2d visualization-wise, and interweaves graph data, layout data, and visuals, the new GEF4 Zest API, on the other hand, is based on [[GEF/GEF4/MVC|GEF4 MVC]] and maintains distinct object hierarchies for the graph data (content model), the layout data (layout model), and the visuals. This decouples the code, which is one of the design goals of GEF4 in general. As a result, you cannot directly affect the visualization as in Zest 1.x Core, but instead modify the underlying graph model which will effect a content synchronization, i.e. update the visualization based on the content changes. Therefore, to transition from Zest 1.x Core to GEF4 Zest.FX, you have to create/modify a [[GEF/GEF4/Graph|GEF4 Graph]] where previously Zest 1.x Graph, GraphNode, and GraphConnection were created/modified.
 +
 +
Since GEF4 Zest is based on [[GEF/GEF4/MVC|GEF4 MVC]], you should be familiar with the mechanisms and concepts of GEF4 MVC, which are employed as follows:
 +
* A ContentModel stores the Graph that is currently rendered.
 +
* A ContentPartFactory constructs controller objects (content parts) for graphs, nodes, and edges. These are responsible for the visualization, content synchronization, and layout integration.
 +
* All content parts support an adapter mechanism where you can set/query adapters for distinct keys. Functionality can be added to a content part by setting a corresponding adapter on it. For example, you can enable different interactions (moving nodes via drag, etc.) by setting the corresponding policies as adapters on the content parts.
 +
* A Module defines (Guice) bindings for the context of an application. Using this mechanism, you can specify which adapters should be set on the different content parts. For example, the adapter mechanism is used to integrate GEF4 Layout into GEF4 Zest.
 +
 +
The GEF4 Git repository contains an [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.graph/src/org/eclipse/gef4/zest/examples/graph/ZestGraphExample.java example] on how to use the new API. The example is very simple as the rendered graph is not modified later on. However, it contains everything that is needed for a fully functional example. As you can see when taking a look into the source code, attributes are set on the graph model to specify certain visualization features such as label, tooltip, CSS id, etc.. Actually, the whole visualization results from those attributes. You can find a list of all available attributes [[GEF/GEF4/Zest#Attributes here]].
 +
 +
Some specific Zest 1.x Core functionalities are implemented differently within GEF4 Zest.FX. The corresponding use case scenerios are as follows.
 +
 +
==== Custom node/edge visualization ====
 +
 +
As the content parts are responsible for the visualization, you have to create a custom content part in order to exchange the visualization of certain graph elements. GEF4 Zest.FX uses a ContentPartFactory to create content parts for graph elements. Therefore, you have to exchange the ContentPartFactory to be able to create custom content parts. The ZestFxModule contains a binding for the ContentPartFactory, i.e. you have to override the corresponding ContentPartFactory#bindIContentPartFactory() method in your module to bind a CustomContentPartFactory instead. Within the CustomContentPartFactory, you can construct custom content parts, for example, for graph elements with specific attributes.
 +
 +
The GEF4 Git repository contains an [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.layout.examples/src/org/eclipse/gef4/layout/examples/CustomNodeLayoutExample.java example] of this scenario. However, note that colors, fonts, borders, and sizes can be configured via JavaFX CSS and do not need a custom visualization.
 +
 +
==== Modifying graphs ====
 +
 +
Since you cannot modify the visualization directly, you have to adjust the underlying graph model instead. The visualization is then updated automatically. The GEF4 Git repository contains an [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.layout.examples/src/org/eclipse/gef4/layout/examples/FullyMeshedLayoutExample.java example] of this scenario.
 +
 +
==== Layout filter ====
 +
 +
=== Migration from Zest 1.x JFace to GEF4 Zest.FX.UI ===
 +
 +
GEF4 Zest.FX.UI consists of a ZestContentViewer and five zest-specific content and label providers. In comparison to the Zest 1.x JFace API, the ZestContentViewer is not a StructuredViewer anymore, but just a ContentViewer. Zooming is part of the Zest 1.x GraphViewer, but this is already covered within GEF4 MVC.FX. Moreover, the functionality of some of the Zest 1.x JFace providers is covered by standard JFace providers, and is therefore replaced by them:
 +
* The old IEntityStyleProvider provides tooltip, fisheye, border, and color information. These are now provided via standard JFace IToolTipProvider, JFace IColorProvider, and GEF4 IGraphNodeLabelProvider (which provides arbitrary attributes for nodes, edges, and graphs). Additionally, the JFace IFontProvider is supported, which provides a Font for a node.
 +
* The old IConnectionStyleProvider (and IEntityConnectionStyleProvider) provide style, color, tooltip, connection router, and connection decorator. These are now provided via GEF4 IEdgeDecorationProvider and GEF4 IGraphNodeLabelProvider, except for the tooltip, which is currently not supported for edges within GEF4 Zest.FX.
 +
 +
Probably, the biggest difference between the Zest 1.x JFace API and GEF4 Zest.FX.UI are the content providers. Zest.FX.UI defines two content providers:
 +
* The IGraphNodeContentProvider provides all content elements that represent nodes for a flat graph. The edges are inferred via a <code>#getConnectedTo(Object)</code> method. This is the equivalent of the Zest 1.x IGraphEntityContentProvider.
 +
* The INestedGraphContentProvider extends the IGraphNodeContentProvider by two methods to provide nested graphs. This is the equivalence of the Zest 1.x INestedContentProvider.
 +
So, both new content providers are node-oriented, i.e. they provide content elements which represent nodes, not edges. The Zest 1.x API additionally defines an IGraphEntityRelationshipContentProvider which provides content elements that represent edges, which is not covered by Zest.FX.UI.
  
=== Layout Filters ===
+
Besides, the following providers have not been migrated, because their corresponding functionality is implemented by means of another mechanism:
 +
* The Zest 1.x IFigureProvider provides a custom visualization for a node. This is now done by creating a different content part for nodes with a custom visualization, as can be seen in this [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceCustomNodeExample.java example].
 +
* The Zest 1.x ISelfStyleProvider provides a custom styling for a node or an edge. This is now done by creating a custom content part and/or using CSS to style the node/edge.
  
Instead of ''org.eclipse.zest.layouts.Filter'' use ''org.eclipse.zest.core.widgets.LayoutFilter'' (see example below and full code in [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples/src/org/eclipse/gef4/zest/examples/swt/GraphSnippet8.java GraphSnippet8.java] in the examples bundle).
+
You can find examples on how to use the different providers in the GEF4 Git repository:
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceColorsExample.java JFaceColorsExample]
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceFontsExample.java JFaceFontsExample]
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceTooltipExample.java JFaceTooltipExample]
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceEdgeDecorationExample.java JFaceEdgeDecorationExample]
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceEdgeRouterExample.java JFaceEdgeRouterExample]
 +
* [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples.ui/src/org/eclipse/gef4/zest/examples/ui/JFaceNestingExample.java JFaceNestingExample]
  
LayoutFilter filter = new LayoutFilter() {
+
==== Migration example: Colors, sizes, borders, styles ====
  public boolean isObjectFiltered(GraphItem item) {
+
    if (item instanceof GraphConnection) {
+
      GraphConnection connection = (GraphConnection) item;
+
      Object data = connection.getData();
+
      if (data != null && data instanceof Boolean) {
+
        return ((Boolean) data).booleanValue();
+
      }
+
      return true;
+
    }
+
    return false;
+
  }
+
};
+
  
=== Connection Style Providers ===
+
==== Migration example: Zooming ====
  
The ''IConnectionStyleProvider'' and ''IEntityConnectionStyleProvider'' interfaces now contain ''getRouter'' methods returning an ''org.eclipse.draw2d.ConnectionRouter''. Return ''null'' for the default router. See [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.examples/src/org/eclipse/gef4/zest/examples/jface/ManhattanLayoutJFaceSnippet.java ManhattanLayoutJFaceSnippet.java] in the examples bundle.
+
==== Migration example: Custom visualization ====
+
= Zest 1.x =
+
  
Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found in the [[GEF/Reference_Documentation|GEF Reference Documentation]].
 
 
[[Category: GEF]]
 
[[Category: GEF]]

Revision as of 11:44, 27 March 2015

Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in the original wiki page.

Introduction

GEF4 Zest is a graph visualization component that can be used to visualize GEF4 Graph-based graph models, applying automatic layout as provided by GEF4 Layout. It uses JavaFX and GEF4 FX for visualization purposes and is internally based on GEF4 MVC.

GEF4 Zest: ZestGraphExample

MVC

The GEF4 MVC component is used as the framework for the viewer.

The ContentParts are implemented for the GEF4 Graph data model:

  • GraphContentPart
  • NodeContentPart
  • EdgeContentPart

Visualization Properties

The visualization is based on the attributes that are associated with graphs, nodes, or edges. The following attributes are supported:

  • For graphs: type, layout.
  • For nodes/edges: css-class, css-id, label, layout-irrelevant.
  • For nodes: node-rect-css-style, node-label-css-style, icon, tooltip, fisheye, hidden.
  • For edges: edge-curve-css-style, edge-label-css-style, edge-router, style.

Layout Integration

The GEF4 Layout interfaces are adopted to the GEF4 Graph data model. The layout objects are constructed from a given Graph object.

Properties

The layout objects support a general property mechanism to exchange layout information. GEF4 Zest transfers visualization attributes (locations and sizes) to layout properties and vice versa.

LayoutModel

The LayoutContext for a graph is stored in the LayoutModel that is associated with the corresponding GraphContentPart.

Eclipse Integration

GEF4 Zest provides an Eclipse ViewPart (o.e.g4.zest.fx.ui.parts.ZestFxUiView) for visualizing graph models, so that you can integrate it into the Eclipse workbench.

Migration from Zest 1.x to GEF4 Zest

GEF4 Zest was mostly written from scratch, replacing the Zest 1.x API as well as the provisional Zest 2.x API ( Zest 2.0 Layout API) that was developed as an intermediate step.

The Zest 1.x API consists of two parts: 1) a core API for the visualization of graphs, and 2) an on-top JFace API with specific content and label providers and a viewer dedicated to displaying Zest graphs. The former has been replaced by GEF4 Zest.FX and the latter by GEF4 Zest.FX.UI.

Migration from Zest 1.x Core to GEF4 Zest.FX

In comparison to the Zest 1.x Core API, which is based on SWT/Draw2d visualization-wise, and interweaves graph data, layout data, and visuals, the new GEF4 Zest API, on the other hand, is based on GEF4 MVC and maintains distinct object hierarchies for the graph data (content model), the layout data (layout model), and the visuals. This decouples the code, which is one of the design goals of GEF4 in general. As a result, you cannot directly affect the visualization as in Zest 1.x Core, but instead modify the underlying graph model which will effect a content synchronization, i.e. update the visualization based on the content changes. Therefore, to transition from Zest 1.x Core to GEF4 Zest.FX, you have to create/modify a GEF4 Graph where previously Zest 1.x Graph, GraphNode, and GraphConnection were created/modified.

Since GEF4 Zest is based on GEF4 MVC, you should be familiar with the mechanisms and concepts of GEF4 MVC, which are employed as follows:

  • A ContentModel stores the Graph that is currently rendered.
  • A ContentPartFactory constructs controller objects (content parts) for graphs, nodes, and edges. These are responsible for the visualization, content synchronization, and layout integration.
  • All content parts support an adapter mechanism where you can set/query adapters for distinct keys. Functionality can be added to a content part by setting a corresponding adapter on it. For example, you can enable different interactions (moving nodes via drag, etc.) by setting the corresponding policies as adapters on the content parts.
  • A Module defines (Guice) bindings for the context of an application. Using this mechanism, you can specify which adapters should be set on the different content parts. For example, the adapter mechanism is used to integrate GEF4 Layout into GEF4 Zest.

The GEF4 Git repository contains an example on how to use the new API. The example is very simple as the rendered graph is not modified later on. However, it contains everything that is needed for a fully functional example. As you can see when taking a look into the source code, attributes are set on the graph model to specify certain visualization features such as label, tooltip, CSS id, etc.. Actually, the whole visualization results from those attributes. You can find a list of all available attributes GEF/GEF4/Zest#Attributes here.

Some specific Zest 1.x Core functionalities are implemented differently within GEF4 Zest.FX. The corresponding use case scenerios are as follows.

Custom node/edge visualization

As the content parts are responsible for the visualization, you have to create a custom content part in order to exchange the visualization of certain graph elements. GEF4 Zest.FX uses a ContentPartFactory to create content parts for graph elements. Therefore, you have to exchange the ContentPartFactory to be able to create custom content parts. The ZestFxModule contains a binding for the ContentPartFactory, i.e. you have to override the corresponding ContentPartFactory#bindIContentPartFactory() method in your module to bind a CustomContentPartFactory instead. Within the CustomContentPartFactory, you can construct custom content parts, for example, for graph elements with specific attributes.

The GEF4 Git repository contains an example of this scenario. However, note that colors, fonts, borders, and sizes can be configured via JavaFX CSS and do not need a custom visualization.

Modifying graphs

Since you cannot modify the visualization directly, you have to adjust the underlying graph model instead. The visualization is then updated automatically. The GEF4 Git repository contains an example of this scenario.

Layout filter

Migration from Zest 1.x JFace to GEF4 Zest.FX.UI

GEF4 Zest.FX.UI consists of a ZestContentViewer and five zest-specific content and label providers. In comparison to the Zest 1.x JFace API, the ZestContentViewer is not a StructuredViewer anymore, but just a ContentViewer. Zooming is part of the Zest 1.x GraphViewer, but this is already covered within GEF4 MVC.FX. Moreover, the functionality of some of the Zest 1.x JFace providers is covered by standard JFace providers, and is therefore replaced by them:

  • The old IEntityStyleProvider provides tooltip, fisheye, border, and color information. These are now provided via standard JFace IToolTipProvider, JFace IColorProvider, and GEF4 IGraphNodeLabelProvider (which provides arbitrary attributes for nodes, edges, and graphs). Additionally, the JFace IFontProvider is supported, which provides a Font for a node.
  • The old IConnectionStyleProvider (and IEntityConnectionStyleProvider) provide style, color, tooltip, connection router, and connection decorator. These are now provided via GEF4 IEdgeDecorationProvider and GEF4 IGraphNodeLabelProvider, except for the tooltip, which is currently not supported for edges within GEF4 Zest.FX.

Probably, the biggest difference between the Zest 1.x JFace API and GEF4 Zest.FX.UI are the content providers. Zest.FX.UI defines two content providers:

  • The IGraphNodeContentProvider provides all content elements that represent nodes for a flat graph. The edges are inferred via a #getConnectedTo(Object) method. This is the equivalent of the Zest 1.x IGraphEntityContentProvider.
  • The INestedGraphContentProvider extends the IGraphNodeContentProvider by two methods to provide nested graphs. This is the equivalence of the Zest 1.x INestedContentProvider.

So, both new content providers are node-oriented, i.e. they provide content elements which represent nodes, not edges. The Zest 1.x API additionally defines an IGraphEntityRelationshipContentProvider which provides content elements that represent edges, which is not covered by Zest.FX.UI.

Besides, the following providers have not been migrated, because their corresponding functionality is implemented by means of another mechanism:

  • The Zest 1.x IFigureProvider provides a custom visualization for a node. This is now done by creating a different content part for nodes with a custom visualization, as can be seen in this example.
  • The Zest 1.x ISelfStyleProvider provides a custom styling for a node or an edge. This is now done by creating a custom content part and/or using CSS to style the node/edge.

You can find examples on how to use the different providers in the GEF4 Git repository:

Migration example: Colors, sizes, borders, styles

Migration example: Zooming

Migration example: Custom visualization

Back to the top