| <!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'> </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'> </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'> </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'> |
| </span>The new Visualiser is entirely decoupled from AspectJ and even the |
| JDT.<span style='mso-spacerun:yes'> </span>You can visualize markups on |
| whatever you want.<span style='mso-spacerun:yes'> </span>The key two interfaces are: </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'> |
| </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'> </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'> </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'> </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'> </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'> </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'> </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'> </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'> </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'> </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'> </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'> </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:#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'> </span>The |
| parameters are as follows:</p> |
| |
| <UL> |
| <LI> |
| <p>The fullmembername is the dotted notation for the member name, so <group>.<member>. </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>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 -> 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'> </span>The |
| parameters are as follows:</p> |
| |
| <p>The fullmembername is the dotted notation for the member name, so <group>.<member>. |
| </p> |
| <p>markupWasClicked indicates if the user did actually click a colored stripe |
| on the member.<span style='mso-spacerun:yes'> </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. </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 -> |
| member view, etc) returning false means the view wont change.</p> |
| <p>What |
| might button click handlers do?<span style='mso-spacerun:yes'> </span>Well, |
| perhaps the model changes when the user clicks? Or somewhere else in the UI |
| something changes.<span style='mso-spacerun:yes'> </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'> </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 stripe kinds from. A default palette is provided with the Visualiser. |
| You can also provide your own palette implementation. 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'> </span></p> |
| <p>If you come up with a generally useful provider, please let us know.<BR> |
| <BR> |
| </p> |
| </BODY> |
| </HTML> |
