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 "VIATRA/Addon/VIATRA Viewers"

< VIATRA‎ | Addon
(13 intermediate revisions by 2 users not shown)
Line 7: Line 7:
 
To select which patterns are used to determine the model elements to bind, several annotations are used by the framework. These annotations also allow to add labels and formatting to the viewers.
 
To select which patterns are used to determine the model elements to bind, several annotations are used by the framework. These annotations also allow to add labels and formatting to the viewers.
  
== Viewer Annotations ==
+
== Using Viewer Annotations for Specifying the View Model ==
 
+
 
The IncQuery Viewers component uses four different annotations to bind query results to various viewers. As the different viewers have vastly different capabilities, all annotations are designed to be ignored if an unsupported annotation (or annotation parameter) is detected. Multiple patterns can have the same annotation type, in this case the Viewers component adds all the corresponding results to the viewer.
 
The IncQuery Viewers component uses four different annotations to bind query results to various viewers. As the different viewers have vastly different capabilities, all annotations are designed to be ignored if an unsupported annotation (or annotation parameter) is detected. Multiple patterns can have the same annotation type, in this case the Viewers component adds all the corresponding results to the viewer.
  
Line 15: Line 14:
 
# The <code>Edge</code> annotation is used on patterns whose results describe a generic edge reference between Items. ''E.g., in case of Zest GraphViewers the ContentProvider will return these results as graph edges.''
 
# The <code>Edge</code> annotation is used on patterns whose results describe a generic edge reference between Items. ''E.g., in case of Zest GraphViewers the ContentProvider will return these results as graph edges.''
 
# The <code>Format</code> annotation is used to define additional formatting. It is expected to be added next to <code>Item</code> and/or <code>Edge</code> annotations.
 
# The <code>Format</code> annotation is used to define additional formatting. It is expected to be added next to <code>Item</code> and/or <code>Edge</code> annotations.
 +
 +
== Binding Results to Viewers ==
 +
=== Viewers Sandbox ===
 +
# Open the Query Explorer and Viewers Sandbox views.
 +
# Add your instance model and query definitions to the Query Explorer.
 +
# Select the ''Initialize IncQuery Viewers'' from a query definition in the popup menu over any selected element in the main area.
 +
#* '''Warning''': the IncQuery Sandbox does not update itself in case of pattern changes (as opposed to the Query Explorer).
 +
#* The ''Initialize'' command uses the actual filter settings, but the Sandbox does not update itself if the filters are updated.
 +
=== Programmatic Binding ===
 +
# Add a dependency to <code>org.eclipse.incquery.viewers.runtime</code> (and <code>org.eclipse.incquery.viewers.runtime.zest</code> if necessary) to your plug-in.
 +
# Create a <code>ViewerModel</code> from a group of patterns.
 +
# Use the corresponding bind methods from <code>IncQueryViewers</code> or <code>IncQueryGraphViewers</code> classes on a manually created <code>Viewer</code> together with the <code>ViewerModel</code> and your instance model.
 +
#* The ViewerModel instance can be re-used between different bindings.
 +
#* If the filters added to the ViewerModel are changed, the bindings will become obsolete, and have to be redone.
  
 
= Examples =
 
= Examples =
Line 27: Line 40:
 
# <code>pattern transitiveSuperClass(sub : Class, sup : Class)</code> - for listing all indirect superclass relations between classes (but not the direct ones)
 
# <code>pattern transitiveSuperClass(sub : Class, sup : Class)</code> - for listing all indirect superclass relations between classes (but not the direct ones)
  
=== JFace List Viewer example ===
+
The visualizer illustrations below correspond to the [http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/papyrus-uml/org.eclipse.incquery.examples.uml.queries/testmodels/Testmodel.uml Test model] in the repository.
  
 +
=== JFace List Viewer example ===
 
<source lang="java">
 
<source lang="java">
 
@Item(item = cl, label="Empty class $cl$")
 
@Item(item = cl, label="Empty class $cl$")
Line 40: Line 54:
 
}
 
}
 
</source>
 
</source>
 +
[[Image:Incquery_Viewers_Demo_UML_List.png]]
 
=== Binding contents to a JFace Tree Viewer ===
 
=== Binding contents to a JFace Tree Viewer ===
 
<source lang="java">
 
<source lang="java">
Line 46: Line 61:
 
...
 
...
 
}
 
}
 
 
@Item(item = cl, label="Empty class $cl$")
 
@Item(item = cl, label="Empty class $cl$")
 
pattern emptyClass(cl : Class) {
 
pattern emptyClass(cl : Class) {
 
...
 
...
 
}
 
}
 
 
@Item(item = cl, label = "Class $cl$")
 
@Item(item = cl, label = "Class $cl$")
 
pattern nonEmptyClass(cl : Class) {
 
pattern nonEmptyClass(cl : Class) {
Line 57: Line 70:
 
}
 
}
 
</source>
 
</source>
 +
[[Image:Incquery_Viewers_Demo_UML_Tree.png]]
 +
 +
Additional notes
 +
 +
* In addition to basic binding support where all items appear both as root and child items as needed, it is possible to limit Items to appear only as root or only as child positions using the hierarchy parameter.
 +
* If creating a TreeViewer binding programmatically, and an item appear in multiple places (e.g. it has multiple parents), make sure you set up the <code>useHashLookup</code> property of your TreeViewer, otherwise the update of the TreeViewer would fail.
 +
 
=== Zest Graph Viewer example===
 
=== Zest Graph Viewer example===
 
<source lang="java">
 
<source lang="java">
Line 64: Line 84:
 
...
 
...
 
}
 
}
 
 
@Edge(source = sup, target = sub)
 
@Edge(source = sup, target = sub)
 
pattern transitiveSuperClass(sub : Class, sup : Class) {
 
pattern transitiveSuperClass(sub : Class, sup : Class) {
 
...
 
...
 
}
 
}
 
 
@Item(item = cl, label="Empty class $cl$")
 
@Item(item = cl, label="Empty class $cl$")
 
@Format(color="#3770d7", textColor = "#ffffff")
 
@Format(color="#3770d7", textColor = "#ffffff")
Line 75: Line 93:
 
...
 
...
 
}
 
}
 
 
@Item(item = cl, label = "Class $cl$")
 
@Item(item = cl, label = "Class $cl$")
 
pattern nonEmptyClass(cl : Class) {
 
pattern nonEmptyClass(cl : Class) {
Line 81: Line 98:
 
}
 
}
 
</source>
 
</source>
 
+
[[Image:Incquery_Viewers_Demo_UML_Zest.png]]
== Binding Results to Viewers ==
+
=== Viewers Sandbox ===
+
# Open the Query Explorer and Viewers Sandbox views.
+
# Add your instance model and query definitions to the Query Explorer.
+
# Select the ''Initialize IncQuery Viewers'' from a query definition in the popup menu over any selected element in the main area.
+
#* '''Warning''': the IncQuery Sandbox does not update itself in case of pattern changes (as opposed to the Query Explorer).
+
#* The ''Initialize'' command uses the actual filter settings, but the Sandbox does not update itself if the filters are updated.
+
=== Programmatic Binding ===
+
# Add a dependency to <code>org.eclipse.incquery.viewers.runtime</code> (and <code>org.eclipse.incquery.viewers.runtime.zest</code> if necessary) to your plug-in.
+
# Create a <code>ViewerModel</code> from a group of patterns.
+
# Use the corresponding bind methods from <code>IncQueryViewers</code> or <code>IncQueryGraphViewers</code> classes on a manually created <code>Viewer</code> together with the <code>ViewerModel</code> and your instance model.
+
#* The ViewerModel instance can be re-used between different bindings.
+
#* If the filters added to the ViewerModel are changed, the bindings will become obsolete, and have to be redone.
+
  
 
== Ecore visualization ==
 
== Ecore visualization ==
 +
We have developed another demonstrating example in the context of the [[EMFIncQuery/UserDocumentation/HeadlessExecution|Headless Execution]] example. As the queries of the Headless Example match against .ecore models (that is, EMF metamodels), the visualization example below can be used to visualize metamodels and containment relationships in a simple way. This example is focused mainly on the 2D graph visualization supported by the GEF4 Zest framework.
 +
 +
=== Specification ===
 +
The example defines two graph node types and three graph edge types ([http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/headlessQueries.incquery/src/headless/headlessQueries.eiq code]):
 +
* Nodes are EPackage and EClass instances
 +
* Edges are '''classes contained in a package''', '''subpackage''' relationships, and a special transitive containment relationship between packages and classes '''classes in a package hierarchy''' that enumerates all classes that are contained by a root package or some subpackage (transitively) below this root.
 +
 +
<source lang="java">
 +
@Item(item = p, label = "P: $p.name$")
 +
@Format(color = "#791662", textColor = "#ffffff")
 +
pattern ePackage(p : EPackage) { EPackage(p); }
 +
 +
@Item(item = ec, label = "EC: $ec.name$")
 +
@Format(color = "#e8da2c")
 +
pattern eClass(ec : EClass) { EClass(ec); }
 +
 +
@Edge(source = p, target = ec, label = "classIn")
 +
pattern classesInPackage(p : EPackage, ec: EClass) { EPackage.eClassifiers(p,ec); }
 +
 +
@Edge(source = p, target = sp, label = "sub")
 +
pattern subPackage(p: EPackage, sp: EPackage){ EPackage.eSubpackages(p,sp); }
 +
 +
@Edge(source = rootP, target = containedClass, label = "classIn+")
 +
@Format(color = "#0033ff")
 +
pattern classesInPackageHierarchy(rootP: EPackage, containedClass: EClass)
 +
{
 +
find classesInPackage(rootP,containedClass);
 +
} or {
 +
find subPackage+(rootP,somePackage);
 +
find classesInPackage(somePackage,containedClass);
 +
}
 +
</source>
 +
 +
=== Visualization ===
 +
The visualization of a simple test model ([http://git.eclipse.org/c/incquery/org.eclipse.incquery.examples.git/tree/headless/headlessQueries.incquery/testmodels/Test.ecore file]) is illustrated in the figure.
 +
 +
[[Image:Headless_viewers.png|right|700px|Ecore metamodel visualization with IncQuery Viewers]]
  
TODO
+
Observe the following details:
 +
* EPackages and EClasses are shown in purple and yellow, respectively
 +
* direct relationships (subpackage and contained packages) are shown in grey
 +
* inferred transitive containment relationships are shown in blue

Revision as of 04:30, 24 May 2013

Using IncQuery Viewers

The goal of the IncQuery Viewers component is to help developing model-driven user interfaces by filling and updating model viewer results with the results of model queries. The implementation relies on (and is modeled after) the JFace Data binding and JFace Viewers libraries.

The IncQuery Viewers component can bind the results of queries to various JFace Viewers: JFace ListViewer and TreeViewers are currently supported, while TableViewer support is planned (see [403325] for current state). Additionally, by installing extra features for the extra update site Zest GraphViewers (based on GEF4 Zest) are also supported.

To select which patterns are used to determine the model elements to bind, several annotations are used by the framework. These annotations also allow to add labels and formatting to the viewers.

Using Viewer Annotations for Specifying the View Model

The IncQuery Viewers component uses four different annotations to bind query results to various viewers. As the different viewers have vastly different capabilities, all annotations are designed to be ignored if an unsupported annotation (or annotation parameter) is detected. Multiple patterns can have the same annotation type, in this case the Viewers component adds all the corresponding results to the viewer.

  1. The Item annotation is used on patterns whose results will be the main elements to display in the viewers. E.g., in case of JFace Viewers the ContentProvider should return all the items.
  2. The ContainsItem annotation is used on patterns whose results describe the the containment references between Items. E.g., in case of JFace TreeViewers the ContentProvider has to return these as child references.
  3. The Edge annotation is used on patterns whose results describe a generic edge reference between Items. E.g., in case of Zest GraphViewers the ContentProvider will return these results as graph edges.
  4. The Format annotation is used to define additional formatting. It is expected to be added next to Item and/or Edge annotations.

Binding Results to Viewers

Viewers Sandbox

  1. Open the Query Explorer and Viewers Sandbox views.
  2. Add your instance model and query definitions to the Query Explorer.
  3. Select the Initialize IncQuery Viewers from a query definition in the popup menu over any selected element in the main area.
    • Warning: the IncQuery Sandbox does not update itself in case of pattern changes (as opposed to the Query Explorer).
    • The Initialize command uses the actual filter settings, but the Sandbox does not update itself if the filters are updated.

Programmatic Binding

  1. Add a dependency to org.eclipse.incquery.viewers.runtime (and org.eclipse.incquery.viewers.runtime.zest if necessary) to your plug-in.
  2. Create a ViewerModel from a group of patterns.
  3. Use the corresponding bind methods from IncQueryViewers or IncQueryGraphViewers classes on a manually created Viewer together with the ViewerModel and your instance model.
    • The ViewerModel instance can be re-used between different bindings.
    • If the filters added to the ViewerModel are changed, the bindings will become obsolete, and have to be redone.

Examples

UML visualization

To illustrate the approach, a simple example was prepared in the [repository of the EMF-IncQuery project] based on UML class diagrams. The examples are relying on the notion of example classes: UML classes that do not have operations or properties (neither in their parent classes).

To present most features of the framework, four specific patterns are used (for the entire implementations visit the git repository):

  1. pattern emptyClass (cl : Class) - for listing all empty classes in the model
  2. pattern nonEmptyClass(cl : Class) - for listing all classes in the model, that are not empty
  3. pattern superClass(sub : Class, sup : Class) - for listing all direct superclass relations between classes
  4. pattern transitiveSuperClass(sub : Class, sup : Class) - for listing all indirect superclass relations between classes (but not the direct ones)

The visualizer illustrations below correspond to the Test model in the repository.

JFace List Viewer example

@Item(item = cl, label="Empty class $cl$")
pattern emptyClass(cl : Class) {
...
}
 
@Item(item = cl, label = "Class $cl$")
pattern nonEmptyClass(cl : Class) {
...
}

Incquery Viewers Demo UML List.png

Binding contents to a JFace Tree Viewer

@ContainsItem(container = sup, item = sub)
pattern superClass(sub : Class, sup : Class) {
...
}
@Item(item = cl, label="Empty class $cl$")
pattern emptyClass(cl : Class) {
...
}
@Item(item = cl, label = "Class $cl$")
pattern nonEmptyClass(cl : Class) {
...
}

Incquery Viewers Demo UML Tree.png

Additional notes

  • In addition to basic binding support where all items appear both as root and child items as needed, it is possible to limit Items to appear only as root or only as child positions using the hierarchy parameter.
  • If creating a TreeViewer binding programmatically, and an item appear in multiple places (e.g. it has multiple parents), make sure you set up the useHashLookup property of your TreeViewer, otherwise the update of the TreeViewer would fail.

Zest Graph Viewer example

@Edge(source = sup, target = sub, label = "direct")
@Format(color = "#7f004b", lineWidth = 2)
pattern superClass(sub : Class, sup : Class) {
...
}
@Edge(source = sup, target = sub)
pattern transitiveSuperClass(sub : Class, sup : Class) {
...
}
@Item(item = cl, label="Empty class $cl$")
@Format(color="#3770d7", textColor = "#ffffff")
pattern emptyClass(cl : Class) {
...
}
@Item(item = cl, label = "Class $cl$")
pattern nonEmptyClass(cl : Class) {
...
}

Incquery Viewers Demo UML Zest.png

Ecore visualization

We have developed another demonstrating example in the context of the Headless Execution example. As the queries of the Headless Example match against .ecore models (that is, EMF metamodels), the visualization example below can be used to visualize metamodels and containment relationships in a simple way. This example is focused mainly on the 2D graph visualization supported by the GEF4 Zest framework.

Specification

The example defines two graph node types and three graph edge types (code):

  • Nodes are EPackage and EClass instances
  • Edges are classes contained in a package, subpackage relationships, and a special transitive containment relationship between packages and classes classes in a package hierarchy that enumerates all classes that are contained by a root package or some subpackage (transitively) below this root.
@Item(item = p, label = "P: $p.name$")
@Format(color = "#791662", textColor = "#ffffff")
pattern ePackage(p : EPackage) { EPackage(p); }
 
@Item(item = ec, label = "EC: $ec.name$")
@Format(color = "#e8da2c")
pattern eClass(ec : EClass) { EClass(ec); }
 
@Edge(source = p, target = ec, label = "classIn")
pattern classesInPackage(p : EPackage, ec: EClass) { EPackage.eClassifiers(p,ec); }
 
@Edge(source = p, target = sp, label = "sub")
pattern subPackage(p: EPackage, sp: EPackage){ EPackage.eSubpackages(p,sp); }
 
@Edge(source = rootP, target = containedClass, label = "classIn+")
@Format(color = "#0033ff")
pattern classesInPackageHierarchy(rootP: EPackage, containedClass: EClass)
{
	find classesInPackage(rootP,containedClass);
} or {
	find subPackage+(rootP,somePackage);
	find classesInPackage(somePackage,containedClass);
}

Visualization

The visualization of a simple test model (file) is illustrated in the figure.

Ecore metamodel visualization with IncQuery Viewers

Observe the following details:

  • EPackages and EClasses are shown in purple and yellow, respectively
  • direct relationships (subpackage and contained packages) are shown in grey
  • inferred transitive containment relationships are shown in blue

Copyright © Eclipse Foundation, Inc. All Rights Reserved.