Jump to: navigation, search

Difference between revisions of "Zest"

(Zest 2.x: Add marketplace link)
(Removed old contents referring to Zest 2.x, which was moved to GEF4.)
 
(4 intermediate revisions by 2 users not shown)
Line 1: Line 1:
''Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in [http://wiki.eclipse.org/Zest the original wiki page]''.
+
For general information about Zest 1.x visit the [http://www.eclipse.org/gef/zest Zest home page]. Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found in the [[GEF/Reference_Documentation|GEF Reference Documentation]].
  
Documentation on Zest - The Eclipse Visualization Framework. For general information visit the [http://www.eclipse.org/gef/zest Zest home page].
+
The new version of Zest is developed as part of [[GEF/GEF4|GEF4]] and is documented at [[GEF/GEF4/Zest|here]].
  
= Zest 1.x =
 
 
Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found on the [[GEF_Zest_Visualization|Zest 1.x wiki page]]. Further documentation is available under the [http://wiki.eclipse.org/Category:GEF GEF category].
 
 
= Zest 2.x =
 
 
This is a collection of documentation on Zest 2.0, the latest development version of Zest. A nightly build of Zest 2 can be installed from our [https://hudson.eclipse.org/hudson/job/gef-zest-nightly/lastSuccessfulBuild/artifact/targetPlatform/ p2 repository]. Integration builds can be installed from the [http://marketplace.eclipse.org/content/zest Eclipse Marketplace].
 
 
== Contribute ==
 
 
The Zest 2 source code is available from our [http://git.eclipse.org/c/gef/org.eclipse.zest.git Git repository]. It is also [https://github.com/fsteeg/org.eclipse.zest mirrored on GitHub]. After cloning and importing the Zest projects in Eclipse 3.7, load the Zest target platform using the [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.dot.ui/zest.target zest.target] file. There are example snippets in ''org.eclipse.zest.examples'' and tests in ''org.eclipse.zest.tests''. To build a p2 repository and run the tests with Tycho, run Maven 3 in the local Git repository root:
 
 
mvn clean install
 
 
You can also skip running the tests:
 
 
mvn -Dskip-tests=true clean install
 
 
To contribute to Zest 2, create a branch in your local Git repository for working on your changes, e.g. a fix for {{bug|321775}}:
 
 
git checkout -b fix-321775
 
 
Test, fix, and commit until you're done. Run the build to make sure everything works. Then create a patch including all commits on your branch against master, like this:
 
 
git format-patch master --stdout > fix-321775.patch
 
 
Finally, attach your patch to the corresponding bug, in this case bug 321775. You can search for [http://bugs.eclipse.org/bugs/buglist.cgi?query_format=advanced;component=Zest;product=GEF existing bugs], or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=GEF&component=Zest file a new one].
 
 
== New subgraph rendering ==
 
 
In Zest 2, subgraphs can hide their contained nodes or add different types of additional information about ''pruned'' elements:
 
 
=== LabelSubgraph ===
 
 
Each subgraph is represented as a separate graph item: a label showing the number of nodes contained within it. It can be subclassed to show other kinds of information.
 
 
[[Image:Zest-tree-subgraph-label.png|150px‎]]
 
 
=== TriangleSubgraph ===
 
 
Each subgraph is represented as a triangle. It's designed specifically to work with ''SpaceTreeLayoutAlgorithm'' (see below) and assumes that nodes ''pruned'' inside it form a tree structure. Properties of this structure are visualized by properties of the triangle. The height of the triangle corresponds to the height of the tree, the length of the triangle's base corresponds to the total number of leaves in the tree and the luminance of the triangle's color corresponds to the average number of children for each node in the tree (which can be understood as the density).
 
 
[[Image:Zest-tree-subgraph-triangle.png|150px‎]]
 
 
=== PrunedSuccessorsSubgraph ===
 
 
Each subgraph is represented as a little label showing how many direct successors are ''pruned''.
 
 
[[Image:Zest-tree-subgraph-successors.png|150px‎]]
 
 
== New layout algorithms ==
 
 
=== SpaceTreeLayoutAlgorithm ===
 
 
''SpaceTreeLayoutAlgorithm'' keeps track of node positions all the time, always trying to form a nice tree structure. This means movement of nodes with the mouse is somehow restricted (you can move a node within its current layer, but only if it doesn't cause nodes to be pushed out of the graph area. When an ''expand'' operation is requested on a node, the node is centered and its subtree is shown, as long as there's enough space (other parts of the tree can be collapsed to extend available space).
 
 
[[Image:Zest-tree-layout-spacetree.png|200px]]
 
 
=== DirectedGraphLayoutAlgorithm ===
 
 
''DirectedGraphLayoutAlgorithm'' was designed with the [http://www.eclipse.org/pde/incubator/dependency-visualization/index.php PDE Dependency Visualization] in mind and is based on its layout algorithm. Initially only nodes without predecessors are ''expanded''. Other nodes become visible if they have at least one direct predecessor which is visible and ''expanded''. ''Collapsed'' nodes can have outcoming connections if the target node is visible because of a predecessor. There's an option to hide such connections.
 
 
[[Image:Zest-tree-layout-dag.png|200px]]
 
 
== Graphviz DOT support ==
 
 
=== UI ===
 
 
In Zest 2, graphs can be created from DOT input. For instance, for the following DOT input, the Zest graph below is drawn, see also the [[Graphviz DOT as a DSL for Zest|complete documentation]]. The Zest graph view can be used with the included DOT editor to visualize a DOT file or to display embedded DOT in other files, e.g. [http://fsteeg.wordpress.com/2010/01/07/visual-textual-documentation-with-dot-and-zest-in-eclipse/ in source code comments] or [http://fsteeg.wordpress.com/2010/02/07/diagrams-in-wiki-markup-with-mylyn-wikitext-dot-and-zest/ in wiki markup].
 
 
digraph simple {
 
  n1[label="Node 1"]
 
  n2[label="Node 2"]
 
  n1 -> n2[style=dotted label="A dotted edge"]
 
}
 
 
[[Image:DotZestGraphView.png|150px]]
 
 
=== Subgraphs ===
 
 
Cluster subgraphs in DOT input are rendered as Zest graph containers, e.g.:
 
 
digraph subgraphs {
 
  subgraph cluster1 { 1 -> 2; 2 -> 3; 2 -> 4 }
 
  subgraph cluster2 { a -> b; a -> c; a -> d }
 
}
 
 
[[Image:DotZestSubgraphs1.png|300px]]
 
 
=== API ===
 
 
Using the API, DOT can be imported to Zest graphs, and Zest graphs can be exported to DOT (see below). To use the API, create a new Plug-in project and add ''org.eclipse.zest.dot.core'' to the MANIFEST.MF dependencies.
 
 
DotGraph graph = new DotGraph("digraph{ 1->2 }", shell, SWT.NONE);
 
graph.add("2->3").add("2->4");
 
graph.add("node[label=zested]; edge[style=dashed]; 3->5; 4->6");
 
System.out.println(graph.toDot());
 
 
The complete sample usage is [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.tests/src/org/eclipse/zest/tests/dot/SampleUsage.java available in the repository], as well as [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.tests/resources/tests DOT input samples].
 
 
== Migration from Zest 1.x to Zest 2.x ==
 
 
In Zest 2, the layout API has been reworked. Most code should keep working just fine. See the Javadoc of the deprecated API for documentation on migrating to the new API. In a few cases however, code changes are required.
 
 
=== Layout Filters ===
 
 
Instead of ''org.eclipse.zest.layouts.Filter'' use ''org.eclipse.zest.core.widgets.LayoutFilter'' (see example below and full code in [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.examples/src/org/eclipse/zest/examples/swt/GraphSnippet8.java GraphSnippet8.java] in the examples bundle).
 
 
LayoutFilter filter = new LayoutFilter() {
 
  public boolean isObjectFiltered(GraphItem item) {
 
    if (item instanceof GraphConnection) {
 
      GraphConnection connection = (GraphConnection) item;
 
      Object data = connection.getData();
 
      if (data != null && data instanceof Boolean) {
 
        return ((Boolean) data).booleanValue();
 
      }
 
      return true;
 
    }
 
    return false;
 
  }
 
};
 
 
=== Custom Layouts ===
 
 
To define custom layouts, instead of extending ''AbstractLayoutAlgorithm'' implement ''LayoutAlgorithm'' (see example below and full code in [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.examples/src/org/eclipse/zest/examples/swt/CustomLayout.java CustomLayout.java] in the examples bundle).
 
 
LayoutAlgorithm layoutAlgorithm = new LayoutAlgorithm() {
 
  private LayoutContext context;
 
  public void setLayoutContext(LayoutContext context) {
 
    this.context = context;
 
  }
 
  public void applyLayout(boolean clean) {
 
    EntityLayout[] entitiesToLayout = context.getEntities();
 
    int totalSteps = entitiesToLayout.length;
 
    double distance = context.getBounds().width / totalSteps;
 
    int xLocation = 0;
 
    for (int currentStep = 0; currentStep < entitiesToLayout.length; currentStep++) {
 
      EntityLayout layoutEntity = entitiesToLayout[currentStep];
 
      layoutEntity.setLocation(xLocation,
 
      layoutEntity.getLocation().y);
 
      xLocation += distance;
 
    }
 
  }
 
};
 
 
=== Connection Style Providers ===
 
 
The ''IConnectionStyleProvider'' and ''IEntityConnectionStyleProvider'' interfaces now contain ''getRouter'' methods returning an ''org.eclipse.draw2d.ConnectionRouter''. Return ''null'' for the default router. See [http://git.eclipse.org/c/gef/org.eclipse.zest.git/tree/org.eclipse.zest.examples/src/org/eclipse/zest/examples/jface/ManhattanLayoutJFaceSnippet.java ManhattanLayoutJFaceSnippet.java] in the examples bundle.
 
 
 
[[Category: GEF]] [[Category: Zest]]
 
[[Category: GEF]] [[Category: Zest]]

Latest revision as of 11:07, 25 March 2015

For general information about Zest 1.x visit the Zest home page. Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found in the GEF Reference Documentation.

The new version of Zest is developed as part of GEF4 and is documented at here.