MoDisco/Components/ModelBrowser/Documentation/0.9

• OverviewDocumentation 0.7Documentation 0.8Documentation 0.9
• New & Noteworthy

MoDisco

Website

Download

Community

Mailing List • Forums

Bugzilla

Open

Help Wanted

Bug Day

Contribute

Browse Source • Project Set File

Browser

Overview

The browser surface is separated in two panes. The left one displays a list of meta-classes, and the right one shows instances of the selected meta-class (that is, model elements).

At the top of each pane, a toolbar allows you to quickly change display options relative to that pane.

Features

Links

You can follow links between model elements by expanding the links tree nodes. Links appear for associations, aggregations and the EMF container. The tree representing the model is infinite.

An icon indicates the link type, and the number of instances under the link is displayed in parentheses.

icon	meaning
	bidirectional link
	unidirectional link
	bidirectional aggregation link
	unidirectional aggregation link
	bidirectional inverse aggregation link
	link to the EMF container of the element (eContainer); this link is not defined in the metamodel

The source of the link is always its parent in the tree, and the targets are its children.

Display options

You can use the buttons at the top of the Instances panel to set the following options (click on the down-pointing arrow to see hidden options):

icon	description
	Sort instances by name
	Show empty links (containing no instances)
	Show derived links
	Sort links by name
	Sort links by type
	Display full qualified meta-classes names
	Display multiplicities on links
	Show ordering
	Show opposite links
	Show a link to the container (which is not part of the metamodel definition)
	Show attributes as tree elements (in addition to the Properties view)
	Show empty attributes
	Show type of links

Meta-class list

The Types panel displays all the meta-classes of the opened model, with the number of instances for each meta-class. When you click on a meta-class, its instances are displayed in the Instances panel. Multi-selection of meta-classes is also supported.

You can use the buttons at the top of the Types panel to set the following options (click on the down-pointing arrow to see hidden options):

icon	description
	Show empty meta-classes
	Display instances of subclasses (for example, when an abstract meta-class is selected, instances of its derived classes are displayed)
	Show derivation tree
	Sort by name
	Sort by instance count
	Show full qualified names
	Group meta-classes by package

Browse

Right-click on a model element and select "Browse" to select the meta-class of this element in the Types panel and display this model element amongst its siblings of the same type. You can also press Enter while an element is selected to trigger this action.

Navigation history

When you navigate from one meta-class to another, or when you browse an instance, you can then go back and forth in navigation history by using the left and right arrows in the toolbar (or the Alt+Left, Alt+Right shortcuts).

Search

Type some text in the search bar and type Enter to filter the currently displayed instances by name. Press Escape to restore the view. Only instances of the currently selected meta-class are filtered.

Attributes

Attributes of the selected element are displayed in the Properties view. To show this view, double-click on a model element or right-click and select Show Properties View.

You can also display attributes directly in the model tree by activating the "Show Attributes" option in the right toolbar.

Accessibility

The font size can easily be changed by the click of a button in the main toolbar.

The first button makes the font larger, the second one smaller, and the third one restores the default font size. The base font is configurable in Eclipse preferences.

Customization

The MoDisco Model Browser can be customized through the use of customization files.

Description

A browser customization is a file contained in a MoDisco project inside your Eclipse Workspace, that has the uiCustom file extension. It can also be packaged inside a plug-in for distribution.

Browser customizations are useful to modify the appearance of any element from its associated metamodel when shown in the Model Browser.

For example, you could specify that all instances of a certain metaclass that have an attribute set to a given value should be displayed in bold with a specific icon.

How it works

Each customizable feature (color, boldness, text font, label, visibility, etc.) can have a default value and a list of conditional values, each one predicated by a query. The chosen value will be the one corresponding to the first condition that evaluated to "true", or the default value if all conditions were false or none was defined.

Furthermore, if no default value is provided for a feature, then a default default value will be used, which corresponds to the default behavior of the Model Browser. For example, if the "icon" feature is not customized, then the icon will be given by the "icon provider" extension point or a registered EMF adapter factory. If neither returned an icon, then a generated icon will be used.

Each value can itself be either a static value (a constant) or a value computed by a query.

Creating a customization

To create a new Browser customization, select a MoDisco project and click on New > Other.... Then select MoDisco > Browser Customization in the wizard. Give a name to the customization file, select the metamodel to which the customization will apply, and optionally choose which query sets will be available to the customization.

Editing a customization

To edit a customization, open its uiCustom file in Eclipse:

The Types section presents a tree of metaclasses from the customized metamodel, each one containing its attributes and references. It is similar to the metaclass pane in the MoDisco Model Browser.

When you select a metaclass, attribute or reference in the Types section, its customizable features are shown in the Customizations section.

The right side of the editor presents a list of buttons used for modifying the customizations shown in the Customizations section.

Editing a default value

To edit the default value of a feature, click on the feature in the Customizations section, and then click on the Edit feature value... button. Alternatively, you can double-click on the feature.

This opens a dialog where you can choose the value:

You can choose between:

• Default value : remove the customization on the feature's default value
• Static value : set the default value as a constant (which can be a boolean, a color, a font name, etc.)
• Value computed by a query : the default value of the feature will be dynamically computed at runtime by the query you select

Editing a conditional value

To add a conditional value to a feature, click on the feature in the Customizations section, then click on the Add... button. You will be presented with the following dialog:

As for default values, you can choose (in the right pane) between either a static value or a query which will yield the value at runtime.

In addition, you must select a query in the left pane that specifies the condition. This query must have a boolean return type, that will determine at runtime whether the value will be chosen or not.

Once you have added a condition, you can then use the Edit... button to change it, the Remove button to remove it, and the Up and Down buttons to reorder the conditions.

What can be customized?

customization	description
Is Visible	Whether to display the element
Label	The text that appears for this element
Text Font Name	The font used to display the label
Text Color	The color of the Label
Background Color	The background color of the Label
Type Icon	A 16x16 image to display as icon for this element
Is Bold	Whether to display the label in bold
Is Italic	Whether to display the label in italic
Is Underlined	Whether to underline the label
Is Struckthrough	Whether to strike through the label
Hide Metaclass Name	Whether to display the metaclass of each element as a prefix of its label ("[Metaclass]")
Visible In Types Panel	Whether the metaclass is visible in the "Types" panel
Overlay Icon	A 8x8 image to display over the type icon (for Facets only)
Collapse Link	Hide the tree node corresponding to the reference. If true the model elements are directly contained by the parent model element. If false the model elements are contained by a link node which is itself contained by the parent model element.

Expected queries return types

The queries are expected to return a value of the right type for the feature they customize:

Feature	Return type	Example	Comment
Bold, Italic, Struck-through, Underlined, Visible, Hide Metaclass Name	Boolean	true or false	The value can depend on attributes of the model element
Text Color, Background Color	String	"(255,128,128)"	Encoded as (red, green, blue) with integer intensity values in the interval [0,255]
Icon	String	"/MyModiscoProject/icons/myIcon.gif"	A path to a resource relative to the Workspace root, or in an installed plug-in (the first segment is then the plug-in name)
Label	String	"MyClass (public, final) [proxy]"	Typically, the query can add information about attributes or references on the model element

How to customize a Facet

A facet is a kind of meta-class (EClass) and a facet set a kind of meta-model (EPackage). The facet sets are represented in the meta-model list by their nsURI. To customize a facet set you just have to create a customization pointing to its nsURI.

Architecture

UI Core

Plug-in "org.eclipse.gmt.modisco.infra.browser.uicore" contains the core parts of the browser, that can be integrated in any tree viewer. It provides a tree content provider, a label provider, and a customization manager.

CustomizableModelContentProvider and CustomizableModelLabelProvider are abstract classes that must be sub-classed, providing an instance of a CustomizationManager.

The CustomizationManager class is the entry point for customizing the way things look and behave in the browser, through:

• Browser customizations ("uiCustom" files)
• Facets ("facetSet" files)
• APIs to control options that would appear in the MoDisco Browser's toolbar (sort instances, show empty links, etc.)

If parameters are modified in CustomizationManager after the TreeViewer was displayed, the viewer must be refreshed explicitly to account for these changes.

You may also want to override method getRootElements in CustomizableModelContentProvider, to provide the EObjects you want to display at the root of the tree.

Pay attention to the fact that the elements in the JFace model are not directly EObjects, but objects internal to the browser. So, don't redefine the getElements method to return EObjects, since that wouldn't work.

EObject from selection

If you want to get an EObject from a selection, you must use an adapter like this:

EObject eObject = (EObject) Platform.getAdapterManager().getAdapter(selectedElement, EObject.class);

Selection from EObject

To select an EObject in a TreeViewer created using UiCore, you can't just create a StructuredSelection(eObject), since the TreeViewer is composed of elements that encapsulate the EObjects.

Instead, you can retrieve the wrapping element by doing something like this:

 public Object findElementForEObject(EObject eObjectToFind, TreeViewer treeViewer) {
   ITreeContentProvider contentProvider = (ITreeContentProvider) treeViewer
       .getContentProvider();
   Object[] elements = contentProvider.getElements(treeViewer.getInput());
   LinkedList<Object> elementsToHandle = new LinkedList<Object>();
   for (Object element : elements) {
     elementsToHandle.add(element);
   }
   while (!elementsToHandle.isEmpty()) {
     Object e = elementsToHandle.removeFirst();
     EObject eObject = (EObject) Platform.getAdapterManager().getAdapter(e, EObject.class);
     if (eObject != null && eObject.equals(eObjectToFind)) {
       return e;
     }
     if (contentProvider.hasChildren(e)) {
       Object[] children = contentProvider.getChildren(e);
       if (children != null) {
         for (Object child : children) {
           elementsToHandle.addLast(child);
         }
       }
     }
   }
   return null;
 }

Context menu / Selection provider

If you need to use a selection provider, for example if you want to add a context menu on your UiCore viewer, you can use UnwrappingSelectionProvider :

getSite().registerContextMenu(MENU_ID, contextMenu, new UnwrappingSelectionProvider(treeViewer));

UnwrappingSelectionProvider also offers static methods should you need them:

• ISelection unwrapSelection(ISelection selection)
• Object unwrapElement(Object element)

prototype to avoid browser freezing with virtual tree

Here is the description of a strategy that moves all computations previously done in the UI thread (in the content and label providers) into background jobs. It relies on the SWT.VIRTUAL style for the SWT Tree, that allows using a lazy content provider (ILazyTreeContentProvider). Together with a label provider that extends CellLabelProvider, that allows doing asynchronous updates (again, in order to not block the UI thread).

It works like this: JFace asks for an update (through the content or label provider), that is enqueued on one of the Jobs (round-robin with the number of Jobs equal to the number of available processors). Once the information is computed, it is applied on the UI thread (mandatory with SWT). These updates are batched in order to minimize the number of switches to the UI thread.

With this strategy implemented, the browser does not freeze anymore, but it is unfortunately a lot slower on Windows. This seems currently unavoidable on Windows (see Bug 129457 - Virtual Tree very slow).

This prototype is available on a branch: https://dev.eclipse.org/svnroot/modeling/org.eclipse.mdt.modisco/plugins/branches/browser_lazy