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
(Zest.FX.UI)
(ZestProperties)
 
(147 intermediate revisions by 3 users not shown)
Line 4: Line 4:
  
 
== Introduction ==
 
== Introduction ==
The <span style="color:#206FAD">[[GEF/GEF4/Zest|GEF4 Zest]]</span> component provides support for visualizing [[GEF/GEF4/Graph|GEF4 Graph]]-based graph models, applying automatic layout as provided by [[GEF/GEF4/Layout|GEF4 Layout]]. It is internally decomposed into the [[#Zest.FX|Zest.FX]] and [[#Zest.FX.UI|Zest.FX.UI]] modules. In addition, there is a deployed [[GEF/GEF4/Zest/Examples#Graph Example (Standalone, Eclipse UI)|Zest Graph Example]] as well as some undeployed [[GEF/GEF4/Zest/Examples#Examples.UI (undeployed)|Zest UI Examples]].
+
The <span style="color:#206FAD">[[GEF/GEF4/Zest|GEF4 Zest]]</span> component provides support for visualizing [[GEF/GEF4/Graph|GEF4 Graph]]-based graph models, applying automatic layout as provided by [[GEF/GEF4/Layout|GEF4 Layout]]. It is internally decomposed into the [[#Zest.FX|Zest.FX]], [[#Zest.FX.JFace|Zest.FX.JFace]], and [[#Zest.FX.UI|Zest.FX.UI]] modules. In addition, there is a deployed [[GEF/GEF4/Zest/Examples#Graph Example (Standalone, Eclipse UI)|Zest Graph Example]] as well as some undeployed [[GEF/GEF4/Zest/Examples#Examples (undeployed)|<span style="color:#206FAD">Zest Examples</span>]] and [[GEF/GEF4/Zest/Examples#Examples.JFace (undeployed)|Zest JFace Examples]].
  
 
[[Image:GEF4-Components-Zest.png|600px]]
 
[[Image:GEF4-Components-Zest.png|600px]]
Line 13: Line 13:
 
*'''bundle: org.eclipse.gef4.zest.fx'''
 
*'''bundle: org.eclipse.gef4.zest.fx'''
  
The [[#Zest.FX|Zest.FX]] module of [[GEF/GEF4/Zest|GEF4 Zest]] provides a graph viewer and implements all functionality therefore. It uses JavaFX and [[GEF/GEF4/FX|GEF4 FX]] for visualization purposes and is internally based on [[GEF/GEF4/MVC|GEF4 MVC]], can thus also be used standalone. Integrating with the Eclipse UI is realized by the [[#Zest.FX.UI|Zest.FX.UI]] module.
+
The [[#Zest.FX|Zest.FX]] module of [[GEF/GEF4/Zest|GEF4 Zest]] provides a graph viewer and implements all functionality therefore. It uses JavaFX and [[GEF/GEF4/FX|GEF4 FX]] for visualization purposes and is internally based on [[GEF/GEF4/MVC|GEF4 MVC]], and can thus also be used standalone. Integrating with the Eclipse UI is realized by the [[#Zest.FX.UI|Zest.FX.UI]] module.
  
<div id="Zest.FX:Root"></div>
+
Being based on [[GEF/GEF4/MVC|GEF4 MVC]], the [[#Zest.FX|Zest.FX]] module specifies a content model and provides a related controller hierarchy and corresponding JavaFX-based visualizations. Zest.FX is capable of rendering a graph with nodes, (binary) edges, and related labels. A node can contain a (nested) graph. A node visualization is composed of a shape, an icon, a label, and a compartment for nodes and edges of a nested graph (if any). It may also have an external label that can be freely placed. An edge visualization is composed of a curve and source/target decorations. It may have freely placable source label, target label, (center) label, and external (center) label.
=== {Root} ===
+
*'''package: org.eclipse.gef4.zest.fx'''
+
  
The [[#Zest.FX:Root|{Root}]] package provides a [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module] ([[#ZestFxModule|ZestFxModule]]) with bindings, as well as a utility class to work with the visualization and layout attributes/properties recognized by [[GEF/GEF4/Zest|GEF4 Zest]] ([[#ZestProperties|ZestProperties]]).  
+
The content model is a [[GEF/GEF4/Graph|GEF4 Graph]] model of which specific attributes are recognized and utilized by [[#Zest.FX|Zest.FX]] for visualization and layout purposes. A utility class ([[#ZestProperties|ZestProperties]]) is provided that can be used to access the visualization-related attributes. Similarly, [[GEF/GEF4/Layout|GEF4 Layout]] provides a utility class ([[GEF/GEF4/Layout#LayoutProperties|org.eclipse.gef4.layout.LayoutProperties]]) that can be used to access the layout-related attributes.
  
[[File:GEF4-Zest-FX-root.jpg|798px]]
+
Visualization-related attributes specify the to be visualized contents. The appearance is controlled via JavaFX CSS. For this purpose, CSS classes are assigned to the visuals so that an external stylesheet can be used. Additionally, a CSS class, ID, and style can be specified for a graph content element using dedicated [[#ZestProperties|ZestProperties]].
  
==== ZestFxModule ====
+
[[#Zest.FX|Zest.FX]] provides content part implementations for the individual graph abstractions, i.e. [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|GraphPart]], [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]], and [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgePart]]. Additionally, [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodeLabelPart]] and [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgeLabelPart]] are provided as controllers for external node/edge labels. The label parts are anchored to their respective controllers.
The <code>ZestFxModule</code> defines various (default) bindings, concerning parts, policies, etc. needed to realize the graph visualization.
+
  
==== ZestProperties ====
+
In order to implement automatic layout, every content part is accompanied by an [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|AbstractLayoutBehavior]] implementation that is responsible for transferring visualization-related attributes to layout-related attributes (and vice versa) within the content [[GEF/GEF4/Graph|GEF4 Graph]] model: [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|GraphLayoutBehavior]], [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|NodeLayoutBehavior]], and [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|EdgeLayoutBehavior]].
<code>ZestProperties</code> defines attributes that are associated to graphs, nodes, and edges (of [[GEF/GEF4/Graph|GEF4 Graph]]), to control the visualization as well as the layout.
+
  
The '''visualization''' is based on the following attributes that are associated with graphs, nodes, or edges:
+
Furthermore, [[#Zest.FX|Zest.FX]] provides a [[#HidingModel|HidingModel]] that maintains a set of currently hidden nodes. The hidden nodes are neither shown, nor taken into account when performing automatic layout. [[#AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior|AbstractHidingBehavior]] implementations are used to hide/show nodes in response to [[#HidingModel|HidingModel]] changes. The behaviors also generate [[#HiddenNeighborsFeedbackPart|HiddenNeighborsFeedbackParts]] that indicate the number of hidden neighbor nodes. Per default, the user can hide/show nodes using dedicated [[#HideHoverHandlePart, ShowHiddenNeighborsHoverHandlePart, ZestFxHoverHandlePartFactory|hover handles]], or [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|interaction policies]].
  
The following attributes are evaluated for graphs:
+
In order to navigate nested/nesting graphs, interaction policies are registered that open a nested/parent graph on double-click ([[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|OpenNestedGraphOnDoubleClickPolicy]], [[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|OpenParentGraphOnDoubleClickPolicy]]), and a [[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|SemanticZoomPolicy]] is registered that carries out zooming and scrolling interactions, so that the user can zoom into and out of (nested) graphs. The viewport of a previously opened graph is stored in the [[#NavigationModel|NavigationModel]] and restored when that graph is opened again.
* "type": Stores a String specifying whether the graph is "directed" or "undirected". In a directed graph, every edge represents a unidirectional connection between its source and target nodes, whereas in an undirected graph, every edge represents a bidirectional connection between its source and target nodes.
+
  
The following attributes are evaluated for nodes and edges (referred to as elements):
+
Besides, a [[#TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy|TranslateSelectedAndRelocateLabelsOnDragPolicy]] is registered so that nodes and labels can be relocated via mouse drag interaction.
* "css-class": Stores the CSS class (String) that is assigned to this element.
+
* "css-id": Stores the CSS id (String) that is assigned to this element.
+
* "label": Stores the label (String) for this element.
+
  
The following attributes are evaluated for nodes:
+
<div id="Zest.FX:Root"></div>
* "node-rect-css-style": Stores the CSS style (String) that is assigned to the JavaFX Rectangle which displays the border and background of this node.
+
=== {Root} ===
* "node-label-css-style": Stores the CSS style (String) that is assigned to the JavaFX Text which displays the label of this node.
+
*'''package: org.eclipse.gef4.zest.fx'''
* "icon": JavaFX Image which is displayed next to the node's label.
+
* "tooltip": Text (String) which is shown as a tooltip, i.e. when the mouse hover the node and does not move for a short time.
+
* "fisheye": If set to True (Boolean), the node's visualization is reduced to a minimum and only expands when the mouse is over the node.
+
  
The following attributes are evaluated for edges:
+
The [[#Zest.FX:Root|{Root}]] package provides a [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module] ([[#ZestFxModule|ZestFxModule]]) with bindings, as well as a utility class ([[#ZestProperties|ZestProperties]]) to work with the visualization and layout attributes/properties recognized by [[GEF/GEF4/Zest|GEF4 Zest]].  
* "edge-curve-css-style": Stores the CSS style (String) that is assigned to the FXGeometryNode<ICurve> ([[GEF/GEF4/FX|GEF4 FX]]) which displays this edge.
+
* "edge-label-css-style": Stores the CSS style (String) that is assigned to the JavaFX Text which displays the label of this edge.
+
* "edge-router": Stores an IFXConnectionRouter ([[GEF/GEF4/FX|GEF4 FX]]) that is used to compute the ICurve ([[GEF/GEF4/Geometry|GEF4 Geometry]]) which is used as the basis for the visualization of this edge.
+
* "style": Stores a String specifying the dash pattern of the edge, which can be "solid", "dashed", "dotted", "dashdot", or "dashdotdot".
+
  
The '''layout''' is based on the following attributes that are associated with graphs, nodes, or edges:
+
[[File:GEF4-Zest-FX-root.jpg|527px]]
  
The following attributes are evaluated for graphs:
+
==== ZestFxModule ====
* "layout": Stores the ILayoutAlgorithm (see [[GEF/GEF4/Layout|GEF4 Layout]]) that will be used to layout the nodes and edges of this graph.
+
The <code>ZestFxModule</code> defines various (default) bindings, concerning parts, policies, etc. needed to realize the graph visualization.
 +
 
 +
==== ZestProperties ====
 +
<code>ZestProperties</code> defines attributes that are associated to graphs, nodes, and edges (of [[GEF/GEF4/Graph|GEF4 Graph]]), to control the visualization as well as the layout.
  
The following attributes are evaluated for nodes and edges (referred to as elements):
+
The '''visualization''' is based on the following attribute, which are associated with graphs (g), nodes (n), or edges (e):
* "layout-irrelevant": If set to True (Boolean), this element will not get layed out.
+
* <code>SHAPE__N</code>, [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/Node.html javafx.scene.Node] (n): Stores the node that is used to display the border and background of the node.
 +
* <code>LABEL__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n, e): Stores the label for the element.
 +
* <code>EXTERNAL_LABEL__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n, e): Stores the external label for the element, which can be freely placed.
 +
* <code>ICON__N</code>, [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/image/Image.html javafx.scene.image.Image] (n): The image that is displayed next to the node's label.
 +
* <code>TOOLTIP__N</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n): Text, which is shown as a tooltip, i.e. when the mouse hover the node and does not move for a short time.
 +
* <code>CURVE__E</code>, [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/Node.html javafx.scene.Node] (n): Stores the node that is used to render the stroke of the edge.
 +
* <code>SOURCE_LABEL__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the source label for the edge.
 +
* <code>TARGET_LABEL__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the target label for the edge.
 +
* <code>SOURCE_DECORATION__E</code>, [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/Node.html javafx.scene.Node] (n): Stores the node that is used to render the source decoration of the edge.
 +
* <code>TARGET_DECORATION__E</code>, [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/Node.html javafx.scene.Node] (n): Stores the node that is used to render the target decoration of the edge.
 +
* <code>CSS_CLASS__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n, e): Stores the CSS class that is assigned to the element.
 +
* <code>CSS_ID__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n, e): Stores the CSS id that is assigned to the element.
 +
* <code>SHAPE_CSS_STYLE__N</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n): Stores the CSS style that is assigned to the shape of this node.
 +
* <code>LABEL_CSS_STYLE__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (n, e): Stores the CSS style that is assigned to the [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/text/Text.html javafx.scene.text.Text] which displays the label of the element.
 +
* <code>CURVE_CSS_STYLE__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the CSS style that is assigned to the curve of the edge.
 +
* <code>SOURCE_LABEL_CSS_STYLE__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the CSS style that is assigned to the source label of this edge.
 +
* <code>TARGET_LABEL_CSS_STYLE__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the CSS style that is assigned to the target label of this edge.
 +
* <code>SOURCE_DECORATION_CSS_STYLE__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the CSS style that is assigned to the source decoration of this edge.
 +
* <code>TARGET_DECORATION_CSS_STYLE__E</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/String.html java.lang.String] (e): Stores the CSS style that is assigned to the target decoration of this edge.
 +
* <code>ROUTER__E</code>, [[GEF/GEF4/FX#IConnectionRouter, StraightRouter, OrthogonalRouter|org.eclipse.gef4.fx.nodes.IConnectionRouter]] (e): Stores the router that is used to manipulate the waypoints of the edge
 +
* <code>INTERPOLATOR__E</code>, [[GEF/GEF4/FX#IConnectionInterpolator, PolylineInterpolator, PolyBezierInterpolator|org.eclipse.gef4.fx.nodes.IConnectionInterpolator]] (e): Stores the interpolator that is used to manipulate the appearance of the edge.
 +
* <code>INVISIBLE__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/Boolean.html java.lang.Boolean] (n,e): Stores whether this element is to be visual or not.
  
 +
The '''layout''' is based on the following attributes, which are associated with graphs (g), nodes (n), or edges (e):
 +
* <code>LAYOUT_ALGORITHM__G</code>, [[GEF/GEF4/Layout#ILayoutAlgorithm|org.eclipse.gef4.layout.ILayoutAlgorithm]] (g): Stores the algorithm that will be used to layout the nodes and edges of this graph.
 +
* <code>LAYOUT_IRRELEVANT__NE</code>, [http://docs.oracle.com/javase/7/docs/api/index.html?java/lang/Boolean.html java.lang.Boolean] (n, e): If set to <code>true</code>, this element will not get layed out.
 +
* <code>POSITION__N</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (n) : Stores the position of the node.
 +
* <code>SIZE__N</code>, [[GEF/GEF4/Geometry#Dimension | org.eclipse.gef4.geometry.planar.Dimension]] (n): Stores the size of the node.
 +
* <code>START_POINT__E</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (e): Stores the start point of the edge.
 +
* <code>END_POINT__E</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (e): Stores the end point of the edge.
 +
* <code>CONTROL_POINTS__E</code>, List of [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]]s (e): Stores the control/way-points of the edge.
 +
* <code>LABEL_POSITION__E</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (e): Stores the position of the label of the edge.
 +
* <code>SOURCE_LABEL_POSITION__E</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (e): Stores the position of the source label of the edge.
 +
* <code>TARGET_LABEL_POSITION__E</code>, [[GEF/GEF4/Geometry#Point | org.eclipse.gef4.geometry.planar.Point]] (e): Stores the position of the target label of the edge.
 
----
 
----
  
Line 65: Line 85:
 
*'''package: org.eclipse.gef4.zest.fx.behaviors'''
 
*'''package: org.eclipse.gef4.zest.fx.behaviors'''
  
[[File:GEF4-Zest-FX-behaviors.png|1052px]]
+
The [[#Behaviors|Behaviors]] package contains specific [[GEF/GEF4/MVC#IBehavior, AbstractBehavior|IBehavior]] implementations for exchanging layout information ([[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|AbstractLayoutBehavior]], [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|NodeLayoutBehavior]], [[#AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior|EdgeLayoutBehavior]]) and the hiding/showing of nodes and related edges ([[#AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior|AbstractHidingBehavior]], [[#AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior|NodeHidingBehavior]], [[#AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior|EdgeHidingBehavior]], [[#AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior|EdgeLabelHidingBehavior]]).
  
----
+
[[File:GEF4-Zest-FX-behaviors.png|1213px]]
  
=== Layout ===
+
==== AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior ====
*'''package: org.eclipse.gef4.zest.fx.layout'''
+
The <code>GraphLayoutBehavior</code> maintains a [[GEF/GEF4/Layout#LayoutContext|org.eclipse.gef4.layout.LayoutContext]], i.e. it is responsible for the creation of such a layout context, updating the layout bounds (based on the corresponding [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|GraphPart]]), and initiating layout passes (based on content or bounds changes). It also registers pre- and post-layout-passes at the [[GEF/GEF4/Layout#LayoutContext|org.eclipse.gef4.layout.LayoutContext]], including those of related <code>NodeLayoutBehavior</code>s and <code>EdgeLayoutBehavior</code>s. The <code>NodeLayoutBehavior</code> provides location and size of its corresponding [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]] before a layout pass is applied, and, accordingly, copies the location and size from the [[GEF/GEF4/Layout#LayoutContext|org.eclipse.gef4.layout.LayoutContext]] to its corresponding [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]] afterwards. Afterwards it initiates a refresh of the visualization and updates the external label position, which is ignored by the [[GEF/GEF4/Layout| GEF4 Layout]] algorithms. The <code>EdgeLayoutBehavior</code> does not need to provide layout information, but only refreshes the visualization of its corresponding [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgePart]] after a layout pass, as well updating the positions of external labels. The <code> AbstractLayoutBehavior </code> provides common functionality for all layout related behaviors.
  
[[File:GEF4-Zest-FX-layout.png|686px]]
+
==== AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior ====
 
+
The <code>NodeHidingBehavior</code>, <code>EdgeHidingBehavior</code>, and <code>EdgeLabelHidingBehavior</code> react to changes in the [[#HidingModel|HidingModel]] by hiding/showing the corresponding visuals. In addition, for nodes, a [[#HiddenNeighborsFeedbackPart|HiddenNeighborsFeedbackPart]] is created when any neighboring nodes are currently hidden. The <code>AbstractHidingBehavior</code> provides common functionality for all hiding related behaviors.
==== GraphLayoutContext, GraphNodeLayout, GraphEdgeLayout, GraphSubgraphLayout ====
+
The [[GEF/GEF4/Layout|GEF4 Layout]] interfaces are adopted to the [[GEF/GEF4/Graph|GEF4 Graph]] data model. The layout objects are constructed from a given Graph object. 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. A GraphLayoutContext combines all layout information for one Graph. Therefore, one GraphLayoutContext is maintained per GraphContentPart via the adapter mechanism.
+
 
+
You can access the GraphLayoutContext for a specific Graph as follows:
+
<source lang="java" style="border-style:solid;border-color:#f2f2f2;border-width:1px;padding:10px;margin-bottom:10px">
+
GraphLayoutContext layoutContext = viewer.getContentPartMap().get(graph).getAdapter(LayoutModel.class);
+
</source>
+
  
 
----
 
----
Line 87: Line 100:
 
*'''package: org.eclipse.gef4.zest.fx.models'''
 
*'''package: org.eclipse.gef4.zest.fx.models'''
  
[[File:GEF4-Zest-FX-models.png|605px]]
+
The [[#Models|Models]] package provides viewer models to support hiding of nodes ([[#HidingModel|HidingModel]]) as well as semantic zooming ([[#NavigationModel | NavigationModel]]).
 +
 
 +
[[File:GEF4-Zest-FX-models.png|635px]]
  
 
==== HidingModel ====
 
==== HidingModel ====
A HidingModel stores which nodes are currently hidden. Every visible node shows a small marker indicating how many of its neighbors are hidden. You can hide/show nodes using the hover handles, respectively. The visualization is automatically synchronized with the HidingModel.
+
The <code>HidingModel</code> is a viewer model that stores which nodes are currently hidden. Every visible node shows a small marker indicating how many of its neighbors are hidden. You can hide/show nodes using the hover handles, respectively. The visualization is automatically synchronized with the <code>HidingModel</code>.
 
+
[[Image:GEF4Zest-HidingHoverHandles.png|Hover handles for hide/show]]
+
 
+
==== LayoutModel ====
+
  
==== ViewportStackModel ====
+
==== NavigationModel ====
 +
The <code>NavigationModel</code> is a viewer model needed to persist viewport configurations. It is used to keep track of all viewports that are passed during nested graph navigation when zooming in and can be used to restore viewports when zooming out again.
  
 
----
 
----
Line 103: Line 115:
 
*'''package: org.eclipse.gef4.zest.fx.operations'''
 
*'''package: org.eclipse.gef4.zest.fx.operations'''
  
[[File:GEF4-Zest-FX-operations.png|396px]]
+
The [[#Operations|Operations]] package currently provides operations for the hiding (visible) and showing (invisible) nodes, as well as for navigating and manipulating of attributes.
 +
 
 +
[[File:GEF4-Zest-FX-operations.png|380px]]
 +
 
 +
==== HideOperation, ShowHiddenNeighboursOperation ====
 +
The <code>HideOperation</code> and <code>ShowHiddenNeighboursOperation</code> are used by [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|HidePolicy]] to hide or show nodes. It adds/removes a respective content part to/from the [[#HidingModel|HidingModel]].
 +
 
 +
==== NavigateOperation ====
 +
The <code>NavigateOperation</code> is used by the [[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|SemanticZoomPolicy]] to realize navigation into and out of nested graphs.
 +
 
 +
==== ChangeAttributesOperation ====
 +
The <code>ChangeAttributesOperation</code> is a general operation used to change values of attributes of an [[GEF/GEF4/Common#IAttributeStore|org.eclipse.gef4.common.attributes.IAttributeStore]], i.e for a [[GEF/GEF4/Graph#Graph|Graph]] model element.
  
 
----
 
----
Line 109: Line 132:
 
=== Parts ===
 
=== Parts ===
 
*'''package: org.eclipse.gef4.zest.fx.parts'''
 
*'''package: org.eclipse.gef4.zest.fx.parts'''
 +
 +
The [[#Parts|Parts]] package provides a specific [[GEF/GEF4/MVC#FXRootPart|org.eclipse.gef4.mvc.fx.parts.FXRootPart]] which adds support for CSS styling.
  
 
[[File:GEF4-Zest-FX-parts-root.png|331px]]
 
[[File:GEF4-Zest-FX-parts-root.png|331px]]
  
[[File:GEF4-Zest-FX-parts-contents.png|842px]]
+
It furthermore provides specific [[GEF/GEF4/MVC#AbstractFXContentPart|org.eclipse.gef4.mvc.fx.parts.AbstractFXContentPart]] implementations ([[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|GraphPart]], [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]], [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodeLabelPart]], [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgePart]], and [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgeLabelPart]]) to control the visualizations of graphs, nodes, and edges.
  
[[File:GEF4-Zest-FX-parts-feedback.png|895px]]
+
[[File:GEF4-Zest-FX-parts-contents.png|910px]]
  
[[File:GEF4-Zest-FX-parts-handles.png|832px]]
+
In addition, it provides specific [[GEF/GEF4/MVC#AbstractFXHandlePart, AbstractFXSegmentHandlePart, FXCircleSegmentHandlePart, FXRectangleSegmentHandlePart, FXSquareSegmentHandlePart|org.eclipse.gef4.mvc.fx.parts.AbstractFXHandlePart]] implementations ([[#HideHoverHandlePart, ShowHiddenNeighborsHoverHandlePart, ZestFxHoverHandlePartFactory|HideHoverHandlePart]] and [[#HideHoverHandlePart, ShowHiddenNeighborsHoverHandlePart, ZestFxHoverHandlePartFactory|ShowHiddenNeighborsHoverHandlePart]]) to realize hiding and showing of nodes via hover handles.
  
[[File:GEF4-Zest-FX-parts-providers.png|188px]]
+
[[File:GEF4-Zest-FX-parts-handles.png|964px]]
  
The [[GEF/GEF4/MVC|GEF4 MVC]] component is used as the framework for the viewer. It is extended by implementing content parts for the [[GEF/GEF4/Graph|GEF4 Graph]] data model (GraphContentPart, NodeContentPart, and EdgeContentPart) and binding a separate content part factory for it, integrating the [[GEF/GEF4/Layout|GEF4 Layout]] component ([[GEF/GEF4/Zest#Layout|layout integration]]), and implementing hiding of nodes by providing a HidingModel and corresponding policies and behaviors.
+
There is also specific [[GEF/GEF4/MVC#AbstractFXFeedbackPart, FXHoverFeedbackPart, FXSelectionFeedbackPart, FXSelectionLinkFeedbackPart|AbstractFXFeedbackPart]] implementation ([[#HiddenNeighborsFeedbackPart|HiddenNeighborsFeedbackPart]]) to indicate feedback for hidden nodes.
  
The [[GEF/GEF4/Graph|GEF4 Graph]] data model consists of 3 classes: Graph, Node, and Edge. A Graph serves as a container for Nodes and Edges. Additionally, a Graph can be ''nested'' inside a so called ''nesting'' Node. Moreover, arbitrary attributes can be set on Graphs, Nodes, and Edges, which the visualization is based on ([[GEF/GEF4/Zest#ZestProperties|ZestProperties]]). GEF4 Zest expects a Graph as its input, which is stored in the ContentModel provided by [[GEF/GEF4/MVC|GEF4 MVC]]. A separate content part is created for every Graph, Node, or Edge in the ContentModel and the content parts are automatically synchronized with the ContentModel, i.e. content parts are removed, created, or refreshed according to ContentModel changes. The content parts are utilized for the synchronization and are also responsible for the visualization of their corresponding content objects.
+
[[File:GEF4-Zest-FX-parts-feedback.png|419px]]
  
[[Image:GEF4Zest-visuals.png|GEF4 Zest default visuals]]
+
==== ZestFxRootPart ====
 +
The <code>ZestFxRootPart</code> is a specific [[GEF/GEF4/MVC#FXRootPart|org.eclipse.gef4.mvc.fx.parts.FXRootPart]] that adds support for CSS styling. In detail, it loads a file with default CSS styles (<code>STYLES_CSS_FILE</code>) and applies it as stylesheet to the [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/Scene.html javafx.scene.Scene].
  
The default visualization for nodes consists of a JavaFX Rectangle for background and border, a Text for the label, and an ImageView for the icon. The default visualization for edges consists of an FXGeometryNode<ICurve> for the connection line, and a JavaFX Text for the label.
+
==== GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory ====
 +
The <code>GraphPart</code>, <code>NodePart</code>, and <code>EdgePart</code> implementations control the visualization of the underlying [[GEF/GEF4/Graph|GEF4 Graph]] model elements, i.e. graphs, nodes, and edges. The default visualization for nodes (contributed by <code>NodePart</code>) consists of a shape Node for background and border, a [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/text/Text.html javafx.scene.text.Text] for the label, and an [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/image/ImageView.html javafx.scene.image.ImageView] for the icon. The default visualization for edges (contributed by <code>EdgePart</code> consists of a [[GEF/GEF4/FX#Connection | org.eclipse.gef4.fx.nodes.Connection]], whose curve node can be exchanged. The external labels of nodes and edges are visualized by [http://docs.oracle.com/javafx/2/api/index.html?javafx/scene/text/Text.html javafx.scene.text.Text]s, which are controlled by <code>NodeLabelPart</code> and <code>EdgeLabelPart</code> respectively.
  
<small>Classes within this package will probably be renamed in the future to achieve a better consistency, as outlined in bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=468804 #468804].</small>
+
The <code>NodePart</code> and <code>EdgePart</code> assign the following JavaFX CSS classes to its visuals:
  
==== GraphRootPart ====
+
* <code>"node"</code> is assigned to the visual of the <code>NodePart</code>.
 +
* <code>"shape"</code> is assigned to the shape sub-visual of the <code>NodePart</code>.
 +
* <code>"label"</code> is assigned to the label sub-visual of the <code>NodePart</code>.
 +
* <code>"icon"</code> is assigned to the icon sub-visual of the <code>NodePart</code>.
 +
* <code>"edge"</code> is assigned to the visual of the <code>EdgePart</code>.
 +
* <code>"curve"</code> is assigned to the curve sub-visual of the <code>EdgePart</code>.
 +
* <code>"decoration"</code> is assigned to the decoration sub-visuals of the <code>EdgePart</code>.
  
==== GraphContentPart, NodeContentPart, EdgeContentPart, EdgeLabelPart, ContentPartFactory ====
+
==== HideHoverHandlePart, ShowHiddenNeighborsHoverHandlePart, ZestFxHoverHandlePartFactory ====
 +
The <code> HideHoverHandlePart </code> and <code> ShowHiddenNeighborsHoverHandlePart </code> are complementary [[GEF/GEF4/MVC#AbstractFXHandlePart, AbstractFXSegmentHandlePart, FXCircleSegmentHandlePart, FXRectangleSegmentHandlePart, FXSquareSegmentHandlePart|org.eclipse.gef4.mvc.fx.parts.AbstractFXSegmentHandlePart]] implementations that are used as hover handles. Being anchored on a respective [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]]s, they react to mouse clicks to perform hiding or showing of nodes.
  
==== ZestFxHidingHandlePart, ZestFxExpandingHandlePart, ZestFxHandlePartFactory ====
+
[[Image:GEF4Zest-HidingHoverHandles.png|Hover handles for hide/show]]
  
 +
==== HiddenNeighborsFeedbackPart ====
 +
The <code> HiddenNeighborsFeedbackPart </code> is a specific [[GEF/GEF4/MVC#AbstractFXFeedbackPart, FXHoverFeedbackPart, FXSelectionFeedbackPart, FXSelectionLinkFeedbackPart|org.eclipse.gef4.mvc.fx.parts.AbstractFXFeedbackPart]] that indicates the number of hidden neighbor nodes via a circle decoration (with a number label).
  
==== HiddenNeighborsPart, ZestFxEdgeLinkFeedbackPart, ZestFxFeedbackPartFactory ====
+
[[Image:GEF4Zest-HiddenNeighborsFeedback.png|38px|Feedback for hidden neighbor nodes]]
  
 
+
==== ZestFxSelectionHandlePartFactory ====
==== ZestCursorProvider ====
+
The <code> ZestFxSelectionHandlePartFactory</code> is a specific handle part factory that does prevent creation of multi selection handles.
  
 
----
 
----
Line 147: Line 183:
 
*'''package: org.eclipse.gef4.zest.fx.policies'''
 
*'''package: org.eclipse.gef4.zest.fx.policies'''
  
[[File:GEF4-Zest-FX-policies.png|747px]]
+
The [[#Policies|Policies]] package contains specific [[GEF/GEF4/MVC#IPolicy, AbstractPolicy|IPolicy]] implementations for hiding/showing of nodes ([[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|HideNodePolicy]], [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|HideOnTypePolicy]], [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|ShowHiddenNeighborsOnTypePolicy]], [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy|HideFirstAnchorageOnClickPolicy]], and [[#HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy| ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy]]), dragging external labels ([[#TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy|TransformLabelPolicy]], [[#TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy| TranslateSelectedAndRelocateLabelsOnDragPolicy]]), and navigating nested graphs via double click ([[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy| SemanticZoomPolicy]], [[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|OpenNestedGraphOnDoubleClickPolicy]], [[#SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy|OpenParentGraphOnDoubleClickPolicy]]).
 +
 
 +
[[File:GEF4-Zest-FX-policies.png|682px]]
 +
 
 +
==== HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy ====
 +
The <code> HidePolicy </code> and <code> ShowHiddenNeighborsPolicy</code> are transaction policies that are registered as an adapter on [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodeParts]]. They are used by the <code> HideOnTypePolicy</code>, <code> ShowHiddenNeighborsOnTypePolicy</code>, <code> HideFirstAnchorageOnClickPolicy</code>, and <code> ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy</code> interaction policies to realize the hiding and showing of nodes.
 +
 
 +
==== TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy ====
 +
The <code> TranslateSelectedAndRelocateLabelsOnDragPolicy </code> is a specific [[GEF/GEF4/MVC#IFXOnDragPolicy|IFXOnDragPolicy]] that enables the positioning of node and edge labels (i.e. [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodeLabelPart]] and [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|EdgeLabelPart]]) during mouse drag. It uses the underlying <code>TransformLabelPolicy</code> to realize the translate operation.
 +
 
 +
==== SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy ====
 +
The <code>OpenNestedGraphOnDoubleClickPolicy</code> and <code>OpenParentGraphOnDoubleClickPolicy</code> policies implement nested graph navigation via double clicking with the mouse. They both rely on the underlying <code>SemanticZoomPolicy</code>, which manipulates the [[#NavigationModel|NavigationModel]] via a [[#NavigateOperation| NavigateOperation]]. The graph of the node where the current graph is nested is opened when the user double clicks in the background (i.e. in a [[#ZestFxRootPart|ZestFxRootPart]]), and the nested graph is opened when the user double clicks in a [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]] that contains a nested graph.
  
 
----
 
----
  
== Zest.FX.UI ==
+
<div id="Zest.FX:Providers"></div>
  
*'''feature: org.eclipse.gef4.zest.fx.ui'''
+
=== Providers ===
*'''bundle: org.eclipse.gef4.zest.fx.ui'''
+
*'''package: org.eclipse.gef4.zest.fx.providers'''
  
The [[#Zest.FX.UI|Zest.FX.UI]] module of [[GEF/GEF4/Zest|GEF4 Zest]] contains Eclipse Workbench UI related graph visualization support. This includes a [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module]] ([[#ZestFxUiModule|ZestFxUiModule]]), which augments the bindings of [[#ZestFxModule|ZestFxModule]] to realize the Eclipse Workbench UI integration, an Eclipse view ([[#ZestFxUiView|ZestFxUiView]] to render graphs based on [[#Zest.FX|Zest.FX]], as well as a [[#JFace|JFace-based API]] to populate a Zest viewer (i.e. an [[GEF/GEF4/MVC#FXViewer|FXViewer]] with bindings defined in [[#ZestFxModule|ZestFxModule]].  
+
The [[#Providers| Providers]] package contains a specific anchor provider for [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]]s.
 +
 
 +
[[File:GEF4-Zest-FX-providers.png|371px]]
 +
 
 +
==== NodePartAnchorProvider ====
 +
The <code>NodePartAnchorProvider</code> is a specific [[GEF/GEF4/MVC#DefaultAnchorProvider|org.eclipse.gef4.mvc.fx.providers.DefaultAnchorProvider]] that uses the [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|NodePart]]'s shape outline.
  
 
----
 
----
  
<div id="Zest.FX.UI:Root"></div>
+
== Zest.FX.JFace ==
=== {Root} ===  
+
  
*'''package: org.eclipse.gef4.zest.fx.ui'''
+
*'''feature: org.eclipse.gef4.zest.fx.jface'''
 +
*'''bundle: org.eclipse.gef4.zest.fx.jface'''
  
[[File:GEF4-Zest-FX-UI-root.png|110px]]
+
The [[#Zest.FX.JFace|Zest.FX.JFace]] module of [[GEF/GEF4/Zest|GEF4 Zest]] provides a JFace-based API to populate a Zest viewer (i.e. an [[GEF/GEF4/MVC#FXViewer|FXViewer]]).
  
==== ZestFxUiModule ====
 
The <code>ZestFxUiModule</code> 
 
 
 
----
 
----
  
=== JFace ===
+
<div id="Zest.FX.JFace:Root"></div>
 +
=== {Root} ===  
  
*'''package: org.eclipse.gef4.zest.fx.ui.jface'''
+
*'''package: org.eclipse.gef4.zest.fx.jface'''
  
[[File:GEF4-Zest-FX-UI-jface.png|1032px]]
+
The [[#Zest.FX.JFace:Root|Root]] package provides a specific [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ContentViewer.html org.eclipse.jface.viewers.ContentViewer]  ([[#ZestContentViewer|ZestContentViewer]]), related content ([[#IGraphContentProvider|IGraphContentProvider]], and attribute ([[#IGraphAttributesProvider|IGraphAttributesProvider]]) providers.
  
<small>As outlined in bug [https://bugs.eclipse.org/bugs/show_bug.cgi?id=469330 #469330] this API will be adjusted in the future.</small>
+
[[File:GEF4-Zest-FX-JFace-root.png|671px]]
  
 
==== ZestContentViewer ====
 
==== ZestContentViewer ====
 
A <code>ZestContentViewer</code> is a specific [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ContentViewer.html org.eclipse.jface.viewers.ContentViewer] that renders an input model as a directed graph, using [[#Zest.FX|Zest.FX]].  
 
A <code>ZestContentViewer</code> is a specific [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ContentViewer.html org.eclipse.jface.viewers.ContentViewer] that renders an input model as a directed graph, using [[#Zest.FX|Zest.FX]].  
  
The to be rendered graph is inferred from the input model by means of a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IContentProvider.html org.eclipse.jface.viewers.IContentProvider]. In the context of a <code>ZestContentViewer</code>, the content provider has to implement [[#IGraphNodeContentProvider|IGraphNodeContentProvider]] or [[#INestedGraphContentProvider|INestedGraphContentProvider]] (if the graph is not flat but contains nested graphs). The content provider is node-based, i.e. edges are not represented as first level entities, but are only inferred from input objects via <code>getConnectedTo(Object)</code>.
+
The to be rendered graph is inferred from the input model by means of a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IContentProvider.html org.eclipse.jface.viewers.IContentProvider]. In the context of a <code>ZestContentViewer</code>, the content provider has to implement [[#IGraphContentProvider|IGraphContentProvider]]. The content provider is node-based, i.e. edges are not represented as first level entities, but are only inferred from input objects via <code>getAdjacentNodes(Object)</code>.
  
 
The visualization of the graph (i.e. of its nodes and edges) can be controlled via a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider]. The <code>getText(Object)</code> and <code>getImage(Object)</code> of the label provider will be used to infer labels and icons for nodes. In case the label provider implements [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IColorProvider.html org.eclipse.jface.viewers.IColorProvider], its <code>getForeground(Object)</code> will be used to infer the color of the node outline and its label, and <code>getBackground(Object)</code> will be used as the node's fill color. In case the label provider implements [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IFontProvider.html org.eclipse.jface.viewers.IFontProvider], <code>getFont(Object)</code> will be used to infer the name, size, and style (bold or italic) of the font, used by the node label. The label provider may furthermore implement [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IToolTipProvider.html org.eclipse.jface.viewers.IToolTipProvider] in case a tooltip should be shown on hovering the node.  
 
The visualization of the graph (i.e. of its nodes and edges) can be controlled via a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider]. The <code>getText(Object)</code> and <code>getImage(Object)</code> of the label provider will be used to infer labels and icons for nodes. In case the label provider implements [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IColorProvider.html org.eclipse.jface.viewers.IColorProvider], its <code>getForeground(Object)</code> will be used to infer the color of the node outline and its label, and <code>getBackground(Object)</code> will be used as the node's fill color. In case the label provider implements [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IFontProvider.html org.eclipse.jface.viewers.IFontProvider], <code>getFont(Object)</code> will be used to infer the name, size, and style (bold or italic) of the font, used by the node label. The label provider may furthermore implement [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IToolTipProvider.html org.eclipse.jface.viewers.IToolTipProvider] in case a tooltip should be shown on hovering the node.  
  
Further, the label provider may implement [[#IEdgeDecorationProvider|IEdgeDecorationProvider]] to provide visual source and target decorations for edges.
+
Further, the label provider may implement [[#IGraphAttributesProvider| IGraphAttributesProvider]], which allows to provide values for all specified [[#ZestProperties|ZestProperties]] for graphs, nodes and edges, via which the visualization can be controlled even more fine-grained. It will overwrite the values returned via the standard label and dedicated provider methods. For edges, this can for instance be used to provide label texts (using the ''label'', ''external-label'', ''source-label'', or ''target-label'' attribute).
  
If the label provider in addition implements [[#IGraphNodeLabelProvider, INestedGraphLabelProvider|IGraphNodeLabelProvider]] or [[#IGraphNodeLabelProvider, INestedGraphLabelProvider|INestedGraphLabelProvider]], it can provide [[#ZestProperties|ZestProperties]] for graphs, nodes and edges, via which the visualization can be controlled even more fine-grained. It will overwrite the values returned via the standard label and dedicated provider methods. For edges, this is currently the only way to provide a label text (using the ''label'' attribute).
+
==== IGraphContentProvider ====
 +
The <code>IGraphContentProvider</code> is responsible of returning those input elements (<code>getNodes()</code>) that are to be visualized as nodes, and to provide information about which nodes are connected via edges to other nodes. The <code>IGraphContentProvider</code> is node-based, i.e. the to be visualized edges are only represented implicitly, by providing the connection target nodes of a node via <code>getAdjacentNodes(Object)</code>, and are not explicitly mapped to underlying input elements. It further provides information about nested graphs via <code>getNestedGraphNodes(Object)</code>.
  
==== IGraphNodeContentProvider ====
+
==== IGraphAttributesProvider ====
The <code>IGraphNodeContentProvider</code> is responsible of returning those input elements (<code>getNodes()</code>) that are to be visualized as nodes, and to provide information about which nodes are connected via edges to other nodes. The <code>IGraphNodeContentProvider</code> is node-based, i.e. the to be visualized edges are only represented implicitly, by providing the connection target nodes of a node via <code>getConnectedTo(Object)</code>, and are not explicitly mapped to underlying input elements.
+
The <code> IGraphAttributesProvider </code>can be implemented by a label provider to return attributes, i.e. [[#ZestProperties|ZestProperties]] for a root graph, as well as for nodes and edges.
  
==== INestedGraphContentProvider ====
+
----
The <code> INestedGraphContentProvider </code> is responsible of returning the nested nodes of a given node (<code>getChildren(Object)</code>. It extends the [[#IGraphNodeContentProvider|IGraphNodeContentProvider]], so that edges can also be inferred between nested nodes, i.e. those being returned as children.
+
  
==== IGraphNodeLabelProvider, INestedGraphLabelProvider ====
+
== Zest.FX.UI ==
The <code>IGraphNodeLabelProvider</code>, in addition to the standard label provider functionality, is responsible of returning attributes, i.e. [[#ZestProperties|ZestProperties]] for a root graph, as well as for nodes and edges. The <code>INestedGraphLabelProvider</code> in addition returns those attributes for nested graphs.
+
  
==== IEdgeDecorationProvider ====
+
*'''feature: org.eclipse.gef4.zest.fx.ui'''
The <code>IEdgeDecorationProvider</code> is responsible of returning source and target decorations ([[GEF/GEF4/FX#FXConnection, IFXDecoration, IFXConnectionRouter, FXPolyBezierConnectionRouter, FXPolylineConnectionRouter|org.eclipse.gef4.fx.nodes.IFXDecoration]]) for an inferred edge, which is identified via a source and target input object.
+
*'''bundle: org.eclipse.gef4.zest.fx.ui'''
 +
 
 +
The [[#Zest.FX.UI|Zest.FX.UI]] module of [[GEF/GEF4/Zest|GEF4 Zest]] contains Eclipse Workbench UI related graph visualization support. This includes a [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module]] ([[#ZestFxUiModule|ZestFxUiModule]]), which augments the bindings of [[#ZestFxModule|ZestFxModule]] to realize the Eclipse Workbench UI integration and an Eclipse view ([[#ZestFxUiView|ZestFxUiView]]) to render graphs based on [[#Zest.FX|Zest.FX]].
  
 
----
 
----
 +
 +
<div id="Zest.FX.UI:Root"></div>
 +
=== {Root} ===
 +
 +
*'''package: org.eclipse.gef4.zest.fx.ui'''
 +
 +
The [[#Zest.FX.UI:Root|{Root}]] package provides a [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module] ([[#ZestFxUiModule|ZestFxUiModule]]) with bindings related to the Eclipse UI Workbench integration of [[#Zest.FX|Zest.FX]].
 +
 +
[[File:GEF4-Zest-FX-UI-root.png|110px]]
 +
 +
==== ZestFxUiModule ====
 +
The <code>ZestFxUiModule</code> extends [[GEF/GEF4/MVC#MvcUiModule|org.eclipse.gef4.mvc.ui.MvcUiModule]] and thus delivers specific bindings related to the integration of [[#Zest.FX|Zest.FX]] with the Eclipse Workbench UI.
  
 
<div id="Zest.FX.UI:Parts"></div>
 
<div id="Zest.FX.UI:Parts"></div>
Line 211: Line 274:
 
*'''package: org.eclipse.gef4.zest.fx.ui.parts'''
 
*'''package: org.eclipse.gef4.zest.fx.ui.parts'''
  
The [[#Zest.FX.UI:Parts|Parts]] package provides an Eclipse ViewPart ([[#ZestFxUiView|ZestFxUiView]]) for visualizing graph models, so that you can integrate it into the Eclipse workbench.
+
The [[#Zest.FX.UI:Parts|Parts]] package provides an Eclipse [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/ui/part/ViewPart.html org.eclipse.ui.part.ViewPart] ([[#ZestFxUiView|ZestFxUiView]]) for visualizing graph models.
  
 
[[File:GEF4-Zest-FX-UI-parts.png|177px]]
 
[[File:GEF4-Zest-FX-UI-parts.png|177px]]
Line 217: Line 280:
 
==== ZestFxUiView ====
 
==== ZestFxUiView ====
  
<code>ZestFxUiView</code> is a specific [[GEF/GEF4/MVC#FXView|FXView]] that can render graphs. It uses the bindings provided by [[#ZestFxUiModule|ZestFxUiModule]].
+
<code>ZestFxUiView</code> is a specific [[GEF/GEF4/MVC#FXView|FXView]] that can render graphs. It uses the bindings provided by [[#ZestFxModule|ZestFxModule]] and [[#ZestFxUiModule|ZestFxUiModule]].  
  
[[Image:GEF4Zest.FX.UI-GraphExample.png|600px|GEF4 Zest in Eclipse]]
 
 
----
 
----
  
Line 226: Line 288:
 
[[GEF/GEF4/Zest|GEF4 Zest]] was mostly written from scratch, replacing the [https://www.eclipse.org/gef/zest/index.php 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.
 
[[GEF/GEF4/Zest|GEF4 Zest]] was mostly written from scratch, replacing the [https://www.eclipse.org/gef/zest/index.php 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:  
+
The [https://www.eclipse.org/gef/zest/index.php Zest 1.x] API consists of two parts:  
# a core API for the visualization of graphs, and
+
# a Core API for the visualization of graphs, and
 
# a JFace API with specific content and label providers and a viewer dedicated to displaying Zest graphs.  
 
# a JFace API with specific content and label providers and a viewer dedicated to displaying Zest graphs.  
The former has been replaced by GEF4 [[GEF/GEF4/Zest#Zest.FX|Zest.FX]] and the latter by [[GEF/GEF4/Zest#Zest.FX.UI|Zest.FX.UI]].
+
The former has been replaced by [[GEF/GEF4/Zest#Zest.FX|Zest.FX]] and the latter by [[GEF/GEF4/Zest#Zest.FX.UI|Zest.FX.UI]].
  
 
----
 
----
Line 235: Line 297:
 
=== Migration from Zest 1.x Core to GEF4 Zest.FX ===
 
=== Migration from Zest 1.x Core to GEF4 Zest.FX ===
  
In comparison to the [https://www.eclipse.org/gef/zest/index.php Zest 1.x] Core API, which is based on SWT/Draw2d visualization and interweaves graph data, layout data, and visuals, [[#Zest.FX|Zest.FX]] 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. As a result, in order to perform structural changes to the visualized graph, you cannot directly affect the visualization as in [https://www.eclipse.org/gef/zest/index.php 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 [https://www.eclipse.org/gef/zest/index.php Zest 1.x] Core to [[#Zest.FX|Zest.FX]], you have to create/modify a [[GEF/GEF4/Graph|GEF4 Graph]] where previously [https://www.eclipse.org/gef/zest/index.php Zest 1.x] Graph, GraphNode, and GraphConnection were created/modified.
+
In comparison to the [https://www.eclipse.org/gef/zest/index.php Zest 1.x] Core API, which is based on SWT/Draw2d visualization and interweaves graph data, layout data, and visuals, [[#Zest.FX|Zest.FX]] 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. As a result, in order to perform structural changes to the visualized graph, you cannot directly affect the visualization as in [https://www.eclipse.org/gef/zest/index.php 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 [https://www.eclipse.org/gef/zest/index.php Zest 1.x] Core to [[#Zest.FX|Zest.FX]], you have to create/modify a [[GEF/GEF4/Graph#Graph, Node, Edge|org.eclipse.gef4.graph.Graph]] where previously [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/widgets/Graph.html org.eclipse.zest.core.widgets.Graph], [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/widgets/GraphNode.html org.eclipse.zest.core.widgets.GraphNode], and [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/widgets/GraphConnection.html org.eclipse.zest.core.widgets.GraphConnection] were created/modified.
  
 
Since [[#Zest.FX|Zest.FX]] is based on [[GEF/GEF4/MVC|GEF4 MVC]], you should be familiar with the mechanisms and concepts of [[GEF/GEF4/MVC|GEF4 MVC]], which are employed as follows:
 
Since [[#Zest.FX|Zest.FX]] is based on [[GEF/GEF4/MVC|GEF4 MVC]], you should be familiar with the mechanisms and concepts of [[GEF/GEF4/MVC|GEF4 MVC]], which are employed as follows:
 
* A [[GEF/GEF4/MVC#ContentModel|org.eclipse.gef4.mvc.models.ContentModel]] stores the Graph that is currently rendered.
 
* A [[GEF/GEF4/MVC#ContentModel|org.eclipse.gef4.mvc.models.ContentModel]] stores the Graph that is currently rendered.
* A [[GEF/GEF4/MVC#IContentPartFactory|org.eclipse.gef4.mvc.parts.IContentPartFactory]] ([[#GraphContentPart, NodeContentPart, EdgeContentPart, EdgeLabelPart, ContentPartFactory|ContentPartFactory]]) constructs controller objects (content parts) for graphs, nodes, and edges. These are responsible for updating the visualization, synchronizing visualizations with contents, and layout integration.
+
* A [[GEF/GEF4/MVC#IContentPartFactory|org.eclipse.gef4.mvc.parts.IContentPartFactory]] ([[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|ZestFxContentPartFactory]]) constructs controller objects (content parts) for graphs, nodes, and edges. These are responsible for updating the visualization, synchronizing visualizations with contents, 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.
 
* 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 [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module] ([[#ZestFxModule|ZestFxModule]]) defines 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 [[GEF/GEF4/Layout|GEF4 Layout]] into [[GEF/GEF4/Zest|GEF4 Zest]].
 
* A [http://google.github.io/guice/api-docs/3.0/javadoc/com/google/inject/Module.html com.google.inject.Module] ([[#ZestFxModule|ZestFxModule]]) defines 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 [[GEF/GEF4/Layout|GEF4 Layout]] into [[GEF/GEF4/Zest|GEF4 Zest]].
Line 248: Line 310:
  
 
==== Customizing Styles ====
 
==== Customizing Styles ====
Many visual features can be specified via JavaFX CSS within GEF4 Zest which would have required either a style provider or a custom figure in previous versions. The CSS styles can be applied to individual elements, or entire classes of elements. There are four parts of the visualization which can be styled individually:
+
Many visual features can be specified via JavaFX CSS within [[GEF/GEF4/Zest | GEF4 Zest]], which would have required either a style provider or a custom figure in previous versions. The CSS styles can be applied to individual elements, or entire classes of elements. There are eight parts of the visualization which can be styled individually (defined by [[#ZestProperties | ZestProperties]]):
* "node-rect-css-style": Styles the JavaFX Rectangle which renders the border and background of a node.
+
* "shape-css-style"
* "node-label-css-style": Styles the JavaFX Text which renders the label of a node.
+
* "label-css-style"
* "edge-curve-css-style": Styles the FXGeometryNode which renders an edge.
+
* "external-label-css-style"
* "edge-label-css-style": Styles the JavaFX Text which renders the label of an edge.
+
* "curve-css-style"
 +
* "source-label-css-style"
 +
* "target-label-css-style"
 +
* "source-decoration-css-style"
 +
* "target-decoration-css-style"
  
 
==== Customizing Visualizations ====
 
==== Customizing Visualizations ====
Within [[GEF/GEF4/MVC|GEF4 MVC]], on which [[#Zest.FX|Zest.FX]] is based, an [[GEF/GEF4/MVC#IContentPart, AbstractContentPart|org.eclipse.gef4.mvc.parts.IContentPart]] is responsible of contributing a respective visualization. You can exchange the [[#Parts|parts]] provided by [[#Zest.FX|Zest.FX]] to control nodes and edges, and thereby replace their visualizations. To do so, you have to create a custom [[GEF/GEF4/MVC#IContentPartFactory|org.eclipse.gef4.mvc.parts.IContentPartFactory]] (e.g. by subclassing [[#GraphContentPart, NodeContentPart, EdgeContentPart, EdgeLabelPart, ContentPartFactory|ContentPartFactory]]) to create different content parts.  
+
Within [[GEF/GEF4/MVC|GEF4 MVC]], on which [[#Zest.FX|Zest.FX]] is based, an [[GEF/GEF4/MVC#IContentPart, AbstractContentPart|org.eclipse.gef4.mvc.parts.IContentPart]] is responsible of contributing a respective visualization. You can exchange the [[#Parts|parts]] provided by [[#Zest.FX|Zest.FX]] to control nodes and edges, and thereby replace their visualizations. To do so, you have to create a custom [[GEF/GEF4/MVC#IContentPartFactory|org.eclipse.gef4.mvc.parts.IContentPartFactory]] (e.g. by subclassing [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|ZestFxContentPartFactory]]) to create different content parts.  
  
To exchange the original [[#GraphContentPart, NodeContentPart, EdgeContentPart, EdgeLabelPart, ContentPartFactory|ContentPartFactory]] with your custom implementation, you have to overwrite the respective binding defined within [[#ZestFxModule|ZestFxModule]]. This can easily be achieved by subclassing [[#ZestFxModule|ZestFxModule]] and overriding  <code>bindIContentPartFactory()</code>. Your custom module has to be handed into the constructor of the [[#ZestContentViewer|ZestContentViewer]], so the specified bindings are evaluated.
+
To exchange the original [[#GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory|ZestFxContentPartFactory]] with your custom implementation, you have to overwrite the respective binding defined within [[#ZestFxModule|ZestFxModule]]. This can easily be achieved by subclassing [[#ZestFxModule|ZestFxModule]] and overriding  <code>bindIContentPartFactory()</code>. Your custom module has to be handed into the constructor of the [[#ZestContentViewer|ZestContentViewer]], so the specified bindings are evaluated.
  
 
The [[GEF/GEF4/Zest/Examples#JFaceCustomNodeExample|JFaceCustomNodeExample]] demonstrates this scenario. However, be aware that colors, fonts, borders, and sizes can already be configured via JavaFX CSS and do not require a custom visualization, as outlined in [[#Customizing Styles|Customizing Styles]].
 
The [[GEF/GEF4/Zest/Examples#JFaceCustomNodeExample|JFaceCustomNodeExample]] demonstrates this scenario. However, be aware that colors, fonts, borders, and sizes can already be configured via JavaFX CSS and do not require a custom visualization, as outlined in [[#Customizing Styles|Customizing Styles]].
Line 271: Line 337:
 
----
 
----
  
=== Migration from Zest 1.x JFace to GEF4 Zest.FX.UI ===
+
=== Migration from Zest 1.x JFace to GEF4 Zest.FX.JFace ===
  
[[#Zest.FX.UI|Zest.FX.UI]] consists of a [[#ZestContentViewer|ZestContentViewer]] and related specializations of [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IContentProvider.html org.eclipse.jface.viewers.IContentProvider] and [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider].  
+
[[#Zest.FX.JFace|Zest.FX.JFace]] consists of a [[#ZestContentViewer|ZestContentViewer]] and related specializations of [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IContentProvider.html org.eclipse.jface.viewers.IContentProvider] and [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider].  
  
 
In comparison to the [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/GraphViewer.html org.eclipse.zest.core.viewers.GraphViewer] provided by [https://www.eclipse.org/gef/zest/index.php Zest 1.x], the [[#ZestContentViewer|ZestContentViewer]] is not a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/StructuredViewer.html org.eclipse.jface.viewers.StructuredViewer], but a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ContentViewer.html org.eclipse.jface.viewers.ContentViewer], which seems to be the more adequate abstraction (as a structured viewer imposes a tree-, list-, or table-based structure, which does not naturally resemble a graph).  
 
In comparison to the [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/GraphViewer.html org.eclipse.zest.core.viewers.GraphViewer] provided by [https://www.eclipse.org/gef/zest/index.php Zest 1.x], the [[#ZestContentViewer|ZestContentViewer]] is not a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/StructuredViewer.html org.eclipse.jface.viewers.StructuredViewer], but a [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ContentViewer.html org.eclipse.jface.viewers.ContentViewer], which seems to be the more adequate abstraction (as a structured viewer imposes a tree-, list-, or table-based structure, which does not naturally resemble a graph).  
  
 
==== Content Providers ====
 
==== Content Providers ====
Probably, the biggest difference between [https://www.eclipse.org/gef/zest/index.php Zest 1.x] and [[#Zest.FX.UI|Zest.FX.UI]] is related to content providers. [[#Zest.FX|Zest.FX]] defines the following ones:
+
Probably, the biggest difference between [https://www.eclipse.org/gef/zest/index.php Zest 1.x] and [[#Zest.FX.JFace|Zest.FX.JFace]] is related to content providers. [[#Zest.FX|Zest.FX]] defines the following ones:
* The [[#IGraphNodeContentProvider|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 [https://www.eclipse.org/gef/zest/index.php Zest 1.x] [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IGraphEntityContentProvider.html org.eclipse.zest.core.viewers.IGraphEntityContentProvider].
+
* The [[#IGraphContentProvider|IGraphContentProvider]] provides all content elements that represent nodes for a flat graph. The edges are inferred via a <code>getAdjacentNodes(Object)</code> method. This is the equivalent of the [https://www.eclipse.org/gef/zest/index.php Zest 1.x] [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IGraphEntityContentProvider.html org.eclipse.zest.core.viewers.IGraphEntityContentProvider]. It also covers the functionality of the [https://www.eclipse.org/gef/zest/index.php Zest 1.x] [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/INestedContentProvider.html org.eclipse.zest.core.viewers.INestedContentProvider] through its <code>getNestedGraphNodes(Object)</code> method.
* The [[#INestedGraphContentProvider|INestedGraphContentProvider]] extends the [[#IGraphNodeContentProvider|IGraphNodeContentProvider]] with two methods to provide contents for nested graphs. This is the equivalence of the [https://www.eclipse.org/gef/zest/index.php Zest 1.x] [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/INestedContentProvider.html org.eclipse.zest.core.viewers.INestedContentProvider].
+
  
Both new content providers are node-oriented, i.e. they provide content elements which represent nodes, not edges. The [https://www.eclipse.org/gef/zest/index.php Zest 1.x] API additionally defines an [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IGraphEntityRelationshipContentProvider.html org.eclipse.zest.core.viewers.IGraphEntityRelationshipContentProvider] which provides content elements that represent edges. This is not yet covered by [[#Zest.FX.UI|Zest.FX.UI]].
+
Both new content providers are node-oriented, i.e. they provide content elements which represent nodes, not edges. The [https://www.eclipse.org/gef/zest/index.php Zest 1.x] API additionally defines an [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IGraphEntityRelationshipContentProvider.html org.eclipse.zest.core.viewers.IGraphEntityRelationshipContentProvider] which provides content elements that represent edges. This is not yet covered by [[#Zest.FX.JFace|Zest.FX.JFace]].
  
 
==== Label Providers ====
 
==== Label Providers ====
While [https://www.eclipse.org/gef/zest/index.php Zest 1.x] was based on the default [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider], [[#Zest.FX.UI|Zest.FX.UI]] provides two specializations, namely [[#IGraphNodeLabelProvider, INestedGraphLabelProvider|IGraphNodeLabelProvider]] and [[#IGraphNodeLabelProvider, INestedGraphLabelProvider|INestedGraphLabelProvider]]. They allow to provide attributes for graphs, nodes, edges, and nested graphs, which may also overwrite those values provided by [[#Dedicated Providers for Styles, Tooltip, Colors, Fonts|dedicated providers]].
+
Similar to [https://www.eclipse.org/gef/zest/index.php Zest 1.x], [[#Zest.FX.JFace|Zest.FX.JFace]] is based on the default [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/ILabelProvider.html org.eclipse.jface.viewers.ILabelProvider].
  
 
==== Dedicated Providers for Styles, Tooltip, Colors, Fonts ====
 
==== Dedicated Providers for Styles, Tooltip, Colors, Fonts ====
 
Most of the custom [https://www.eclipse.org/gef/zest/index.php Zest 1.x] JFace providers have been replaced with the respective standard JFace providers:
 
Most of the custom [https://www.eclipse.org/gef/zest/index.php Zest 1.x] JFace providers have been replaced with the respective standard JFace providers:
  
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IEntityStyleProvider.html org.eclipse.zest.core.viewers.IEntityStyleProvider] provides tooltip, fisheye, border, and color information. These are now provided via [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IToolTipProvider.html org.eclipse.jface.viewers.IToolTipProvider], [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IColorProvider.html org.eclipse.jface.viewers.IColorProvider], and the specialized [[#Label Providers|label provides]] (which provides arbitrary attributes for nodes, edges, and graphs). Additionally, the [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IFontProvider.html org.eclipse.jface.viewers.IFontProvider] is now supported, which allows to exchange the label font for a node.
+
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IEntityStyleProvider.html org.eclipse.zest.core.viewers.IEntityStyleProvider] provides tooltip, fisheye, border, and color information. These are now provided via [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IToolTipProvider.html org.eclipse.jface.viewers.IToolTipProvider], [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IColorProvider.html org.eclipse.jface.viewers.IColorProvider], and the [[#IGraphAttributesProvider|attribute provide]] (which provides arbitrary attributes for nodes, edges, and graphs). Additionally, the [http://help.eclipse.org/topic/org.eclipse.platform.doc.isv/reference/api/org/eclipse/jface/viewers/IFontProvider.html org.eclipse.jface.viewers.IFontProvider] is now supported, which allows to exchange the label font for a node.
* The old [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IConnectionStyleProvider.html org.eclipse.zest.core.viewers. IConnectionStyleProvider] (and [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IEntityStyleProvider.html org.eclipse.zest.core.viewers.IEntityStyleProvider]) provide style, color, tooltip, connection router, and connection decorator. These are now provided via [[#IEdgeDecorationProvider| IEdgeDecorationProvider]] and [[#IGraphNodeLabelProvider, INestedGraphLabelProvider|IGraphNodeLabelProvider]], except for the tooltip, which is currently not supported for edges within [[#Zest.FX|Zest.FX]].
+
* The old [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IConnectionStyleProvider.html org.eclipse.zest.core.viewers. IConnectionStyleProvider] (and [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IEntityStyleProvider.html org.eclipse.zest.core.viewers.IEntityStyleProvider]) provide style, color, tooltip, connection router, and connection decorator. These are now provided via the [[#IGraphAttributesProvider|IGraphAttributeProvider]]. It can also be used to overwrite the values returned by a provider for the font, foreground, and background color, which are transferred into equivalent CSS styles.
 
+
The values returned by a provider for the font, foreground, and background color are transferred into equivalent CSS styles which can be overwritten by the [[#Label Providers|label provides]].
+
  
The following providers have not been migrated, because their corresponding functionality is implemented by means of default [[GEF/GEF4/MVC|GEF4 MVC]] mechanisms, on which [[#Zest.FX|Zest.FX]] and thus [[#Zest.FX.UI|Zest.FX.UI]] are based:
+
The following providers have not been migrated, because their corresponding functionality is implemented by means of default [[GEF/GEF4/MVC|GEF4 MVC]] mechanisms, on which [[#Zest.FX|Zest.FX]] and thus [[#Zest.FX.JFace|Zest.FX.JFace]] are based:
 
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/ISelfStyleProvider.html org.eclipse.zest.core.viewers. ISelfStyleProvider] provides a custom styling for a node or an edge. This can now be achieved by applying CSS styles as outlined in [[#Customizing Styles|Customizing Styles]].
 
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/ISelfStyleProvider.html org.eclipse.zest.core.viewers. ISelfStyleProvider] provides a custom styling for a node or an edge. This can now be achieved by applying CSS styles as outlined in [[#Customizing Styles|Customizing Styles]].
 
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IFigureProvider.html org.eclipse.zest.core.viewers.IFigureProvider] provides support for using a custom visualization for a node. This can now be achieved by means of [[GEF/GEF4/MVC|GEF4 MVC]] mechanisms, i.e. via providing a custom content part, as outlined in [[#Customizing Visualizations|Customizing Visualizations]]. Therefore, you can create your own content parts instead of the content parts provided by [[#Zest.FX|Zest.FX]]. The [[GEF/GEF4/Zest/Examples#JFaceCustomNodeExample|JFaceCustomNodeExample]] demonstrates this scenario.
 
* The [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/IFigureProvider.html org.eclipse.zest.core.viewers.IFigureProvider] provides support for using a custom visualization for a node. This can now be achieved by means of [[GEF/GEF4/MVC|GEF4 MVC]] mechanisms, i.e. via providing a custom content part, as outlined in [[#Customizing Visualizations|Customizing Visualizations]]. Therefore, you can create your own content parts instead of the content parts provided by [[#Zest.FX|Zest.FX]]. The [[GEF/GEF4/Zest/Examples#JFaceCustomNodeExample|JFaceCustomNodeExample]] demonstrates this scenario.
  
You can find examples on how to use the different providers in the [[GEF/GEF4/Zest/Examples#Examples.UI (undeployed)|JFace-API examples]].
+
You can find examples on how to use the different providers in the [[GEF/GEF4/Zest/Examples#Examples.JFace (undeployed)|JFace-API examples]].
  
 
==== Zooming ====
 
==== Zooming ====
Basic support for zooming, which is specifically implemented within [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/GraphViewer.html org.eclipse.zest.core.viewers.GraphViewer], is already provided as a base feature of [[GEF/GEF4/MVC#MVC.FX|GEF4 MVC.FX]], on which [[#Zest.FX|Zest.FX]] and thus also [[#Zest.FX.UI|Zest.FX.UI]] are based. Within [[GEF/GEF4/MVC|GEF4 MVC]], a ViewportModel maintains a content transformation which can be modified to zoom in/out of a visualization. [[#Zest.FX|Zest.FX]] adds a semantic zoom that allows to zoom into nested graphs. That is, when zooming into a nesting node, it will - from a certain zoom level onwards - show the nested contents and will eventually replace the viewer contents with the nested graph.
+
Basic support for zooming, which is specifically implemented within [http://help.eclipse.org/topic/org.eclipse.zest.doc.isv/reference/api/org/eclipse/zest/core/viewers/GraphViewer.html org.eclipse.zest.core.viewers.GraphViewer], is already provided as a base feature of [[GEF/GEF4/MVC#MVC.FX|GEF4 MVC.FX]], on which [[#Zest.FX|Zest.FX]] and thus also [[#Zest.FX.JFace|Zest.FX.JFace]] are based. Within [[GEF/GEF4/MVC|GEF4 MVC]], a ViewportModel maintains a content transformation which can be modified to zoom in/out of a visualization. [[#Zest.FX|Zest.FX]] adds a semantic zoom that allows to zoom into nested graphs. That is, when zooming into a nesting node, it will - from a certain zoom level onwards - show the nested contents and will eventually replace the viewer contents with the nested graph.
  
 
[[Category: GEF]]
 
[[Category: GEF]]

Latest revision as of 11:14, 3 June 2016

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

The GEF4 Zest component provides support for visualizing GEF4 Graph-based graph models, applying automatic layout as provided by GEF4 Layout. It is internally decomposed into the Zest.FX, Zest.FX.JFace, and Zest.FX.UI modules. In addition, there is a deployed Zest Graph Example as well as some undeployed Zest Examples and Zest JFace Examples.

GEF4-Components-Zest.png

Zest.FX

  • feature: org.eclipse.gef4.zest.fx
  • bundle: org.eclipse.gef4.zest.fx

The Zest.FX module of GEF4 Zest provides a graph viewer and implements all functionality therefore. It uses JavaFX and GEF4 FX for visualization purposes and is internally based on GEF4 MVC, and can thus also be used standalone. Integrating with the Eclipse UI is realized by the Zest.FX.UI module.

Being based on GEF4 MVC, the Zest.FX module specifies a content model and provides a related controller hierarchy and corresponding JavaFX-based visualizations. Zest.FX is capable of rendering a graph with nodes, (binary) edges, and related labels. A node can contain a (nested) graph. A node visualization is composed of a shape, an icon, a label, and a compartment for nodes and edges of a nested graph (if any). It may also have an external label that can be freely placed. An edge visualization is composed of a curve and source/target decorations. It may have freely placable source label, target label, (center) label, and external (center) label.

The content model is a GEF4 Graph model of which specific attributes are recognized and utilized by Zest.FX for visualization and layout purposes. A utility class (ZestProperties) is provided that can be used to access the visualization-related attributes. Similarly, GEF4 Layout provides a utility class (org.eclipse.gef4.layout.LayoutProperties) that can be used to access the layout-related attributes.

Visualization-related attributes specify the to be visualized contents. The appearance is controlled via JavaFX CSS. For this purpose, CSS classes are assigned to the visuals so that an external stylesheet can be used. Additionally, a CSS class, ID, and style can be specified for a graph content element using dedicated ZestProperties.

Zest.FX provides content part implementations for the individual graph abstractions, i.e. GraphPart, NodePart, and EdgePart. Additionally, NodeLabelPart and EdgeLabelPart are provided as controllers for external node/edge labels. The label parts are anchored to their respective controllers.

In order to implement automatic layout, every content part is accompanied by an AbstractLayoutBehavior implementation that is responsible for transferring visualization-related attributes to layout-related attributes (and vice versa) within the content GEF4 Graph model: GraphLayoutBehavior, NodeLayoutBehavior, and EdgeLayoutBehavior.

Furthermore, Zest.FX provides a HidingModel that maintains a set of currently hidden nodes. The hidden nodes are neither shown, nor taken into account when performing automatic layout. AbstractHidingBehavior implementations are used to hide/show nodes in response to HidingModel changes. The behaviors also generate HiddenNeighborsFeedbackParts that indicate the number of hidden neighbor nodes. Per default, the user can hide/show nodes using dedicated hover handles, or interaction policies.

In order to navigate nested/nesting graphs, interaction policies are registered that open a nested/parent graph on double-click (OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy), and a SemanticZoomPolicy is registered that carries out zooming and scrolling interactions, so that the user can zoom into and out of (nested) graphs. The viewport of a previously opened graph is stored in the NavigationModel and restored when that graph is opened again.

Besides, a TranslateSelectedAndRelocateLabelsOnDragPolicy is registered so that nodes and labels can be relocated via mouse drag interaction.

{Root}

  • package: org.eclipse.gef4.zest.fx

The {Root} package provides a com.google.inject.Module (ZestFxModule) with bindings, as well as a utility class (ZestProperties) to work with the visualization and layout attributes/properties recognized by GEF4 Zest.

GEF4-Zest-FX-root.jpg

ZestFxModule

The ZestFxModule defines various (default) bindings, concerning parts, policies, etc. needed to realize the graph visualization.

ZestProperties

ZestProperties defines attributes that are associated to graphs, nodes, and edges (of GEF4 Graph), to control the visualization as well as the layout.

The visualization is based on the following attribute, which are associated with graphs (g), nodes (n), or edges (e):

  • SHAPE__N, javafx.scene.Node (n): Stores the node that is used to display the border and background of the node.
  • LABEL__NE, java.lang.String (n, e): Stores the label for the element.
  • EXTERNAL_LABEL__NE, java.lang.String (n, e): Stores the external label for the element, which can be freely placed.
  • ICON__N, javafx.scene.image.Image (n): The image that is displayed next to the node's label.
  • TOOLTIP__N, java.lang.String (n): Text, which is shown as a tooltip, i.e. when the mouse hover the node and does not move for a short time.
  • CURVE__E, javafx.scene.Node (n): Stores the node that is used to render the stroke of the edge.
  • SOURCE_LABEL__E, java.lang.String (e): Stores the source label for the edge.
  • TARGET_LABEL__E, java.lang.String (e): Stores the target label for the edge.
  • SOURCE_DECORATION__E, javafx.scene.Node (n): Stores the node that is used to render the source decoration of the edge.
  • TARGET_DECORATION__E, javafx.scene.Node (n): Stores the node that is used to render the target decoration of the edge.
  • CSS_CLASS__NE, java.lang.String (n, e): Stores the CSS class that is assigned to the element.
  • CSS_ID__NE, java.lang.String (n, e): Stores the CSS id that is assigned to the element.
  • SHAPE_CSS_STYLE__N, java.lang.String (n): Stores the CSS style that is assigned to the shape of this node.
  • LABEL_CSS_STYLE__NE, java.lang.String (n, e): Stores the CSS style that is assigned to the javafx.scene.text.Text which displays the label of the element.
  • CURVE_CSS_STYLE__E, java.lang.String (e): Stores the CSS style that is assigned to the curve of the edge.
  • SOURCE_LABEL_CSS_STYLE__E, java.lang.String (e): Stores the CSS style that is assigned to the source label of this edge.
  • TARGET_LABEL_CSS_STYLE__E, java.lang.String (e): Stores the CSS style that is assigned to the target label of this edge.
  • SOURCE_DECORATION_CSS_STYLE__E, java.lang.String (e): Stores the CSS style that is assigned to the source decoration of this edge.
  • TARGET_DECORATION_CSS_STYLE__E, java.lang.String (e): Stores the CSS style that is assigned to the target decoration of this edge.
  • ROUTER__E, org.eclipse.gef4.fx.nodes.IConnectionRouter (e): Stores the router that is used to manipulate the waypoints of the edge
  • INTERPOLATOR__E, org.eclipse.gef4.fx.nodes.IConnectionInterpolator (e): Stores the interpolator that is used to manipulate the appearance of the edge.
  • INVISIBLE__NE, java.lang.Boolean (n,e): Stores whether this element is to be visual or not.

The layout is based on the following attributes, which are associated with graphs (g), nodes (n), or edges (e):


Behaviors

  • package: org.eclipse.gef4.zest.fx.behaviors

The Behaviors package contains specific IBehavior implementations for exchanging layout information (AbstractLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior) and the hiding/showing of nodes and related edges (AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior).

GEF4-Zest-FX-behaviors.png

AbstractLayoutBehavior, GraphLayoutBehavior, NodeLayoutBehavior, EdgeLayoutBehavior

The GraphLayoutBehavior maintains a org.eclipse.gef4.layout.LayoutContext, i.e. it is responsible for the creation of such a layout context, updating the layout bounds (based on the corresponding GraphPart), and initiating layout passes (based on content or bounds changes). It also registers pre- and post-layout-passes at the org.eclipse.gef4.layout.LayoutContext, including those of related NodeLayoutBehaviors and EdgeLayoutBehaviors. The NodeLayoutBehavior provides location and size of its corresponding NodePart before a layout pass is applied, and, accordingly, copies the location and size from the org.eclipse.gef4.layout.LayoutContext to its corresponding NodePart afterwards. Afterwards it initiates a refresh of the visualization and updates the external label position, which is ignored by the GEF4 Layout algorithms. The EdgeLayoutBehavior does not need to provide layout information, but only refreshes the visualization of its corresponding EdgePart after a layout pass, as well updating the positions of external labels. The AbstractLayoutBehavior provides common functionality for all layout related behaviors.

AbstractHidingBehavior, NodeHidingBehavior, EdgeHidingBehavior, EdgeLabelHidingBehavior

The NodeHidingBehavior, EdgeHidingBehavior, and EdgeLabelHidingBehavior react to changes in the HidingModel by hiding/showing the corresponding visuals. In addition, for nodes, a HiddenNeighborsFeedbackPart is created when any neighboring nodes are currently hidden. The AbstractHidingBehavior provides common functionality for all hiding related behaviors.


Models

  • package: org.eclipse.gef4.zest.fx.models

The Models package provides viewer models to support hiding of nodes (HidingModel) as well as semantic zooming ( NavigationModel).

GEF4-Zest-FX-models.png

HidingModel

The HidingModel is a viewer model that stores which nodes are currently hidden. Every visible node shows a small marker indicating how many of its neighbors are hidden. You can hide/show nodes using the hover handles, respectively. The visualization is automatically synchronized with the HidingModel.

NavigationModel

The NavigationModel is a viewer model needed to persist viewport configurations. It is used to keep track of all viewports that are passed during nested graph navigation when zooming in and can be used to restore viewports when zooming out again.


Operations

  • package: org.eclipse.gef4.zest.fx.operations

The Operations package currently provides operations for the hiding (visible) and showing (invisible) nodes, as well as for navigating and manipulating of attributes.

GEF4-Zest-FX-operations.png

HideOperation, ShowHiddenNeighboursOperation

The HideOperation and ShowHiddenNeighboursOperation are used by HidePolicy to hide or show nodes. It adds/removes a respective content part to/from the HidingModel.

NavigateOperation

The NavigateOperation is used by the SemanticZoomPolicy to realize navigation into and out of nested graphs.

ChangeAttributesOperation

The ChangeAttributesOperation is a general operation used to change values of attributes of an org.eclipse.gef4.common.attributes.IAttributeStore, i.e for a Graph model element.


Parts

  • package: org.eclipse.gef4.zest.fx.parts

The Parts package provides a specific org.eclipse.gef4.mvc.fx.parts.FXRootPart which adds support for CSS styling.

GEF4-Zest-FX-parts-root.png

It furthermore provides specific org.eclipse.gef4.mvc.fx.parts.AbstractFXContentPart implementations (GraphPart, NodePart, NodeLabelPart, EdgePart, and EdgeLabelPart) to control the visualizations of graphs, nodes, and edges.

GEF4-Zest-FX-parts-contents.png

In addition, it provides specific org.eclipse.gef4.mvc.fx.parts.AbstractFXHandlePart implementations (HideHoverHandlePart and ShowHiddenNeighborsHoverHandlePart) to realize hiding and showing of nodes via hover handles.

GEF4-Zest-FX-parts-handles.png

There is also specific AbstractFXFeedbackPart implementation (HiddenNeighborsFeedbackPart) to indicate feedback for hidden nodes.

GEF4-Zest-FX-parts-feedback.png

ZestFxRootPart

The ZestFxRootPart is a specific org.eclipse.gef4.mvc.fx.parts.FXRootPart that adds support for CSS styling. In detail, it loads a file with default CSS styles (STYLES_CSS_FILE) and applies it as stylesheet to the javafx.scene.Scene.

GraphPart, NodePart, NodeLabelPart, EdgePart, EdgeLabelPart, ZestFxContentPartFactory

The GraphPart, NodePart, and EdgePart implementations control the visualization of the underlying GEF4 Graph model elements, i.e. graphs, nodes, and edges. The default visualization for nodes (contributed by NodePart) consists of a shape Node for background and border, a javafx.scene.text.Text for the label, and an javafx.scene.image.ImageView for the icon. The default visualization for edges (contributed by EdgePart consists of a org.eclipse.gef4.fx.nodes.Connection, whose curve node can be exchanged. The external labels of nodes and edges are visualized by javafx.scene.text.Texts, which are controlled by NodeLabelPart and EdgeLabelPart respectively.

The NodePart and EdgePart assign the following JavaFX CSS classes to its visuals:

  • "node" is assigned to the visual of the NodePart.
  • "shape" is assigned to the shape sub-visual of the NodePart.
  • "label" is assigned to the label sub-visual of the NodePart.
  • "icon" is assigned to the icon sub-visual of the NodePart.
  • "edge" is assigned to the visual of the EdgePart.
  • "curve" is assigned to the curve sub-visual of the EdgePart.
  • "decoration" is assigned to the decoration sub-visuals of the EdgePart.

HideHoverHandlePart, ShowHiddenNeighborsHoverHandlePart, ZestFxHoverHandlePartFactory

The HideHoverHandlePart and ShowHiddenNeighborsHoverHandlePart are complementary org.eclipse.gef4.mvc.fx.parts.AbstractFXSegmentHandlePart implementations that are used as hover handles. Being anchored on a respective NodeParts, they react to mouse clicks to perform hiding or showing of nodes.

Hover handles for hide/show

HiddenNeighborsFeedbackPart

The HiddenNeighborsFeedbackPart is a specific org.eclipse.gef4.mvc.fx.parts.AbstractFXFeedbackPart that indicates the number of hidden neighbor nodes via a circle decoration (with a number label).

Feedback for hidden neighbor nodes

ZestFxSelectionHandlePartFactory

The ZestFxSelectionHandlePartFactory is a specific handle part factory that does prevent creation of multi selection handles.


Policies

  • package: org.eclipse.gef4.zest.fx.policies

The Policies package contains specific IPolicy implementations for hiding/showing of nodes (HideNodePolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, and ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy), dragging external labels (TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy), and navigating nested graphs via double click ( SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy).

GEF4-Zest-FX-policies.png

HidePolicy, ShowHiddenNeighborsPolicy, HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy

The HidePolicy and ShowHiddenNeighborsPolicy are transaction policies that are registered as an adapter on NodeParts. They are used by the HideOnTypePolicy, ShowHiddenNeighborsOnTypePolicy, HideFirstAnchorageOnClickPolicy, and ShowHiddenNeighborsOfFirstAnchorageOnClickPolicy interaction policies to realize the hiding and showing of nodes.

TransformLabelPolicy, TranslateSelectedAndRelocateLabelsOnDragPolicy

The TranslateSelectedAndRelocateLabelsOnDragPolicy is a specific IFXOnDragPolicy that enables the positioning of node and edge labels (i.e. NodeLabelPart and EdgeLabelPart) during mouse drag. It uses the underlying TransformLabelPolicy to realize the translate operation.

SemanticZoomPolicy, OpenNestedGraphOnDoubleClickPolicy, OpenParentGraphOnDoubleClickPolicy

The OpenNestedGraphOnDoubleClickPolicy and OpenParentGraphOnDoubleClickPolicy policies implement nested graph navigation via double clicking with the mouse. They both rely on the underlying SemanticZoomPolicy, which manipulates the NavigationModel via a NavigateOperation. The graph of the node where the current graph is nested is opened when the user double clicks in the background (i.e. in a ZestFxRootPart), and the nested graph is opened when the user double clicks in a NodePart that contains a nested graph.


Providers

  • package: org.eclipse.gef4.zest.fx.providers

The Providers package contains a specific anchor provider for NodeParts.

GEF4-Zest-FX-providers.png

NodePartAnchorProvider

The NodePartAnchorProvider is a specific org.eclipse.gef4.mvc.fx.providers.DefaultAnchorProvider that uses the NodePart's shape outline.


Zest.FX.JFace

  • feature: org.eclipse.gef4.zest.fx.jface
  • bundle: org.eclipse.gef4.zest.fx.jface

The Zest.FX.JFace module of GEF4 Zest provides a JFace-based API to populate a Zest viewer (i.e. an FXViewer).


{Root}

  • package: org.eclipse.gef4.zest.fx.jface

The Root package provides a specific org.eclipse.jface.viewers.ContentViewer (ZestContentViewer), related content (IGraphContentProvider, and attribute (IGraphAttributesProvider) providers.

GEF4-Zest-FX-JFace-root.png

ZestContentViewer

A ZestContentViewer is a specific org.eclipse.jface.viewers.ContentViewer that renders an input model as a directed graph, using Zest.FX.

The to be rendered graph is inferred from the input model by means of a org.eclipse.jface.viewers.IContentProvider. In the context of a ZestContentViewer, the content provider has to implement IGraphContentProvider. The content provider is node-based, i.e. edges are not represented as first level entities, but are only inferred from input objects via getAdjacentNodes(Object).

The visualization of the graph (i.e. of its nodes and edges) can be controlled via a org.eclipse.jface.viewers.ILabelProvider. The getText(Object) and getImage(Object) of the label provider will be used to infer labels and icons for nodes. In case the label provider implements org.eclipse.jface.viewers.IColorProvider, its getForeground(Object) will be used to infer the color of the node outline and its label, and getBackground(Object) will be used as the node's fill color. In case the label provider implements org.eclipse.jface.viewers.IFontProvider, getFont(Object) will be used to infer the name, size, and style (bold or italic) of the font, used by the node label. The label provider may furthermore implement org.eclipse.jface.viewers.IToolTipProvider in case a tooltip should be shown on hovering the node.

Further, the label provider may implement IGraphAttributesProvider, which allows to provide values for all specified ZestProperties for graphs, nodes and edges, via which the visualization can be controlled even more fine-grained. It will overwrite the values returned via the standard label and dedicated provider methods. For edges, this can for instance be used to provide label texts (using the label, external-label, source-label, or target-label attribute).

IGraphContentProvider

The IGraphContentProvider is responsible of returning those input elements (getNodes()) that are to be visualized as nodes, and to provide information about which nodes are connected via edges to other nodes. The IGraphContentProvider is node-based, i.e. the to be visualized edges are only represented implicitly, by providing the connection target nodes of a node via getAdjacentNodes(Object), and are not explicitly mapped to underlying input elements. It further provides information about nested graphs via getNestedGraphNodes(Object).

IGraphAttributesProvider

The IGraphAttributesProvider can be implemented by a label provider to return attributes, i.e. ZestProperties for a root graph, as well as for nodes and edges.


Zest.FX.UI

  • feature: org.eclipse.gef4.zest.fx.ui
  • bundle: org.eclipse.gef4.zest.fx.ui

The Zest.FX.UI module of GEF4 Zest contains Eclipse Workbench UI related graph visualization support. This includes a com.google.inject.Module] (ZestFxUiModule), which augments the bindings of ZestFxModule to realize the Eclipse Workbench UI integration and an Eclipse view (ZestFxUiView) to render graphs based on Zest.FX.


{Root}

  • package: org.eclipse.gef4.zest.fx.ui

The {Root} package provides a com.google.inject.Module (ZestFxUiModule) with bindings related to the Eclipse UI Workbench integration of Zest.FX.

GEF4-Zest-FX-UI-root.png

ZestFxUiModule

The ZestFxUiModule extends org.eclipse.gef4.mvc.ui.MvcUiModule and thus delivers specific bindings related to the integration of Zest.FX with the Eclipse Workbench UI.

Parts

  • package: org.eclipse.gef4.zest.fx.ui.parts

The Parts package provides an Eclipse org.eclipse.ui.part.ViewPart (ZestFxUiView) for visualizing graph models.

GEF4-Zest-FX-UI-parts.png

ZestFxUiView

ZestFxUiView is a specific FXView that can render graphs. It uses the bindings provided by ZestFxModule and ZestFxUiModule.


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. a JFace API with specific content and label providers and a viewer dedicated to displaying Zest graphs.

The former has been replaced by Zest.FX and the latter by 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 and interweaves graph data, layout data, and visuals, Zest.FX is based on GEF4 MVC and maintains distinct object hierarchies for the graph data (content model), the layout data (layout model), and the visuals. As a result, in order to perform structural changes to the visualized graph, 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 Zest.FX, you have to create/modify a org.eclipse.gef4.graph.Graph where previously org.eclipse.zest.core.widgets.Graph, org.eclipse.zest.core.widgets.GraphNode, and org.eclipse.zest.core.widgets.GraphConnection were created/modified.

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

  • A org.eclipse.gef4.mvc.models.ContentModel stores the Graph that is currently rendered.
  • A org.eclipse.gef4.mvc.parts.IContentPartFactory (ZestFxContentPartFactory) constructs controller objects (content parts) for graphs, nodes, and edges. These are responsible for updating the visualization, synchronizing visualizations with contents, 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 com.google.inject.Module (ZestFxModule) defines 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 Zest Graph Example demonstrates best 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 (Visualization Properties).

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

Customizing Styles

Many visual features can be specified via JavaFX CSS within GEF4 Zest, which would have required either a style provider or a custom figure in previous versions. The CSS styles can be applied to individual elements, or entire classes of elements. There are eight parts of the visualization which can be styled individually (defined by ZestProperties):

  • "shape-css-style"
  • "label-css-style"
  • "external-label-css-style"
  • "curve-css-style"
  • "source-label-css-style"
  • "target-label-css-style"
  • "source-decoration-css-style"
  • "target-decoration-css-style"

Customizing Visualizations

Within GEF4 MVC, on which Zest.FX is based, an org.eclipse.gef4.mvc.parts.IContentPart is responsible of contributing a respective visualization. You can exchange the parts provided by Zest.FX to control nodes and edges, and thereby replace their visualizations. To do so, you have to create a custom org.eclipse.gef4.mvc.parts.IContentPartFactory (e.g. by subclassing ZestFxContentPartFactory) to create different content parts.

To exchange the original ZestFxContentPartFactory with your custom implementation, you have to overwrite the respective binding defined within ZestFxModule. This can easily be achieved by subclassing ZestFxModule and overriding bindIContentPartFactory(). Your custom module has to be handed into the constructor of the ZestContentViewer, so the specified bindings are evaluated.

The JFaceCustomNodeExample demonstrates this scenario. However, be aware that colors, fonts, borders, and sizes can already be configured via JavaFX CSS and do not require a custom visualization, as outlined in Customizing Styles.

Modifying graphs

Since you cannot modify the visualization directly, you have to adjust the underlying graph model instead. The FullyMeshedLayoutExample demonstrates this scenario.

Layout filter

Nodes and edges can be marked as layout-irrelevant, meaning they will not get reported to layout algorithms. The FilterLayoutExample demonstrates this scenario.


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

Zest.FX.JFace consists of a ZestContentViewer and related specializations of org.eclipse.jface.viewers.IContentProvider and org.eclipse.jface.viewers.ILabelProvider.

In comparison to the org.eclipse.zest.core.viewers.GraphViewer provided by Zest 1.x, the ZestContentViewer is not a org.eclipse.jface.viewers.StructuredViewer, but a org.eclipse.jface.viewers.ContentViewer, which seems to be the more adequate abstraction (as a structured viewer imposes a tree-, list-, or table-based structure, which does not naturally resemble a graph).

Content Providers

Probably, the biggest difference between Zest 1.x and Zest.FX.JFace is related to content providers. Zest.FX defines the following ones:

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 org.eclipse.zest.core.viewers.IGraphEntityRelationshipContentProvider which provides content elements that represent edges. This is not yet covered by Zest.FX.JFace.

Label Providers

Similar to Zest 1.x, Zest.FX.JFace is based on the default org.eclipse.jface.viewers.ILabelProvider.

Dedicated Providers for Styles, Tooltip, Colors, Fonts

Most of the custom Zest 1.x JFace providers have been replaced with the respective standard JFace providers:

The following providers have not been migrated, because their corresponding functionality is implemented by means of default GEF4 MVC mechanisms, on which Zest.FX and thus Zest.FX.JFace are based:

You can find examples on how to use the different providers in the JFace-API examples.

Zooming

Basic support for zooming, which is specifically implemented within org.eclipse.zest.core.viewers.GraphViewer, is already provided as a base feature of GEF4 MVC.FX, on which Zest.FX and thus also Zest.FX.JFace are based. Within GEF4 MVC, a ViewportModel maintains a content transformation which can be modified to zoom in/out of a visualization. Zest.FX adds a semantic zoom that allows to zoom into nested graphs. That is, when zooming into a nesting node, it will - from a certain zoom level onwards - show the nested contents and will eventually replace the viewer contents with the nested graph.

Back to the top