Difference between revisions of "GEF/GEF4/Zest"

From Eclipsepedia

< GEF‎ | GEF4
Jump to: navigation, search
Line 1: Line 1:
 
TODO: Create a stand-alone documentation of the GEF4 Zest component here. Up to now, some documentation can already be found under [[Zest]]
 
TODO: Create a stand-alone documentation of the GEF4 Zest component here. Up to now, some documentation can already be found under [[Zest]]
 +
 +
''Note to non-wiki readers: This documentation is generated from the Eclipse wiki - if you have corrections or additions it would be awesome if you added them in [http://wiki.eclipse.org/Zest the original wiki page]''.
 +
 +
== GEF4 Zest ==
 +
 +
This is a collection of documentation on Zest 2.0, the latest development version of Zest. Zest 2 is part of [[GEF/GEF4|GEF4]] and can be installed from the [[GEF/GEF4#Update_Sites|GEF4 Update Sites]]. Additional information can also be found here:
 +
 +
* [[Tree_Views_for_Zest | Zest 2.0 Layout API]]
 +
* [[Zest/DOT | Graphviz DOT support]]
 +
 +
== Contribute ==
 +
 +
The Zest 2 source code is available from the [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/ GEF4 Git repository]. It is also [https://github.com/eclipse/gef4 mirrored on GitHub]. There are example snippets in ''org.eclipse.gef4.zest.examples'' and tests in ''org.eclipse.gef4.zest.tests''. For instructions on contributing, see the [[GEF/Contributor Guide | GEF Contributor Guide]]. You can search for [https://bugs.eclipse.org/bugs/buglist.cgi?list_id=4722702&classification=Tools&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Zest&product=GEF existing bugs], or [https://bugs.eclipse.org/bugs/enter_bug.cgi?product=GEF&component=Zest file a new one].
 +
 +
== New subgraph rendering ==
 +
 +
In GEF4 Zest, 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‎]]
 +
 +
 +
 +
== 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.gef4.git/tree/org.eclipse.gef4.zest.tests/src/org/eclipse/gef4/zest/tests/dot/SampleUsage.java available in the repository], as well as [http://git.eclipse.org/c/gef/org.eclipse.gef4.git/tree/org.eclipse.gef4.zest.tests/resources/tests DOT input samples].
 +
 +
== Migration from Zest 1.x to GEF4 Zest ==
 +
 +
 +
=== 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.gef4.git/tree/org.eclipse.gef4.zest.examples/src/org/eclipse/gef4/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;
 +
  }
 +
};
 +
 +
=== 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.gef4.git/tree/org.eclipse.gef4.zest.examples/src/org/eclipse/gef4/zest/examples/jface/ManhattanLayoutJFaceSnippet.java ManhattanLayoutJFaceSnippet.java] in the examples bundle.
 +
 +
= Zest 1.x =
 +
 +
Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found in the [[GEF/Reference_Documentation|GEF Reference Documentation]].
 +
[[Category: GEF]]

Revision as of 16:28, 20 January 2014

TODO: Create a stand-alone documentation of the GEF4 Zest component here. Up to now, some documentation can already be found under Zest

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

Contents

GEF4 Zest

This is a collection of documentation on Zest 2.0, the latest development version of Zest. Zest 2 is part of GEF4 and can be installed from the GEF4 Update Sites. Additional information can also be found here:

Contribute

The Zest 2 source code is available from the GEF4 Git repository. It is also mirrored on GitHub. There are example snippets in org.eclipse.gef4.zest.examples and tests in org.eclipse.gef4.zest.tests. For instructions on contributing, see the GEF Contributor Guide. You can search for existing bugs, or file a new one.

New subgraph rendering

In GEF4 Zest, 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.

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

150px‎

PrunedSuccessorsSubgraph

Each subgraph is represented as a little label showing how many direct successors are pruned.

150px‎


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 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. in source code comments or in wiki markup.

digraph simple { 
 n1[label="Node 1"]
 n2[label="Node 2"]
 n1 -> n2[style=dotted label="A dotted edge"]
}

DotZestGraphView.png

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 }
}

DotZestSubgraphs1.png

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 available in the repository, as well as DOT input samples.

Migration from Zest 1.x to GEF4 Zest

Layout Filters

Instead of org.eclipse.zest.layouts.Filter use org.eclipse.zest.core.widgets.LayoutFilter (see example below and full code in 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;
  }
};

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 ManhattanLayoutJFaceSnippet.java in the examples bundle.

Zest 1.x

Documentation on getting started with Zest 1.x, the latest released version of Zest, can be found in the GEF Reference Documentation.