<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder V6.0.2 for Windows">
<META http-equiv="Content-Style-Type" content="text/css">


<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
<TITLE>Extending the Visualiser</TITLE>
</HEAD>
<BODY>
<H1 style="text-align:center" align="center">Extending the Visualiser</H1>
<a name="background"></a>
<H2><a name="background">1 Background</a></H2>
<p>This page describes how to work with the Visualiser - the focus is on how
to create visualizations of your own data.</p>
<H3> <I>1.1 Groups and Members</I></H3>
<p>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.<span
style='mso-spacerun:yes'>&nbsp; </span>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.<span style='mso-spacerun:yes'>&nbsp; </span>Unless there is a good reason not to, it is advised that you use these
implementations in your extensions.<span style='mso-spacerun:yes'>&nbsp; </span>If you really need to include some meta-information about members/groups
 they should be subclassed and your Visualiser extensions should use the
subclasses.<BR>
<h4>Groups and Members represented in Member View:</h4>
<BR>
<P><IMG src="groupmember2.png" border="0"></P>
<h4>Groups and Members represented in Group View:</h4>
<BR>
<P><IMG src="groupmember.png" border="0"></P>
<P><BR>
For more about group and member view, see <A href="../userguide/main.html">'Using the Visualiser'</A>.</P>
<BR>

<H3> <I>1.2 Stripes</I></H3>
<p>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.</p>

<a name="provider"></a>
<H2><a name="provider">2 Writing a Provider</a></H2>
<H3><I>2.1 Architecture</I></H3>
<p>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.<span style='mso-spacerun:yes'>&nbsp;
</span>The new Visualiser is entirely decoupled from AspectJ and even the
JDT.<span style='mso-spacerun:yes'>&nbsp; </span>You can visualize markups on
whatever you want.<span style='mso-spacerun:yes'>&nbsp; </span>The key two interfaces are:&nbsp;</p>

<p style='margin-left:36.0pt;text-indent:-18.0pt;mso-list:l0 level1 lfo1;
tab-stops:list 36.0pt'>


<ul><li>
IContentProvider  The implementer of this
class is responsible for telling the Visualiser what the different bars are in
the Visualiser.
</li><li>IMarkupProvider  The implementer of this class is responsible for telling
  the Visualiser what colored marks (called stripes) should be placed on
  each member.<span style='mso-spacerun:yes'>&nbsp;
</span>
</li></ul>
<p>Extension
points have been provided in the Visualiser for specifying the implementations
of these two interfaces.<span style='mso-spacerun:yes'>&nbsp; </span>Because it can
be a bit daunting to get to grips with, the default Visualiser includes two
simple implementations of these classes, called <b>SimpleContentProvider</b> and <b>SimpleMarkupProvider</b>
respectively  the source for these modules is documented to give you a basic
idea of what they do.<span style='mso-spacerun:yes'>&nbsp; </span>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.</p>

<p>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.<span style='mso-spacerun:yes'>&nbsp; </span>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.</p>

<H3><I>2.2 Dynamic Providers and forcing an update</I></H3>

<p>The providers that have been discussed so far have a model that does not
change post initialization.<span style='mso-spacerun:yes'>&nbsp; </span>If a new provider is created where the model does change, it will need
to force a Visualiser update, through the API call:</p>

<p style='text-indent:36.0pt'><span lang=EN-US
style='font-size:9.0pt;font-family:"Courier New";color:black;background:white;
mso-highlight:white'>VisualiserPlugin.refreshVisualisation()</span></p>

<p>Dynamic providers should use this method if their model changes post initialization.<span style='mso-spacerun:yes'></span></p>

<a name="register"></a>
<H2><a name="register">3 Registering your provider</a></H2>
<p>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 <a href="../org_eclipse_contribution_visualiser_providers.html">click here</a>.</p>


<a name="features"></a>
<H2><a name="features">4 Other features</a></H2>
<p>After reading the previous sections, you should be able to get your own data on the
screen.<span style='mso-spacerun:yes'>&nbsp; </span>But there are still a lot of
things you might be interested in doing</p>

<H3><I>4.1 Color Management</I></H3>

<p>The SimpleMarkupProvider automatically manages the colors for your stripes.<span style='mso-spacerun:yes'>&nbsp; </span>In order to manage them yourself, the two methods to implement from the IMarkupProvider interface are:</p>

<p><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";
background:white;mso-highlight:white'><span style='mso-tab-count:1'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span><span
style='color:black'>Color</span> <span style='color:black'>getColorFor(String</span>
<span style='color:black'>kind);</span></span><span lang=EN-US
style='font-size:9.0pt;font-family:"Courier New";color:black'></span></p>

<p style='mso-layout-grid-align:none;text-autospace:none'><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'><span style='mso-tab-count:1'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; </span><span
style='color:#7F0055'>void</span> <span style='color:black'>setColorFor(String</span>
<span style='color:black'>kind,</span> <span style='color:black'>Color</span> <span
style='color:black'>color);</span></span></p>

<p>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.<BR>
<BR>
Alternatively you can associate a <A href="#palettes">color palette</A> with your provider via the providers extension point.</p>

<H3><I>4.2 Handling clicks</I></H3>

<p>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.<span
style='mso-spacerun:yes'>&nbsp; </span>If the user left clicks on a member in the
member view then the Visualiser jumps to a subselect view of just that
member.<span style='mso-spacerun:yes'>&nbsp; </span>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).</p>

<p>Both the content provider interface and markup provider interfaces provide a
callback method which is invoked when one of these click events occurs.<span
style='mso-spacerun:yes'>&nbsp; </span>In IMarkupProvider:</p>

<p style='mso-layout-grid-align:none;text-autospace:none'><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:#7F0055;
background:white;mso-highlight:white'>public boolean</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>processMouseclick(</span></span></p>
<p style='text-indent:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";
color:black;background:white;mso-highlight:white'>String</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>fullmembername,</span> </span></p>
<p style='margin-left:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";
color:black;background:white;mso-highlight:white'>Stripe</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>stripe,</span> </span></p>
<p style='margin-left:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";
color:black;background:white;mso-highlight:white'>String</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>exactKind,</span> </span></p>
<p style='margin-left:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:
"Courier New";color:#7F0055;background:white;mso-highlight:white'>int</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>buttonClicked);</span></span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'></span></p>

<p>This handler is <u>only</u> called if the user actually clicks on a stripe/markup
upon one of the members in the view.<span style='mso-spacerun:yes'>&nbsp; </span>The
parameters are as follows:</p>

<UL>
  <LI>
  <p>The fullmembername is the dotted notation for the member name, so &lt;group&gt;.&lt;member&gt;. </p></li>
  <LI><p>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</p>
</li>
  <LI><p>exactKind is the exact kind from stripe that was clicked upon.<span
style='mso-spacerun:yes'>&nbsp; </span>If the stripe had kinds S1, S2, S3 then
exactKind might be S2.</p>
</li>
  <LI><p>buttonClicked is 1,2 or 3 depending on whether the mouse click was left,
middle or right button. </p>
</li>
</UL>

<p>The
return value indicates if the handler wants to allow the normal Visualiser
behaviour on button clicks to be performed (i.e. jumping group -&gt; member
view, etc)  returning false means the view wont change.</p>
<p>In
the IContentProvider:</p>
<p style='mso-layout-grid-align:none;text-autospace:none'><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";color:#7F0055;
background:white;mso-highlight:white'>public boolean</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>processMouseclick(</span></span></p>
<p style='text-indent:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:"Courier New";
color:black;background:white;mso-highlight:white'>String</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>fullmembername,</span> </span></p>
<p style='margin-left:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:
"Courier New";color:#7F0055;background:white;mso-highlight:white'>boolean</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>markupWasClicked,</span> </span></p>
<p style='margin-left:36.0pt;mso-layout-grid-align:none;
text-autospace:none'><span lang=EN-US style='font-size:9.0pt;font-family:
"Courier New";color:#7F0055;background:white;mso-highlight:white'>int</span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New";background:white;
mso-highlight:white'> <span style='color:black'>buttonClicked);</span></span><span
lang=EN-US style='font-size:9.0pt;font-family:"Courier New"'></span></p>
<p>This handler is called if the user clicks anywhere on a member  not just
when they click on a colored stripe/markup.<span style='mso-spacerun:yes'>&nbsp; </span>The
parameters are as follows:</p>

<p>The fullmembername is the dotted notation for the member name, so &lt;group&gt;.&lt;member&gt;.
</p>
<p>markupWasClicked indicates if the user did actually click a colored stripe
on the member.<span style='mso-spacerun:yes'>&nbsp; </span>If this is true, then you know the other handler in IMarkupProvider is
also going to be called.</p>

<p>buttonClicked is 1,2 or 3 depending on whether the mouse click was left,
middle or right button. &nbsp;</p>
<p>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 -&gt;
member view, etc)  returning false means the view wont change.</p>
<p>What
might button click handlers do?<span style='mso-spacerun:yes'>&nbsp; </span>Well,
perhaps the model changes when the user clicks? Or somewhere else in the UI
something changes.<span style='mso-spacerun:yes'>&nbsp; </span>In the JDT provider
for example, where the members are java source files, the handler might open an
editor on the source file.</p>
<p>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.<span style='mso-spacerun:yes'>&nbsp; </span>The content provider will
always get called.</p>
<H2><a name="renderers">5 Renderers</a></H2>
<p>The Visualiser comes with several renderers, which draw the bars in different
ways.
<h4>Default renderer:</h4>
<IMG src="default.png" width="629" height="291" border="0"><BR>
<h4>
Cylinder renderer:</h4>
<IMG src="cylinder.png" width="629" height="290" border="0"><BR>
<BR>
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 
<A href="../org_eclipse_contribution_visualiser_renderers.html">here</A>.
<H2><a name="palettes">6 Color Palettes</a></H2>
<p>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 <A href="../org_eclipse_contribution_visualiser_palettes.html">here</A>.</p>
<a name="forthcoming"></a>
<H2><a name="forthcoming">7 Forthcoming providers</a></H2>
<p>In addition to the included providers, we are also
working on a CVS provider.<span
style='mso-spacerun:yes'>&nbsp;</span></p>
<p>If you come up with a generally useful provider, please let us know.<BR>
<BR>
</p>
</BODY>
</HTML>