# Extending the Visualiser

## 1 Background

This page describes how to work with the Visualiser - the focus is on how to create visualizations of your own data.

### 1.1 Groups and Members

The simplest unit in the visualization is called a member. Members are always contained in a group (exactly the same as java source files can be grouped into packages.) Dont put groups into groups, it is not supported. The interfaces that the Visualiser works with are IMember and IGroup. There are simple implementations of these interfaces in the Visualiser, called SimpleMember and SimpleGroup. Unless there is a good reason not to, it is advised that you use these implementations in your extensions. If you really need to include some meta-information about members/groups they should be subclassed and your Visualiser extensions should use the subclasses.

#### Groups and Members represented in Member View:

#### Groups and Members represented in Group View:

For more about group and member view, see 'Using the Visualiser'.

### 1.2 Stripes

Stripes are used to represent information about a member. Stripes are each of a certain 'kind', which is distinguished by their color. The Visualiser Menu view displays the kind-color pairs.

## 2 Writing a Provider

### 2.1 Architecture

In order to extend the Visualiser, you have to understand a little about its architecture. The original Visualiser showed AspectJ and Java source files as the bars in the Visualiser, whilst any advice affecting those source files was shown as colored lines across the bars. The new Visualiser is entirely decoupled from AspectJ and even the JDT. You can visualize markups on whatever you want. The key two interfaces are:

- IContentProvider The implementer of this class is responsible for telling the Visualiser what the different bars are in the Visualiser.
- IMarkupProvider The implementer of this class is responsible for telling the Visualiser what colored marks (called stripes) should be placed on each member.

Extension points have been provided in the Visualiser for specifying the implementations of these two interfaces. Because it can be a bit daunting to get to grips with, the default Visualiser includes two simple implementations of these classes, called SimpleContentProvider and SimpleMarkupProvider respectively the source for these modules is documented to give you a basic idea of what they do. On their own, these implementations do absolutely nothing they just provide a framework that implements IContentProvider and IMarkupProvider they are all ready to manage a data model of members and groups, they just have no data in their models.

To show you how to utilise the simple provider implementations, the plugin includes a file based variant of each, FileContentProvider and FileMarkupProvider these are subclasses of the SimpleContentProvider and SimpleMarkupProvider respectively. The source for these is fully documented they basically read the content of two files, one for content and one for markups, and populate the model that exists in the superclasses from these.

### 2.2 Dynamic Providers and forcing an update

The providers that have been discussed so far have a model that does not change post initialization. If a new provider is created where the model does change, it will need to force a Visualiser update, through the API call:

VisualiserPlugin.refreshVisualisation()

Dynamic providers should use this method if their model changes post initialization.

## 3 Registering your provider

Providers are registerd through Eclipse's extension point mechanism. You will need to define your extension in the plugin.xml file for your plugin. To see the schema for the extension point and an example click here.

## 4 Other features

After reading the previous sections, you should be able to get your own data on the screen. But there are still a lot of things you might be interested in doing

### 4.1 Color Management

The SimpleMarkupProvider automatically manages the colors for your stripes. In order to manage them yourself, the two methods to implement from the IMarkupProvider interface are:

Color getColorFor(String kind);

void setColorFor(String kind, Color color);

The second of the two methods is called when the user interacts with the Visualiser Menu, clicking the colored square next to a kind this actually pops up in an in place color picker and after the user has selected an appropriate color, the call is made to setColorFor to tell the markup implementer that it has happened.
Alternatively you can associate a color palette with your provider via the providers extension point.

### 4.2 Handling clicks

By default, when in the group view and the user selects a group (by left mouse clicking), the Visualiser jumps to a member view for that group. If the user left clicks on a member in the member view then the Visualiser jumps to a subselect view of just that member. If the user right mouse clicks, the Visualiser returns to what it was previously showing (so, if we selected a group and jumped to a member view within that group with a left click then a right click will take us back to the group view).

Both the content provider interface and markup provider interfaces provide a callback method which is invoked when one of these click events occurs. In IMarkupProvider:

public boolean processMouseclick(

String fullmembername,

Stripe stripe,

String exactKind,

int buttonClicked);

This handler is only called if the user actually clicks on a stripe/markup upon one of the members in the view. The parameters are as follows:

- The fullmembername is the dotted notation for the member name, so <group>.<member>.

- The stripe is the instance of Stripe that represents that horizontal strip on the member this might be a compound stripe if there are multiple colors on the line, which is why we have

- exactKind is the exact kind from stripe that was clicked upon. If the stripe had kinds S1, S2, S3 then exactKind might be S2.

- buttonClicked is 1,2 or 3 depending on whether the mouse click was left, middle or right button.

The return value indicates if the handler wants to allow the normal Visualiser behaviour on button clicks to be performed (i.e. jumping group -> member view, etc) returning false means the view wont change.

In the IContentProvider:

public boolean processMouseclick(

String fullmembername,

boolean markupWasClicked,

int buttonClicked);

This handler is called if the user clicks anywhere on a member not just when they click on a colored stripe/markup. The parameters are as follows:

The fullmembername is the dotted notation for the member name, so <group>.<member>.

markupWasClicked indicates if the user did actually click a colored stripe on the member. If this is true, then you know the other handler in IMarkupProvider is also going to be called.

buttonClicked is 1,2 or 3 depending on whether the mouse click was left, middle or right button.

The return value indicates if the handler wants to allow the normal Visualiser behaviour on button clicks to be performed (i.e. jumping from group view -> member view, etc) returning false means the view wont change.

What might button click handlers do? Well, perhaps the model changes when the user clicks? Or somewhere else in the UI something changes. In the JDT provider for example, where the members are java source files, the handler might open an editor on the source file.

Remember that depending on whether a stripe is clicked within in a member, you might get one or two chances to handle a mouse click the markup provider will get called if a stripe was clicked. The content provider will always get called.

## 5 Renderers

The Visualiser comes with several renderers, which draw the bars in different ways.

#### Default renderer:

#### Cylinder renderer:

It is relatively easy to add your own renderer if you wish to. There is a simple extension point and a single interface to provide an implementer of. In addition you can subclass one of the provided renderers. To see the schema click here.

## 6 Color Palettes

A color palette is a set of colors that the Visualiser uses to select the colors for skinds from. A default palette is provided with the Visualiser. You can also provide your own palette for your provider (or another). This may be useful if you want to exclude certain colors or tones, or limit the palette in any other way. To see the schema for this extension point click here.

## 7 Forthcoming providers

In addition to the included providers, we are also working on a CVS provider.

If you come up with a generally useful provider, please let us know.