blob: 5336577acf1508bceff089a16c6c51cdcba13b78 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta name="generator" content="HTML Tidy, see www.w3.org">
<title>Visual Editor Tutorial</title>
<link rel="stylesheet" type="text/css"
href="../default_style.css">
<style type="text/css">
.PictureParagraph { margin-left: 10% }
.PictureStyle { border-style: ridge; border-width: 1px; padding: 1px }
</style>
</head>
<body link="#0000ff" vlink="#800080">
<div align="right">
&nbsp; <font face="Times New Roman, Times, serif" size="2">Copyright
&copy; 2005 IBM and other contributors</font>
<table border="0" cellpadding="2" cellspacing="0" width="100%">
<tbody>
<tr>
<td colspan="2" align="left" bgcolor="#0080c0" valign="top">
<b><font face="Arial,Helvetica"><font color="#ffffff">&nbsp;Eclipse
Corner Article</font></font></b></td>
</tr>
</tbody>
</table>
</div>
<div align="left">
<h1><img src="../images/Idea.jpg" align="middle" height="86" width=
"120"></h1>
</div>
<p>&nbsp;</p>
<h1 align="center">Extending The Visual Editor:<br>
Enabling support for a custom widget</h1>
<blockquote>
<p><b>Summary</b><br>
This tutorial
shows how to extend the Visual Editor to support a custom widget.
It covers topics such as adding to the Visual Editor's palette,
building a BeanInfo class, and working with
EMF .override files to
introduce custom editor behavior.</p>
<p><b>Dave Orme, db4objects</b><br>
<b>Gili Mendel, IBM</b><br>
<b>Joe Winchester, IBM</b><br>
<font size="-1">June 20, 2005</font></p>
</blockquote>
<hr width="100%">
<h2><a name="Introduction"></a>Introduction</h2>
<p>The <a href="http://www.eclipse.org/vep">Visual Editor</a> project
provides reference implementations of a graphical user interface
builder for the JFC and SWT widget toolkits built around an extensible
framework.&nbsp; The motivation for this came from experience with
previous GUI builders that, while they provided high function end
points for particular toolkits, were unable to be adapted to support
custom behavior. This typically would be for areas of functionality
such as user defined widgets, new layout managers, or flexible code
generation patterns. A design goal of the Visual Editor is that is none
of its own custom behavior for any JFC or SWT classes is done with hard
coding and all logic that the VE employs to enable specific bespoke
function such dropping a control on a composite or showing feedback for
a particular layout manager is soft coded through extension points. The
intention is that the same techniques can be leveraged by anyone
wishing to employ similar techniques for their own scenario.</p>
<p>In this tutorial a 3.1 based Eclipse plugin&nbsp; <i>org.eclipse.ve.example.customwidget</i>
is created that illustrates some of the extension points of the visual
editor.&nbsp; To do this an SWT custom widget is built that combines a
Label, Text and Button in a single widget called <span
style="font-style: italic;">org.eclipse.ve.examples.customwidget.MyCustomPrompter</span>.&nbsp;</p>
<p><img style="width: 243px; height: 34px;" alt="CustomWidget"
src="images/CustomWidget.png"></p>
<p>MyCustomPrompter has two properties: <span
style="font-style: italic;">type</span> and <span
style="font-style: italic;">text</span>.&nbsp; These each have get and
set methods and can be used to configure the behavior of the Button and
the Text's text value.&nbsp; There is also a <span
style="font-style: italic;">ButtonSelectionEvent</span> event that is
raised when the prompter's button is pressed and listeners can register
for this callback using <span style="font-style: italic;">addButtonSelectionListener(ButtonSelectionListener
aListener);</span></p>
<p>In the absence of the plugin that this tutorial creates<span
style="font-family: monospace;">,</span> the <span
style="font-family: monospace;">MyCustomPrompter</span> widget can
still be used by a user who drops it onto an SWT composite by adding a
jar (or folder) containing the class to their Java project's build path<span
style="font-family: monospace;">.</span> Within the Visual Editor the
class can be selected by using <span style="font-style: italic;">ChooseBean</span>
from the palette to drop <span style="font-family: monospace;">MyCustomPrompter</span>
onto a composite. Through inheritance (<span
style="font-family: monospace;">MyCustomPrompter</span> extends <span
style="font-family: monospace;">org.eclipse.swt.widgets.Composite</span>)
the custom control will be rendered correctly and its properties will
be determined using JavaBeans<sup>TM</sup> reflection allowing it to be
modified using the Properties Viewer.&nbsp; The new event will also be
determined automatically through introspection by the Visual Editor and
available to the user to add callback logic to through the <span
style="font-style: italic;">Add Event</span> dialog.&nbsp;</p>
<p>This tutorial shows how to extend the edit experience by creating a
plugin that enables specific Visual Editor behavior over and above the
default that is determined through inheritance.&nbsp; This results in a
higher level edit experience for end users of the <span
style="font-style: italic;">MyCustomPrompter</span> class.&nbsp; The
examples given are purely for illustrative purposes only and to
highlight some of the available ways to extend the behavior of the
Visual Editor, and it is expected that the reader of this tutorial will
use it to learn the extension mechanism and then apply this to their
own custom widget or Java class.&nbsp;</p>
<h3><a name="Intro_Palette"></a>Palette</h3>
<p>The visual editor provides a palette of classes from which the user
can choose commonly used classes.&nbsp; The tutorial shows how to
create a new palette category containing the CustomWidget to allow it
to be brought to the user's selection and easily selected and dropped
without having to use <span style="font-style: italic;">ChooseBean</span>
and enter the class name</p>
<table style="text-align: left; width: 50%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before</td>
<td style="vertical-align: top;">With plugin showing <span
style="font-style: italic;">Custom</span> category with the <span
style="font-style: italic;">MyCustomPrompter</span> class</td>
</tr>
<tr>
<td style="vertical-align: top;"><img
style="width: 147px; height: 241px;" alt="OriginalPalette"
src="images/OriginalPalette.png"><br>
</td>
<td style="vertical-align: top;"><img
style="width: 143px; height: 240px;" alt="NewPalette"
src="images/NewPalette.png"> </td>
</tr>
</tbody>
</table>
<h3><a name="Intro_Property_sheet"></a>Property sheet</h3>
<p><span style="font-family: monospace;">MyCustomPrompter</span> has an
<span style="font-style: italic;">int</span> property called <span
style="font-style: italic;">type</span> that affects the text shown on
the CustomPrompter's button.&nbsp; This has a set of restricted values
corresponding to static constraints.&nbsp; For example, 0 is the
constant <span style="font-family: monospace;">CustomPrompter.DOTS</span>,
1 is <span style="font-family: monospace;">CustomPrompter.MORE</span>
and 2 is <span style="font-family: monospace;">CustomPrompter.OPEN.</span>
Rather than have the user have to remember this the property sheet will
be extended so that there is a drop down list of available values and
the existing value is shown as its meaningful name rather than its
internal <span style="font-style: italic;">int</span> value.</p>
<table style="text-align: left; width: 75%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before</td>
<td style="vertical-align: top;">With plugin</td>
<td style="vertical-align: top;">With plugin</td>
</tr>
<tr>
<td style="vertical-align: top;"><span style="font-style: italic;">type</span>
property displayed with default <span style="font-style: italic;">int</span>
editor</td>
<td style="vertical-align: top;"><span style="font-style: italic;">type</span>
property displayed as static constant name</td>
<td style="vertical-align: top;"><span style="font-style: italic;">type</span>
property edited with drop down list of enumerated allowable values</td>
</tr>
<tr>
<td style="vertical-align: top;"><img
style="width: 217px; height: 85px;" alt="OriginalType"
src="images/OriginalTypeProperty.png"><br>
</td>
<td style="vertical-align: top;"><img
style="width: 216px; height: 86px;"
alt="TypePropertyLabelProviderWithPlugin"
src="images/TypePropertyLabelProvider.png"><br>
</td>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 216px; height: 86px;"
alt="TypePropertyCellEditor" src="images/TypePropertyCellEditor.png"></td>
</tr>
</tbody>
</table>
<p><span style="font-family: monospace;">MyCustomPrompter</span> has a
String property called <span style="font-style: italic;">text</span>
that reflects the value shown on the CustomPrompter's text
widget.&nbsp; The default property sheet editor for a String property
is a Text field that allows the value to be changed, however the
tutorial shows how to have a custom property editor that launches a
separate dialog through which the value can be changed</p>
<table style="text-align: left; width: 50%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before with default String
editor behavior for <span style="font-style: italic;">text</span>
property</td>
<td style="vertical-align: top;">With plugin showing custom
editor for <span style="font-style: italic;">text</span> property</td>
</tr>
<tr>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 212px; height: 47px;"
alt="OriginalTextProperty" src="images/OriginalTextProperty.png"> </td>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 211px; height: 46px;"
alt="TextPropertyCellEditor" src="images/TextPropertyCellEditor.png"> </td>
</tr>
</tbody>
</table>
<h3><a name="Intro_Graphical_behavior"></a>Graphical behavior</h3>
<p>The visual editor uses the graphical editor framework or GEF to
render the visual classes to the user.&nbsp; GEF is a powerful
framework which uses EditPart classes as mediators between the
underlying model and the draw2d view layer.&nbsp; This is similar to
the controller in an MVC pattern and described in overview at <a
href="http://www-128.ibm.com/developerworks/opensource/library/os-gef/index.html">
Create an Eclipse based application using GEF.</a> The default behavior
for a visual class is a WYSIWYG rendering where a preview of the live
runtime widget is drawn.&nbsp; There are times when you may wish to
override this for a specific component such as to visually annotate the
feedback for the figure such as drawing grid lines, additional handles
or other features provided by GEF.&nbsp; As an example of how to alter
the edit part used by the visual editor the tutorial shows how to have <span
style="font-style: italic;">MyCustomPrompter&nbsp;</span> rendered
with an icon <img style="width: 16px; height: 16px;" alt="Custom"
src="images/custom.gif"> and the text <span
style="color: rgb(255, 0, 0);">VE Rules</span> super imposed over the
image of the live visual control.&nbsp; In addition the default
behavior of a Composite graphical edit part is to draw a border around
it in the editor so that it can be located by the user irrespective of
whether it has child controls or not.&nbsp; <span
style="font-style: italic;">MyCustomPrompter</span> is an aggregate of
three child controls into a custom widget so the graphical edit part
will remove the artificial border.</p>
<table style="text-align: left; width: 100%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before with default behavior
showing the image of the live visual control with a border</td>
<td style="vertical-align: top;">With plugin showing custom edit
part with an icon and label and no border</td>
</tr>
<tr>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 342px; height: 172px;"
alt="originalGEF" src="images/OriginalGraphicalEditPart.png"> </td>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 341px; height: 171px;"
alt="GraphicalEditPart" src="images/GraphicalEditPart.png"> </td>
</tr>
</tbody>
</table>
<h3><a name="Intro_Code_generation"></a>Code generation</h3>
<p>Code generation uses decoder classes to mediate between the visual
editor's model and the Java source model.&nbsp; This tutorial shows how
to create a custom code generation rule for the <span
style="font-style: italic;">text</span> property of <span
style="font-style: italic;">MyCustomPrompter</span> so that it has an
additional comment placed on the line with the set method.&nbsp; This
is the string <span style="color: rgb(0, 102, 0);">// Prompter Text
Property</span></p>
<table style="text-align: left; width: 100%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before with default code
generation behavior</td>
<td style="vertical-align: top;">With plugin showing the extra
comment line code generated for the setText(String) method</td>
</tr>
<tr>
<td style="vertical-align: top; font-family: monospace;"><span
style="color: rgb(153, 0, 0);">private void</span>
createMyCustomPrompter() {<br>
&nbsp; myCustomPrompter = <span style="color: rgb(153, 0, 0);">new</span>
MyCustomPrompter(sShell, SWT.<span
style="font-style: italic; color: rgb(51, 51, 255);">NONE</span>);&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;<br>
&nbsp; myCustomPrompter.setText(<span style="color: rgb(51, 51, 255);">"Text
Value"</span>);<br>
}</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;"><span style="color: rgb(153, 0, 0);">private
void</span> createMyCustomPrompter() {</span><br
style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp; myCustomPrompter = <span
style="color: rgb(153, 0, 0);">new</span> MyCustomPrompter(sShell, SWT.<span
style="font-style: italic; color: rgb(51, 51, 255);">NONE</span>);&nbsp;&nbsp;&nbsp;
&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;</span> <br
style="font-family: monospace;">
<span style="font-family: monospace;">&nbsp;
myCustomPrompter.setText(<span style="color: rgb(51, 51, 255);">"Text
value"</span>); <span style="color: rgb(0, 153, 0);">// Prompter Text
Property</span></span> <br style="font-family: monospace;">
<span style="font-family: monospace;">}</span> </td>
</tr>
</tbody>
</table>
<h3><a name="Intro_Preferred_Event"></a>Preferred Event</h3>
<p><span style="font-style: italic;">MyCustomPrompter</span> signals an
event when its button is pressed.&nbsp;&nbsp; Listeners can register
interest in this with the method <span style="font-style: italic;">addButtonSelectionListener(ButtonSelectionListener
aListener)</span> and remove interest with the method <span
style="font-style: italic;">removeButtonSelectionListener(ButtonSelectionListener
aListener).&nbsp;</span> The Visual Editor will automatically detect
this event because the naming convention of the methods and the
listener class follows the JavaBeans specification.&nbsp; The event
will be available from the list of all available events for the custom
control, however it is included in the list that has everything from
mouse through keyboard and paint events.&nbsp; This tutorial shows how
to promote the event to the list of <span style="font-style: italic;">preferred</span>
events whereupon it will be shown on the <span
style="font-style: italic;">Add Events</span> menu for the class.</p>
<table style="text-align: left; width: 100%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">Before where the Events menu has
no preferred events</td>
<td style="vertical-align: top;">With plugin the Events menu has <span
style="font-style: italic;">buttonSelected</span> as a preferred event</td>
</tr>
<tr>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 502px; height: 412px;"
alt="OriginalEventsMenu" src="images/OriginalEventsMenu.png"> </td>
<td style="vertical-align: top;"><img
style="border: 1px solid ; width: 501px; height: 411px;"
alt="EventsMenuAfter" src="images/EventsMenuAfter.png"> </td>
</tr>
</tbody>
</table>
<h2><a name="Getting_started">Getting started</a></h2>
<p>This tutorial goes go through the steps required to build a plugin
called<i>org.eclipse.ve.example.customwidget</i><span
style="font-style: italic;"><span style="font-weight: bold;">.&nbsp;&nbsp;&nbsp;</span></span>
The pre-requisites are an Eclipse 3.1 target environment which has a
3.1 code-base for the Visual Editor, GEF and EMF installed.&nbsp; These
can be obtained from the <a
href="http://download.eclipse.org/tools/ve/downloads/index.php">Visual
Editor's download page</a>.&nbsp; There is an SDK version of the Visual
Editor available as well as a runtime, and to develop this tutorial
ensure you have the SDK download for the VE. If you obtain the SDK
drivers for GEF and EMF it means you will be able to view their source
and debug code more easily.</p>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;">&nbsp;&nbsp;&nbsp; Although the
plugin is designed to target 3.1 it can be developed in an earlier
environment such as 3.0.1.&nbsp; The target environment is the one that
is run when the <span style="font-weight: bold;">Run ... Eclipse
Environment</span> is used to launch a runtime workbench.&nbsp; You can
use <span style="font-weight: bold;">Windows-&gt;Preference-&gt;PDE-&gt;Target
Platform</span> to view and change the target environment and <span
style="font-weight: bold;">Help About</span> to see the version of
Eclipse.</p>
<p>The completed plugin can be obtained separately as described in the
section <a href="#A_complete_example">A complete example</a></p>
<h2><a name="Creating_the_Plugin">Creating the Plugin</a></h2>
<p>This section describes how to build the plugin <span
style="font-style: italic;">org.eclipse.ve.example.customwidget.&nbsp;</span>
This will be used to package the CustomWidget itself as well as to
include the extensions required to override its default behavior.&nbsp;
The end result for users is that they will install this plugin onto
their Eclipse environment and then configure their Java projects to use
the custom widget jar that is included in this plugin <a
href="#Using_a_classpath_container">using a class path container</a>.</p>
<p>To create the plugin select open the New Project wizard using the
menu options <span style="font-weight: bold;">File &gt; New &gt;
Project</span> and choose <span style="font-weight: bold;">Plug-in
Project</span><br>
</p>
<p><br>
On the first page of the creation wizard name the plugin <i>org.eclipse.ve.example.customwidget</i>,
select 3.1 as the target version and select the check box <span
style="font-style: italic;">Create an OSGi bundle manifest.&nbsp;&nbsp;</span>
Press <span style="font-style: italic;">Next</span> to bring up the <span
style="font-style: italic;">Plug-in-Content</span> page and enter a
plugin name such as <span style="font-style: italic;">Customwidget VE
Example Plugin</span> in the <span style="font-style: italic;">Plugin-In
Name</span> text field and set the name of runtime library to <span
style="font-style: italic;">customwidgetplugin.jar</span>.&nbsp;</p>
<p><img style="border: 1px solid ; width: 499px; height: 253px;" alt=""
src="images/CreatePluginWizard.png"></p>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> The reason the default suggested
runtime library name of <span style="font-style: italic;">customwidget</span><span
style="font-style: italic;"><span style="font-style: italic;">.jar</span></span>
is renamed to <span style="font-style: italic;">customwidgetplugin.jar</span>
is to distinguish the jar file used by the workbench code for the
plugin from the name that will be given to the runtime jar containing
the custom widget.&nbsp; This is covered in the section <a
href="#Different_jars_and_packages">Different jars and packages for
workbench and widget code</a></p>
<p>Press <span style="font-style: italic;">Finish</span> to have the
PDE generate the stub plugin.&nbsp; The workbench might then ask you to
switch to the PDE perspective which you can answer <span
style="font-style: italic;">Yes</span> to.&nbsp; The plugin manifest
editor should be opened by default.&nbsp; This is an editor that allows
you to view and edit the contents of the files called <span
style="font-style: italic;">plugin.xml and manifest.mf</span> that
reside within the plugin.&nbsp; These are both important files as they
describe the extension points used and also the list of pre-requisite
plugins.</p>
<p>A plugin represents a component that can be installed onto an
Eclipse environment and contributes code.&nbsp; Every plugin has a set
of dependent plugins which is those it requires to function.&nbsp; This
list would typically include pre-requisite plugins with classes or
interfaces extended or any extension points that have been used.&nbsp;
The list of pre-requisite plugins for a plugin extending the visual
editor is:</p>
<ul>
<li>org.eclipse.ui</li>
<li>org.eclipse.core.runtime</li>
<li>org.eclipse.ve.java.core</li>
<li>org.eclipse.jdt.core</li>
<li>org.eclipse.jem</li>
<li>org.eclipse.jem.proxy</li>
<li>org.eclipse.ve.cde</li>
<li><img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif">org.eclipse.ve.swt</li>
<li>org.eclipse.ve.propertysheet</li>
<li>org.eclipse.gef</li>
<li>org.eclipse.emf.ecore</li>
</ul>
<p>The pre-requisite plugin&nbsp;<img style="width: 24px; height: 13px;"
alt="" src="../images/tag_1.gif"> org.eclipse.ve.swt is not necessarily
required by everyone extending the visual editor.&nbsp; It contains the
code that enables the visual editor to work with the SWT and because <span
style="font-style: italic;">MyCustomPrompter</span> is an SWT custom
widget the plugin will be extending SWT base behavior.&nbsp; If your
plugin was for a JFC toolkit such as AWT or Swing you would not
necessarily include <span style="font-style: italic;">org.eclipse.ve.swt</span>
in your list of dependencies but instead would use <span
style="font-style: italic;">org.eclipse.ve.jfc.&nbsp;</span> If your
plugin was for an entirely new widget toolkit you might include neither.</p>
<p>To set up the list of required plugins select the <span
style="font-style: italic;">Dependencies</span> tab on the plugin
editor, select the <span style="font-style: italic;">Add ...</span>
button beside the list of Required Plug-ins and enter the list of
plugins listed above.</p>
<p><img style="border: 1px solid ; width: 353px; height: 166px;"
alt="PreReqPlugins" src="images/PreReqPlugins.png"></p>
<p>Having created the plugin there are two major steps remaining.&nbsp;
The first is to create the actual custom widget class itself and test
it, and the second is to extend the visual editor to have the
customized behavior described in the <a href="#Introduction">introduction</a>.</p>
<h2><a name="Different_jars_and_packages"></a>Different jars and
packages for workbench and widget code</h2>
<p>There are two jar files being created as part of this
tutorial.&nbsp; The reason for this is based on the architecture of the
Visual Editor and how it uses a separate JVM for the classes
instantiated by the editor rather with re-use or share the JVM used by
Eclipse itself.<br>
<br>
The Visual Editor can be considered as an extension to the Java
Development Tooling (JDT) that lets you preview any visual controls
that are part of the Java class being edited.&nbsp; The raw Java editor
on its own lets you view and modify the source code for a <span
style="font-style: italic;">.java</span> file, and edit it using
features like Code assist and the Outline viewer.&nbsp; When you use
code assist the list of available classes is scoped to be only those
that are valid for the current compilation unit, namely those present
in the Java build path of the project.&nbsp; The Java build path is
specified through the project's properties and can be thought of as the
list of <span style="font-style: italic;">-classpath</span> entries
that make up the <span style="font-style: italic;">javac</span>
command.&nbsp; If you try to use a class that isn't on the build path
you will get a compile error.&nbsp; If you try to call a method that
doesn't exist on a valid class you will get a compile error, although
if you were to change the build path so that it now contained a version
of the class that had the method it would compile.&nbsp; The build
path's entries determine the environment in which the class you're
editing is being created for and the editor responds accordingly.<br>
<br>
When the Visual Editor is open it uses the JDT's Java editor (as the
bottom half of the screen or a separate tab depending on the workbench
preferences) and parses the code to recognize visual classes and how
they are constructed and associated with each other together with their
initial property values. To create a preview of the visuals these
classes must be actually instantiated in a live environment following
the constructor pattern detected from the source and set methods
actually invoked against the live objects for the desired properties
and relationships.&nbsp; To do this a JVM environment must exist that
contains the list of <span style="font-style: italic;">-classpath</span>
entries that match those in the Java build path so that the JVM can
load and use the actual instances the user is editing their project
with.&nbsp; This can't be the Eclipse's JVM as this is started with the
.jar files required for it to behave as an editor, so a separate JVM is
created each time the Visual Editor is opened on a class.&nbsp; This is
sometimes referred to as the <span style="font-style: italic;">target
VM</span> and its purpose is to host prototype Java instances that the
Visual Editor instantiates and uses based on the source statements in
the <span style="font-style: italic;">.java</span> file being
edited.&nbsp;&nbsp; A good analogy to this process is the one used by
the <span style="font-style: italic;">Run As&gt;Java Application</span>
option in the JDT.&nbsp; If you write a Java class with a public void
main(String[] args) method the JDT lets you edit it inside the Eclipse
JVM, however to test it a separate JVM is launched by the <span
style="font-style: italic;">Java Application</span> launcher.&nbsp;
The JDT launcher's separate JVM can be viewed from the <span
style="font-style: italic;">Debug</span> viewer allowing you to set
breakpoints and step through code, while the Visual Editor's <span
style="font-style: italic;">target VM</span> is deliberately hidden
from the <span style="font-style: italic;">Debug</span> viewer to stop
users from accidentally terminating it.<br>
<br>
When writing the plugin for this tutorial there are two jar files that
will finally be created.&nbsp; The first of these is the <a
href="#Plugin_Jar">plugin side jar</a> and contains the Eclipse
workbench code that is used within the IDE's VM and contains code such
as a JFace property sheet editor, a GEF graphical edit part and a
custom source decoder.&nbsp; The second is the <a href="#Runtime_jar">runtime
side jar</a> that contains the actual <font face="Courier New">MyCustomPrompter</font>
class itself and doesn't run inside the IDE but instead is placed in
the Java build path of the user's project and runs in the target
VM.&nbsp; The runtime side jar also contains the BeanInfo class for
MyCustomPrompter that contains the extensions that conform to the
JavaBeans component model which is covered more in the sections on the <a
href="#Using_an_ENUM_cell_editor"><span style="font-style: italic;">type</span>
property editor</a> and creating the <a href="#Preferred_Event">preferred
event</a>.<br>
<br>
<img style="width: 601px; height: 515px;" alt=""
src="images/JARdiagram.png"><br>
</p>
<h3><a name="Plugin_Jar"></a>Plugin jar</h3>
<p>The plugin code for this tutorial is placed in <span
style="font-style: italic;">customwidgetplugin.jar</span> that is
defined as the runtime jar for the plugin itself.&nbsp; On the New
Project wizard we explicitly changed the default prompted jar name to
be <i>customwidgetplugin.jar</i> so that is will not be confused with
the <a href="#Runtime_jar">run time jar</a>. The <span
style="font-style: italic;">customwidgetplugin.jar </span>contains
the Eclipse code that will run inside the workbench and its definition
can be seen in the in the <span style="font-style: italic;">Runtime</span>
tab of the manifest editor for the plugin's plugin.xml file.&nbsp;<br>
<br>
<img style="border: 1px solid ; width: 357px; height: 155px;" alt=""
src="images/RuintimeLibraryPluginName.png"><br>
<br>
<img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> The name of the plugin code's jar
is either held in a <span style="font-family: monospace;">&lt;runtime&gt;&lt;library
name="customwidgetplugin.jar"&gt;&lt;/runtime&gt;</span> tag in the <span
style="font-style: italic;">plugin.xml</span> file for a pre 3.1
plugin, or else for an OSGI 3.1compatible only plugin the jar file name
is held in the <span style="font-style: italic;">MANIFEST.MF</span>
file in the line <span style="font-family: monospace;">Bundle-ClassPath:
customwidgetplugin.jar</span>.&nbsp;<br>
<br>
The package <span style="font-family: monospace;">org.eclipse.ve.example.customwidget</span>
contains the Java code that is used to create the contents of the <span
style="font-style: italic;">customwidgetplugin.jar</span>.<br>
</p>
<h3><a name="Runtime_jar"></a>Runtime jar</h3>
<p>The code for the <span style="font-family: monospace;">MyCustomPrompter</span>
and its BeanInfo class are placed in the package<span
style="font-family: monospace;">org.eclipse.ve.example.customwidget.prompter</span>.&nbsp;
When the plugin is deployed these classes are compiled not into the
plugin's <span style="font-style: italic;">customwidgetplugin.jar</span>
but
instead to a file customwidgets.jar.&nbsp;&nbsp; The steps to create
the customwidgets.jar are described in the section <a
href="#The_Custom_Widget">The Custom Widget</a>.</p>
<h2><a name="The_Custom_Widget">The Custom Widget</a></h2>
<p>The custom widget used in this tutorial extends SWT composite and
has three child controls on it; a label, a text field, and a
button.&nbsp; For this tutorial we used the Visual Editor to build the
custom widget which, although a good exercise in using the Visual
Editor, is outside the scope of what this tutorial is designed to cover
- you can download it directly from CVS to begin working.&nbsp; You
should download the two classes <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/src/org/eclipse/ve/example/customwidget/prompter/MyCustomPrompter.java">
<font face="Courier New">MyCustomPrompter.java</font></a>, and <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/src/org/eclipse/ve/example/customwidget/prompter/ButtonSelectionListener.java">
<font face="Courier New">ButtonSelectionListener.java</font></a> and
place them into the plugin project in a package <span
style="font-style: italic;">org.eclipse.ve.customwidget.prompter.&nbsp;</span>
This is illustrated below together with the Visual Editor opened
against the <span style="font-style: italic;">MyCustomPrompter</span>
class to show the three child controls.&nbsp; The package <span
style="font-style: italic;">org.eclipse.ve.example.customwidget</span>
is where the visual editor classes&nbsp; (such as the specialized
graphical edit part or code generation decoder) will reside, and the
package <span style="font-style: italic;">org.eclipse.ve.customwidget.prompter</span>
is where the classes reside that the user will use to build their
runtime GUIs with.&nbsp;</p>
<p><img style="border: 1px solid ; width: 721px; height: 357px;"
alt="RuntimeClasses" src="images/CustomWidgetPackage.png"></p>
<p>For deployment the classes <span style="font-style: italic;">MyCustomPrompter</span>
and <span style="font-style: italic;">ButtonSelectionListener</span>
will be packaged in a runtime jar.&nbsp; To do this select the runtime
package and use the pop up menu option <span style="font-weight: bold;">Export</span>
to bring up the Export wizard.&nbsp; Select the JAR file option and
name the JAR file <span style="font-style: italic;">customwidgets.jar.&nbsp;</span>
This JAR file will be placed inside the plugin itself and there are two
ways to do this.&nbsp; The first is to either export the JAR to a
temporary location on your computer and then import it into the
project.&nbsp; If you do this you should import the <span
style="font-style: italic;">customwidgets.jar</span> not as a JAR file
as it contains no code of any interest to the plugin itself, but
instead as a raw <span style="font-style: italic;">File</span>.&nbsp;&nbsp;
The reason for this is that the inclusion of the runtime code in the
plugin is not for the benefit of Eclipse and it will never be loaded by
the Visual Editor into the Eclipse JVM.&nbsp; The user of the plugin
will configure their Java project to use the custom prompter which is
described in the later section <a href="#Using_a_classpath_container">Using
a classpath container</a>, and the visual editor will insert the JAR
into the -classpath of the VM that it uses to host the Java classes
that make up the user's classes.<br>
<br>
The second way to ensure that the <span style="font-style: italic;">customwidgets.jar</span>
is included in the plugin that avoids having to export to the file
system and then re-import as a file, is to export straight to the
directory used by the plugin itself.&nbsp; To see the location of the
plugin you can open its properties and select Info.&nbsp; The figure
below shows an example of this where the workbench location is
D:\temp\tutorial and the JAR wizard creates customwidgets.jar into the
directory used by the <span style="font-style: italic;">org.eclipse.ve.example.customwidget</span>
plugin.&nbsp; If you do export directly to the workbench as shown below
afterwards you will need to do a manual refresh of the project's
contents using F5 (or the pop-up menu option) to ensure that the
Eclipse workbench is in sync with the file system contents that have
just been altered.<br>
</p>
<img style="border: 1px solid ; width: 466px; height: 401px;"
alt="JarExport" src="images/JARExport.png"><br>
<br>
<h3><a name="Testing_MyCustomPrompter"></a>Testing MyCustomPrompter</h3>
<p>Having created the plugin you can now test it.&nbsp; To do this
create an Eclipse launch configuration using the <span
style="font-weight: bold;">Run</span> menu to bring up the list of
available launch configurations, selecting <span
style="font-style: italic;">Eclipse Application</span> and <span
style="font-style: italic;">New</span> and then running this using the
default application.</p>
<p><img alt="" style="border: 1px solid ; width: 261px; height: 311px;"
src="images/LaunchConfig.png"></p>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> On Eclipse 3.0.x an <i>Eclipse
Application</i> launch configuration is called <i>Run-time Workbench.</i></p>
<p>This will launch a second Eclipse workbench - the first being your
one that you are using to develop the plugin and the second being the
one you are going to use to deploy the plugin into.&nbsp; In the
deployed workbench create a Java project and add <i>customwidgets.jar</i>
to the Java build path.&nbsp; This is done using the pop-up menu option
to open the <span style="font-weight: bold;">Properties</span> of the
project and selecting <span style="font-weight: bold;">Java Build path
...</span>.&nbsp; On the build path select the <span
style="font-style: italic;">Libraries</span> tab and <span
style="font-style: italic;">Add External Jar ...</span>.&nbsp; Point
to the location of the jar in the plugin itself - for the example
figure above this would be <span style="font-style: italic;">D:\temp\tutorial\org.eclipse.ve.example.customwidget.customwidgets.jar.</span>&nbsp;
Having added the JAR containing the <span style="font-style: italic;">MyCustomPrompter</span>
class you can now use it within a visual editor class.&nbsp; Create a
test sample using <span style="font-weight: bold;">File &gt; New &gt;
Visual class</span> and selecting <span style="font-weight: bold;">SWT
&gt; Shell.&nbsp;</span> This will open the Visual Editor over a class
with an SWT shell.&nbsp; Select the <span style="font-style: italic;">Choose
Bean</span> palette entry and because <span style="font-style: italic;">customwidgets.jar</span>
is in the project's build path (the effective -classpath used by the
Eclipse Java compiler and by the Visual Editor) you can choose <span
style="font-style: italic;">MyCustomPrompter</span> and drop it onto
the Shell.<br>
<br>
The behavior of <span style="font-style: italic;">MyCustomPrompter</span>
is everything picked up by default as the Visual Editor will realize
that <span style="font-style: italic;">MyCustomPrompter</span> extends
<span style="font-style: italic;">org.eclipse.swt.widgets.Composite</span>
so it will be rendered visually and have default property sheet, code
generation, graphical edit part and event menu behavior.&nbsp; The
remainder of this tutorial shows how to customize this behavior as
described in the <a href="#Introduction">introduction</a>.</p>
<h2><a name="Creating_a_Classpath_Container">Creating a classpath
container</a></h2>
<p>For the test described at the end of the preceding section the <span
style="font-style: italic;">MyCustomPrompter</span> class was made
available to the user's Java project by them adding it as an external
JAR.&nbsp; This isn't ideal as it requires the user knowing the
location of the plugin directory on their computer and physically
pointing to it.&nbsp; A better way is to use a classpath
container.&nbsp; This allows one-touch configuration of a Java project
to use a named container which handles all the internals of how to
locate the correct runtime code.&nbsp;</p>
<p>A Java container is a class that implements the JDT interface <span
style="font-style: italic;">org.eclipse.jdt.core.IClasspathContainer</span>.&nbsp;&nbsp;
It is added to a Java project's build path using the <span
style="font-style: italic;">Add Library</span> button on the <span
style="font-style: italic;">Libraries</span> tab and an example of one
used by the Visual Editor is <span style="font-style: italic;">org.eclipse.ve.internal.swt.SWTContainer</span>.&nbsp;&nbsp;
As well as the JDT using the container to locate the runtime classes
the Visual Editor uses this as a marker for extension behavior.&nbsp;
When the Visual Editor opens over a project all of the containers are
scanned and matched against extension points to see if there are any
plugins that wish to contribute to the palette or any other custom
visual editor behavior based on the classes included within the
container.</p>
<p>This tutorial doesn't create a new container class because the
complexities involved doing this require knowledge of JDT concepts such
as IPath and IClassPathEntry[].&nbsp; It is expected that commercial
quality plugins extending the Visual Editor will create their own
containers in which case the <span style="font-style: italic;">SWTContainer</span>
class is a good example to look at to learn how to do this, however for
simplicity the visual editor provides a reference implementation
container class&nbsp; <span style="font-style: italic;">org.eclipse.ve.internal.java.core.RegisteredClassPathContainer.&nbsp;</span>
The Registered container uses extension points to determine the JAR
files it will add to the user's build path.</p>
<p>The user experience is that a container called "Custom Prompter"
will be available for them to add to a Java project's build path.&nbsp;
This is described in the section <a href="#Using_a_classpath_container">Using
a classpath container</a>.&nbsp; The JDT extension point <span
style="font-style: italic;">org.eclipse.jdt.ui.classpathContainerPage</span>
allows contributions to be made for an entry to appear in the list of
containers and be available for the user to select, as well as the
wizard page that will then appear once <span
style="font-style: italic;">Next</span> is pressed.&nbsp; The wizard
page is responsible for configuring the project's build path to
actually add the container classpath entry.</p>
<p>To add the <span style="font-style: italic;">Custom Prompter</span>
entry to the list of available containers add the following to the <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/plugin.xml">
plugin.xml</a> of the <span style="font-style: italic;">org.eclipse.ve.examples.customwidget</span>
plugin.</p>
<pre> <a name="ContainerPageDefinition"></a>&lt;extension<br> point="org.eclipse.jdt.ui.classpathContainerPage"&gt;<br> &lt;classpathContainerPage<br><img
style="width: 24px; height: 13px;" alt="tag1" src="../images/tag_1.gif"> name="Custom Prompter"<br><img
style="width: 24px; height: 13px;" alt="tag2" src="../images/tag_2.gif"> class="org.eclipse.ve.internal.java.wizard.RegisteredClasspathContainerWizardPage"<br><img
style="width: 24px; height: 13px;" alt="tag3" src="../images/tag_3.gif"> id="org.eclipse.ve.example.PrompterContainer"&gt;<br> &lt;/classpathContainerPage&gt;<br> &lt;/extension&gt;<br></pre>
<p>The name <img style="font-style: italic; width: 24px; height: 13px;"
alt="tag1" src="../images/tag_1.gif"><span style="font-style: italic;">"Custom
Prompter"</span> is the user visible String shown in the list of
available libraries from the <span style="font-style: italic;">Add
Library</span> wizard on the <span style="font-style: italic;">Libraries</span>
tab on the <span style="font-style: italic;">Java build path.&nbsp;</span>
In a commercial quality plugin it is expected this would come from a
resource bundle and be externalized for different locales however this
tutorial will hard code it to the literal <span
style="font-style: italic;">"Custom Prompter"</span>.&nbsp; Once the
user selects a container library to be added and presses <span
style="font-style: italic;">Next</span> a wizard page is brought up
showing configuration details of the particular container.&nbsp; This
wizard page <span style="font-style: italic;">implements
org.eclipse.jdt.ui.wizards.IClasspathContainerPage</span> and for a
commercial quality plugin it is expected that a custom page would be
written.&nbsp; The visual editor SWT container page
org.eclipse.ve.internal.swt.SWTcontainerWizardPage is a good example to
look at if your intention is to create a full wizard page, however the
visual editor provides an example <span style="font-style: italic;">org.eclipse.ve.internal.java.wizard.RegisteredClasspathContainerWizardPage</span>
that can be used <img style="width: 24px; height: 13px;" alt="tag2"
src="../images/tag_2.gif">.&nbsp;&nbsp;<br>
<br>
The container needs an id that uniquely identifies it within an Eclipse
environment and this tutorial uses&nbsp;<img
style="width: 24px; height: 13px;" alt="tag3" src="../images/tag_3.gif"> <span
style="font-style: italic;">org.eclipse.ve.example.PrompterContainer.</span><br>
<br>
The RegisteredClasspathContainerWizardPage will add the container
RegisteredClasspathContainer to the build path of the user's project
once they select it.&nbsp; This is a generic container and to identify
it as being an entry that should point to the runtime files required
for the <span style="font-style: italic;">MyCustomPrompter</span> and
its supporting classes requires two further extension points.&nbsp; If
a specific custom container is being used then these are not required.<br>
<br>
The extension point <span style="font-style: italic;">org.eclipse.jdt.core.classpathContainerInitializer</span>
specificies a container initializer that will be used by the JDT to
configure containers.&nbsp; The following lines should be added to the
plugin.xml for the <span style="font-style: italic;">org.eclipse.ve.examples.customwidget</span>
plugin.</p>
<pre> &lt;extension<br> point="org.eclipse.jdt.core.classpathContainerInitializer"&gt;<br> &lt;classpathContainerInitializer<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> class="org.eclipse.ve.internal.java.core.RegisteredClasspathContainerInitializer"<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> id="org.eclipse.ve.example.PrompterContainer"&gt;<br> &lt;/classpathContainerInitializer&gt;<br> &lt;/extension&gt;<br><br></pre>
<p>The class used is a reference implementation provided by the Visual
Editor and is <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif"> <span style="font-style: italic;">org.eclipse.ve.internal.java.core.RegisteredClasspathcontainerInitializer.&nbsp;</span>
The id used must match the one described earlier as the id of the
container wizard page.&nbsp; This tutorial is using <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> <span
style="font-style: italic;">org.eclipse.ve.example.PrompterContainer.<br>
<br>
</span> Having configured the wizard page and the container initializer
this will now add an instance of the RegisteredClasspathContainer to
the user's build path of their Java project.&nbsp; This needs to be
told where to locate the jars that contain the runtime code.&nbsp;
There is an extension point used by the RegisteredClasspathContainer
class named <span style="font-style: italic;">org.eclipse.ve.java.core.registrations.&nbsp;</span>
To use it add the following lines to the plugin.xml.&nbsp; Note that if
a true container implementation is being done instead then this
extension point is not required - it is only used by the
RegisteredClasspathContainer.&nbsp; For example, the project
org.eclipse.ve.swt that defines the SWT extensions for the visual
editor has its own custom behavior and does not require use of this
extension point.&nbsp;</p>
<pre> &lt;extension<br> point="org.eclipse.ve.java.core.registrations"&gt;<br> &lt;registration<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> container="org.eclipse.ve.example.PrompterContainer"<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> description="Custom Prompter"&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> &lt;<a
name="library_definition"></a>library runtime="customwidgets.jar"/&gt;<br> &lt;/registration&gt;<br> &lt;/extension&gt;<br></pre>
<p>The&nbsp; name of the container must match the id used when the
classpath wizard page and container initializer were defined.&nbsp;
This tutorial is using <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif"> <span style="font-style: italic;">org.eclipse.ve.example.PrompterContainer.&nbsp;&nbsp;</span>
The container needs a description that will appear in the Java build
path list of classpath entries and the tutorial uses the hard coded
literal <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> <span style="font-style: italic;">"Custom
Prompter".&nbsp;</span> The plugin element&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">
&lt;library runtime="customwidgets.jar".&gt; describes the actual
location of the runtime jars that contain the <span
style="font-style: italic;">MyCustomPrompter</span> class.&nbsp; If
there are multiple jars then the entry can be repeated.&nbsp;&nbsp; The
location of the jar is relative to the plugin itself, so if <span
style="font-style: italic;">customwidgets.jar</span> were in a
directory called <span style="font-style: italic;">jars</span> within
the plugin then the entry would be runtime="jars/.customwidgets.jar".<br>
<br>
Having updated the plugin.xml file to define the classpath container
the next step is to test this.</p>
<h2><a name="Using_a_classpath_container"></a>Using a classpath
container</h2>
<p>Launch the Eclipse Application workbench using the <span
style="font-weight: bold;">Run</span> menu to open the runtime
environment in which the <span style="font-style: italic;">MyCustomPrompter</span>
class can be tested.&nbsp; If you have previously done this and created
a Java project with a build path entry pointing to the <span
style="font-style: italic;">customwidgets.jar</span> as described
earlier remove the jar from the build path.&nbsp; Otherwise create a
new Java project.</p>
<p>The next steps are the experience that a user of the plugin will
take to configure a Java project to work with the <span
style="font-style: italic;">MyCustomPrompter</span> custom
control.&nbsp; Open the properties for the Java project using the <span
style="font-weight: bold;">Properties</span> choice on the pop-up menu
and select <span style="font-style: italic;">Java Build Path.</span><span
style="font-weight: bold;"><span style="font-style: italic;">&nbsp;</span></span>
Select the <span style="font-style: italic;">Libraries</span> tab and
choose the <span style="font-style: italic;">Add Library</span>
button.&nbsp; This will bring up a list of all known Java containers
which will include the <span style="font-style: italic;">Custom
Prompter</span> as defined using the extension point
org.eclipse.jdt.ui.classpathcontainerPage <a
href="#ContainerPageDefinition">earlier.</a> The figure below shows
the Java build path for a project called <span
style="font-style: italic;">Test</span> and the Custom Prompter
displayed in the list of available libraries opened from the <span
style="font-style: italic;">Add Library</span> button</p>
<p><img style="border: 1px solid ; width: 641px; height: 471px;" alt=""
src="images/CustomPrompterContainer.png"></p>
<p>Select the <span style="font-style: italic;">Custom Prompter</span>
and press Next to view the wizard page <span
style="font-style: italic;">org.eclipse.ve.internal.java.wizard.RegisteredClasspathContainerWizardPage</span>
defined <a href="#ContainerPageDefinition">earlier</a>.&nbsp; This is
a generic example of a page and shows details of the jar that will be
added by the page.&nbsp; For commercial quality plugins it is expected
that this page however will be a specific to the particular
plugin.&nbsp;</p>
<p>Pressing Finish on the wizard page will configure the project (using
the RegisteredClasspathcontainerInitializer defined earlier) to include
the container <span style="font-style: italic;">RegisteredClasspathContainer</span>
together with the id of<span style="font-style: italic;">org.eclipse.ve.examples.PrompterContainer.&nbsp;</span>
Expanding the container in the project's build path will show that it
points to the correct location for the customwidgets.jar as described
in the <span style="font-family: monospace;">&lt;library
runtinme="customwidgets.jar"&gt;</span> plugin.xml tag described <a
href="#library_definition">earlier</a>.<br>
<br>
<img style="border: 1px solid ; width: 281px; height: 147px;" alt=""
src="images/TestProjectBuildPath.png"><br>
<br>
<img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> The figures above for configuring
the project Test's build path to include the <span
style="font-style: italic;">Custom Prompter</span> container entry
show two other containers, namely the <span style="font-style: italic;">JRE
System library</span> and the <span style="font-style: italic;">Standard
Widget Toolkit.</span>&nbsp;&nbsp; The JRE container will be present on
the Java project by default when it is first created, however the SWT
container will not be.&nbsp; This is a container defined by the plugin
project <span style="font-style: italic;">org.eclipse.ve.swt</span>
that enables the Visual Editor to work with the SWT.&nbsp; If you
created the Test project in the step <a
href="#Testing_MyCustomPrompter">Testing the custom prompter</a>
described earlier when you created the test class using the <span
style="font-style: italic;">New Visual Class Wizard</span>and selected
SWT application the wizard automatically added the SWT container to the
project's build path as required.&nbsp; SWT support for the Visual
Editor can be manually added by using the steps described above but
selecting <span style="font-style: italic;">Standard Widget Toolkiit</span>
instead of <span style="font-style: italic;">Custom Prompter</span> on
the <span style="font-style: italic;">Add Library</span> wizard
page.&nbsp; Adding dependent containers (CustomPrompter requires SWT)
is not something that is supported by the reference implementation of
RegisteredClassPathContainer and it is expected that commercial quality
plugins will provide their own container class with the required logic
to ensure consistency of dependent containers in the user's build path.<br>
<br>
Having configured the Test project to use the <span
style="font-style: italic;">Custom Prompter</span> container you can
now test it by creating an SWT Shell from the <span
style="font-style: italic;">New Visual Class Wizard</span> and
dropping <span style="font-style: italic;">MyCustomPrompter</span>
using the <span style="font-style: italic;">Choose Bean ...</span>
palette entry.&nbsp; the next step is to configure the palette so that
a new category called <span style="font-style: italic;">Custom</span>
is added that has an entry for the <span style="font-style: italic;">MyCustomPrompter</span>
class.</p>
<h2><a name="Adding_a_palette_category_for_our_widget">Adding a palette
category for MyCustomPrompter</a></h2>
<p>The visual editor's palette is described by an EMF model.&nbsp; EMF
serializes to&nbsp; <a
href="http://www.omg.org/technology/documents/formal/xmi.htm">XMI</a>
which is an XML representation of a graph of EMF objects.&nbsp; Plugins
can define their own XMI files that describe the categories to be added
to the palette, the groups these belong to, and the actual entries
themselves.&nbsp; For the org.eclipse.ve.examples.customwidgets plugin
there will be a palette XMI file that describes the single category and
class to add.<br>
<br>
Create a file called customprompter.xmi in the plugin and open it with
a text editor.&nbsp; The data for the file is shown below and can be
downloaded directly from <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/customprompter.xmi">
CVS</a> to avoid re-entry.<br>
<br>
</p>
<pre> &lt;xmi:XMI xmi:version="2.0"<br> xmlns:xmi="http://www.omg.org/XMI"<br> xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" <br> xmlns:palette="http:///org/eclipse/ve/internal/cde/palette.ecore"<br> xmlns:utility="http:///org/eclipse/ve/internal/cde/utility.ecore"&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> &lt;palette:CategoryCmp&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> &lt;categoryLabel xsi:type="utility:ConstantString" string="Custom"/&gt;<br> &lt;cmpGroups xsi:type="palette:GroupCmp"&gt;<br><br><img
style="width: 23px; height: 13px;" alt="" src="../images/tag_3.gif"> &lt;cmpEntries xsi:type="palette:AnnotatedCreationEntry" xmi:id="entry2" icon16Name="platform:/plugin/org.eclipse.ve.example.customwidget/icons/custom.gif"&gt;<br> &lt;objectCreationEntry xsi:type="palette:EMFCreationToolEntry"<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif"> creationClassURI<b>=</b>"java:/org.eclipse.ve.example.customwidget.prompter#MyCustomPrompter"/&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_5.gif"> &lt;entryLabel xsi:type="utility:ConstantString" string="Prompter"/&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_6.gif"> &lt;values xmi:type="ecore:EStringToStringMapEntry" key="org.eclipse.ve.internal.cde.core.nameincomposition" value="customPrompter"/&gt; <br> &lt;/cmpEntries&gt;<br><br> &lt;/cmpGroups&gt;<br> &lt;/palette:CategoryCmp&gt;<br> &lt;/xmi:XMI&gt;<br></pre>
<p>The&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif"> &lt;palette:categoryCmp&gt; tag describes a
palette category that has a label and groups, each group containing a
number of entries.&nbsp; In the example for the tutorial the label is
hard coded to the literal&nbsp;<img style="width: 24px; height: 13px;"
alt="" src="../images/tag_2.gif"> <span style="font-style: italic;">"Custom".&nbsp;</span>
<img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> For
a plugin that needed to support different language locales there is an
EMF class utility:TranslatableString and examples of its usage can be
found in the palette files for the plugin org.eclipse.ve.jfc.<br>
<br>
A single group is defined for the Custom category.&nbsp; If multiple
groups are defined the palette demarks these visually with a
separator.&nbsp; The group has a single entry that defines the&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">
graphic, the qualified&nbsp;<img style="width: 24px; height: 13px;"
alt="" src="../images/tag_4.gif"> name of the class and the literal <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_5.gif">
string that is displayed on the palette entry.&nbsp; To ensure that a
good default name is used each time the user drops an instance of the
CustomPrompter a&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_6.gif"> default <span style="font-style: italic;">nameincomposition
</span>is specified to be "customPrompter". &nbsp; The&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">
graphic points to the URL of where the image is located, in this case
the entry points to a file <span style="font-style: italic;">custom.gif</span>
in the <span style="font-style: italic;">icons</span> directory of the
plugin called <span style="font-style: italic;">org.eclipse.ve.example.customwidget.&nbsp;</span>
The graphic used&nbsp;<img style="width: 16px; height: 16px;" alt=""
src="images/custom.gif"> is available in <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/icons/custom.gif">CVS</a>
and you will
need to create a folder called <span style="font-style: italic;">icons</span>
in the plugin and copy it there.<br>
<br>
<img style="border: 1px solid ; width: 264px; height: 148px;" alt=""
src="images/IconsFolder.png"></p>
<p><img src="../images/tip.gif" alt="Tip:"
style="width: 62px; height: 13px;">
Because XMI files do not have anything to validate them at design time
errors made in their syntax can easily be made that cause runtime
problems that can be hard to trace and debug.&nbsp; The most
straightforward way to write a Visual Editor XMI file is to copy an
existing one that is similar to what you desire and then alter just the
parts that need changing.</p>
<p>Having created the <span style="font-style: italic;">customprompter.xmi</span>
file we need to enable the Visual Editor to use it.&nbsp; This is done
by associating the palette file with a classpath container, in our case
the Custom Prompter.&nbsp;</p>
<p>Now that we have our palette xmi file available, we need to
contribute it to the Visual Editor.&nbsp; We do so by adding to the
following extension in the plugin's&nbsp; <span
style="font-style: italic;">plugin.xml</span> manifest
file.</p>
<pre> &lt;extension<br><img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif"> point="org.eclipse.ve.java.core.contributors"&gt;<br> &lt;palette<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> container="org.eclipse.ve.example.PrompterContainer"<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> categories="<b>customprompter.xmi</b>"/&gt;<br> &lt;/extension&gt; <br></pre>
<p>The extension point used is&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> <span
style="font-style: italic;">org.eclipse.ve.java.core.contributors.</span>
This has a &lt;palette&gt; child XML tag that points to the id of
the&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> container whose inclusion in a project's
build path causes the palette categories defined in the&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">
categories tag to be included. The palette categories tag is relative
to the root of the plugin project, for example If the palette XMI file
is in a folder called <span style="font-style: italic;">palette</span>
then the entry would be <span style="font-family: monospace;">categories="palette/customprompter.xmi".</span></p>
<p>When the Visual Editor starts it scans all of the project's build
path entries and for any that are containers it looks to see whether
there are any palette files.&nbsp; These are combined together to
create the overall palette.</p>
<p><img style="width: 63px; height: 13px;" src="../images/note.gif"
alt="Note:"> As well as describing palette entries directly it is
possible to configure the Visual Editor to have an <font
face="Courier New">IConfigurationContribution</font> that has the
ability to manipulate both the -classpath of the Visual Editor's VM and
the palette with more fine control.&nbsp; An example of where this is
done is by SWT that has to add runtime packages such as DLLs or
packages to the VM's arguments, or a plugin that might wish to remove
some of the existing palette entries (such as the JFC ones) for
projects configured with their container present.</p>
<p><img style="height: 13px; width: 62px;" alt="Tip:"
src="../images/tip.gif"> As
well as defining containers to be the trigger point for Visual Editor
custom behavior you can also use plugins by direct name&nbsp;using the <span
style="font-style: italic;">plugin=</span> tag. An example of where
you might do this is if you were extending the Visual Editor to work
with a set of classes that were contained in a specific plugin, so the
user experience to enable a Java project would be to add a dependent
plugin rather than a classpath container.&nbsp; An example of this
might be something like a PDE type development environment for the
actual end user.</p>
<h3><a name="Testing_the_custom_palette"></a>Testing the custom palette</h3>
<p>Having modified the manifest of the example plugin to include the
plugin the next step is so test it.&nbsp; Do this by launching the
Eclipse Application workbench and creating, or re-opening, a class <font
face="Courier New">MyShell</font> that was created from the <span
style="font-style: italic;">New Visual Class <span
style="font-style: italic;">Wizard</span></span> as an SWT
application.&nbsp; The Visual Editor should detect that the container
with an id of <span style="font-style: italic;">org.eclipse.ve.example.PrompterContainer</span>
is in the project's build path and include the palette categories
contained in the <span style="font-style: italic;">custompalette.xmi</span>
file.&nbsp; This is shown in the figure below where the Prompter
palette entry has been selected and dragged out onto the Shell.&nbsp;<br>
<br>
<img style="border: 1px solid ; width: 758px; height: 396px;" alt=""
src="images/CustomPalette.png"><br>
<br>
<img src="../images/tip.gif" alt="Note:" style="height: 13px; width: 62px;">
When
you launch the Eclipse Application workspace use the <span
style="font-style: italic;">-clean</span> option, as each time the <span
style="font-style: italic;">plugin.xml</span> manifest file has
changed we need to be sure the runtime Eclipse environment clears its
cached manifest details<br>
<br>
At this point in the tutorial you should have defined a classpath
container that the user can configure a Java project with to include
the jar containing the runtime code for the <span
style="font-style: italic;"><span style="font-style: italic;"><span
style="font-style: italic;">MyCustomPrompter</span></span></span>
class.&nbsp; The extension point <span style="font-style: italic;">org.eclipse.ve.java.core.contributors</span>
has been used to point to the location of a palette XMI file that
contains a category with an entry for the class.<br>
<br>
The next steps are to configure the Visual Editor so that <span
style="font-style: italic;">MyCustomPrompter</span> has custom
behavior over and above that it inherits by virtue of extending <span
style="font-style: italic;">org.eclipse.swt.widgets.Composite</span>.</p>
<h2><a name="Using_an_ENUM_cell_editor">Enumerated values for the <span
style="font-style: italic;">type</span> property</a></h2>
<p><span style="font-family: monospace;">MyCustomPrompter</span> class
has an <i>int</i> property named <i style="font-weight: bold;">type</i>with
<i>getType</i>() and <i>setType</i>(int aType) methods.&nbsp; While
the signature of <i>setType</i> allows it to accept any int, the class
itself only works with one of the three values 0, 1, or 2 The
definition of the values is held in three static constants on the <span
style="font-family: monospace;">MyPrompterClass</span>.</p>
<pre><span style="color: rgb(153, 0, 0);">public final static int</span> <span
style="font-style: italic; color: rgb(51, 51, 255);">DOTS</span> = 0;<br><span
style="color: rgb(153, 0, 0);">public final static int</span> <span
style="color: rgb(51, 51, 255); font-style: italic;">MORE</span> <span
style="font-style: italic;">=</span> 1;<br><span
style="color: rgb(153, 0, 0);">public final static int</span> <span
style="color: rgb(51, 51, 255); font-style: italic;">OPEN</span> = 2;<br></pre>
<p>The significance of the three values is that they alter the button
text for <span style="font-family: monospace;">MyCustomPrompter to</span>
be either "...", "More", or "Open" respectively.&nbsp;&nbsp; The
following code shows this for <span style="font-family: monospace;">MyCustomPrompter</span>'s
<span style="font-family: monospace;">setType(int type)</span> method.</p>
<pre><span style="color: rgb(153, 0, 0);">public void</span> setType (<span
style="color: rgb(153, 0, 0);">int</span> type) {<br> <span
style="color: rgb(153, 0, 0);">switch</span> (type) {<br> <span
style="color: rgb(153, 0, 0);">case</span> <span
style="font-style: italic; color: rgb(51, 51, 255);">DOTS</span>: button.setText(<span
style="color: rgb(51, 51, 255);">"..."</span>);<br> <span
style="color: rgb(153, 0, 0);">break</span>;<br> <span
style="color: rgb(153, 0, 0);">case</span> <span
style="font-style: italic; color: rgb(51, 51, 255);">MORE</span>: button.setText(<span
style="color: rgb(51, 51, 255);">"More"</span>);<br> <span
style="color: rgb(153, 0, 0);">break</span>;<br> <span
style="color: rgb(153, 0, 0);">case</span> <span
style="font-style: italic; color: rgb(51, 51, 255);">OPEN</span>: button.setText(<span
style="color: rgb(51, 51, 255);">"Open"</span>);<br> <span
style="color: rgb(153, 0, 0);">break</span>;<br> <span
style="color: rgb(153, 0, 0);">default</span>:<br> <span
style="color: rgb(153, 0, 0);">throw new</span> IllegalArgumentException(<span
style="color: rgb(51, 51, 255);">"Value "</span> + type + <span
style="color: rgb(51, 51, 255);">" must be one of 0, 1 or 2"</span>);<br> }<br>}<br></pre>
<p>Whenever a class is selected in the Visual Editor graphical canvas
or Java Beans tree viewer the Properties view will show its properties
and their current values.&nbsp; The view can also be used to edit the
property values, and the Visual Editor has a number of pre-defined
editors associated with specific types.&nbsp; <span
style="font-style: italic;">int</span> properties for example have an
editor that allows only valid <span style="font-style: italic;">int</span>
values to be entered and by default the Visual Editor will use this
whenever the <span style="font-style: italic;">type</span> property is
selected based on its signature.</p>
<p>This step of the tutorial describes how to override the default
behavior so that the <span style="font-style: italic;">type</span>
property is edited using a drop down list of the three allowable
values.&nbsp; Also, instead of the values 0, 1 and 2 being displayed as
the current values the literals "Dots", "More" and "Open" will be used
instead.&nbsp; This is described as an objective of the tutorial in the
<a href="#Introduction">Introduction</a>.</p>
<p>To override the behavior of the <span style="font-style: italic;">type</span>
property so that it has the desired behavior involves using a BeanInfo
class.&nbsp; BeanInfo classes provide a way to describe a classes'
design time behavior and art part of the <a
href="http://java.sun.com/products/javabeans/reference/api/index.html">JavaBeans
specification</a>.&nbsp; The Visual Editor uses the JavaBeans
specification wherever possible to define edit time behavior for a
JavaBean.&nbsp;</p>
<p>The BeanInfo specification allows for a class with the same name as
its Java peer to exist that describes the edit time behavior of the
class.&nbsp; For example, the tutorial class is named <span
style="font-family: monospace;">MyCustomPrompter</span> so there would
be a class <span style="font-family: monospace;">MyCustomPrompterBeanInfo</span>
that implements the interface <span style="font-family: monospace;">java.beans.BeanInfo</span>
associated with it.&nbsp; The simplest way to create this class is to
put it in the same package as the class it describes (e.g. <span
style="font-family: monospace;">org.eclipse.ve.example.customwidget</span>)
.&nbsp; Strictly speaking this isn't good physical separation of
behaviors as the BeanInfo classes should be kept apart from the runtime
in a separate package and separate jar so they don't become part of the
end user's actual deployment configuration.&nbsp; The Visual Editor
does support scenarios where the BeanInfo is in separate packages and
separate jars, however for the purpose of this tutorial the class <span
style="font-family: monospace;">org.eclipse.ve.examples.customwidget.MyCustomPrompterBeanInfo</span>
will be created that extends the abstract superclass <span
style="font-family: monospace;">java.beans.SimpleBeanInfo</span>.</p>
<p>The full source code for the BeanInfo can be downloaded from <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/src/org/eclipse/ve/example/customwidget/prompter/MyCustomPrompterBeanInfo.java">
CVS.</a>&nbsp; A BeanInfo class is responsible for describing the list
of properties used by a tool such as the Visual Editor, and also their
edit time behavior.&nbsp; This is done by specializing the method <span
style="font-family: monospace;">PropertyDescriptor[]
getPropertyDescriptors()</span>.&nbsp; The method returns an array of <span
style="font-family: monospace;">java.beans.PropertyDescriptor</span>
objects, each one representing an item that will appear as a row in the
Properties view and containing information about its display name, the
Java get and set method associated with the property, as well as the
rules for how the property shoud be edited.&nbsp; The specification
allows support for editing behavior is provided by having a <span
style="font-family: monospace;">java.beans.PropertyEditor</span>
defined against the <span style="font-family: monospace;">PropertyDescriptor</span>,
and while the Visual Editor will work correctly if a <span
style="font-family: monospace;">PropertyEditor</span> class has been
defined it also supports a shorthand notation for describing a list of
enumerated values because this pattern occurs frequently in widget
libraries (for example orientation properties on scroll bars, alignment
values on layout constraints, etc...) and is the pattern used by the
MyCustomPrompter's <span style="font-style: italic;">type</span>
property.&nbsp; This shorthand notation involves defining a key value
pair on the PropertyDescriptor, the key of which is the string literal <span
style="font-style: italic;">enumerationValues</span> and the value of
which is an array of tri values.&nbsp; The structure of the array is a
repeating set of <span style="font-weight: bold;">displayName, value,
initializationString</span>.&nbsp; The displayName is the user visible
string shown to the user in the Properties view, the value is the
actual object that identifies the trivalue against a live property
setting, and the initializationString is the fully qualified code
fragment that is generated as argument to the property's set
method.&nbsp; This is illustrated below in the method <span
style="font-family: monospace;">getPropertyDescriptors()</span> for
the class <span style="font-family: monospace;">MyCustomPrompterBeanInfo</span>.</p>
<pre> <span style="color: rgb(153, 0, 0);">public</span> PropertyDescriptor[] getPropertyDescriptors() {<br><br> <span
style="color: rgb(153, 0, 0);">try</span> {<br> PropertyDescriptor[] result = <span
style="color: rgb(153, 0, 0);">new</span> PropertyDescriptor[2];<br><br> result[0] = <span
style="color: rgb(153, 0, 0);">new</span> PropertyDescriptor(<span
style="color: rgb(51, 51, 255);">"text"</span>,MyCustomPrompter.class);<br> result[1] = <span
style="color: rgb(153, 0, 0);">new</span> PropertyDescriptor<span
style="font-weight: bold;">(<span style="color: rgb(51, 51, 255);">"type"</span></span>,MyCustomPrompter.class);<br><br> result[1].setValue(<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"><span
style="color: rgb(51, 51, 255);">"enumerationValues"</span>, <span
style="color: rgb(153, 0, 0);">new</span> Object[] {<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> <span
style="color: rgb(51, 51, 255);">"Dots"</span>, <span
style="color: rgb(153, 0, 0);">new</span> Integer(MyCustomPrompter.<span
style="color: rgb(51, 51, 255); font-style: italic;">DOTS</span>), <span
style="color: rgb(51, 51, 255);">"org.eclipse.ve.example.customwidget.prompter.MyCustomPrompter.DOTS"</span>,<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> <span
style="color: rgb(51, 51, 255);">"More"</span>, <span
style="color: rgb(153, 0, 0);">new</span> Integer(MyCustomPrompter.<span
style="color: rgb(51, 51, 255); font-style: italic;">MORE</span>), <span
style="color: rgb(51, 51, 255);">"org.eclipse.ve.example.customwidget.prompter.MyCustomPrompter.MORE"</span>,<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif"> <span
style="color: rgb(51, 51, 255);">"Open"</span>, <span
style="color: rgb(153, 0, 0);">new</span> Integer(MyCustomPrompter.<span
style="color: rgb(51, 51, 255); font-style: italic;">OPEN</span>), <span
style="color: rgb(51, 51, 255);">"org.eclipse.ve.example.customwidget.prompter.MyCustomPrompter.OPEN"</span> <br> });<br> <br> <span
style="color: rgb(153, 0, 0);">return</span> result;<br> } <span
style="color: rgb(153, 0, 0);">catch</span> (IntrospectionException e) { <br> e.printStackTrace();<br> <span
style="color: rgb(153, 0, 0);">return null</span>;<br> }<br>}<br></pre>
<p>The getPropertyDescriptors() method returns an array of two
properties; <span style="font-style: italic;">text</span> and <span
style="font-style: italic;">type.&nbsp;</span> The <span
style="font-style: italic;">type</span> property has a key value pair
assigned to it with a key of <img style="width: 24px; height: 13px;"
alt="" src="../images/tag_1.gif"> <span style="font-style: italic;">enumerationValues</span>
and a value that is an array of nine elements.&nbsp; These nine
elements represent the three enumerated values defined as a
tri-values.&nbsp; The first of these is for the value 0 and is defined
as <span style="font-weight: bold;">displayName,value,initString</span>
of&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> "Dots", 0, "0".&nbsp; Instead of hard
coding the 0 however they are coded to be the dynamic lookups of the
actual value from the static constant, allowing the constant to
internally change without requiring BeanInfo modification.&nbsp; The
other two values <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_3.gif"> "More" and <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif">
"Open" are defined as tri-values for the 4th, 5th and 6th elements of
the array and the 7th, 8th and 9th respectively.</p>
<p>The <span style="font-family: monospace;">getPropertyDescriptors()</span>
method returns a fully inclusive set of property descriptors for the
JavaBean.&nbsp; For <span style="font-family: monospace;">MyCustomPrompter</span>
the user experience the tutorial wants is that the inherited properties
such as background, foreground, size, etc.. are present on the
class.&nbsp; To achieve this rather than having the <span
style="font-family: monospace;">getPropertyDescriptors()</span> method
collect the full list of all desired properties, the JavaBeans
specification allows for the method <span
style="font-family: monospace;">BeanInfo[] getAdditionalBeanInfo()</span>
to be specialized.&nbsp; This returns an array of <span
style="font-family: monospace;">BeanInfo</span> classes whose
properties are merged together with the result of <span
style="font-family: monospace;">getPropertyDescriptors()</span> to
create the complete list.</p>
<pre> <span style="color: rgb(153, 0, 0);">public</span> BeanInfo[] getAdditionalBeanInfo(){<br> <span
style="color: rgb(153, 0, 0);">try</span>{<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> <span
style="color: rgb(153, 0, 0);">return new</span> BeanInfo[]{Introspector.<span
style="font-style: italic;">getBeanInfo</span>(Control.<span
style="color: rgb(153, 0, 0);">class</span>)};<br> } <span
style="color: rgb(153, 0, 0);">catch</span> (IntrospectionException e){<br> <span
style="color: rgb(153, 0, 0);">return new</span> BeanInfo[0];<br> }<br></pre>
<img src="../images/tip.gif" alt="Note:" style="width: 62px; height: 13px;">
<p>To create the array of BeanInfo classes representing the set of
descriptors to merge one technique might be to write the code <span
style="font-family: monospace;"><span style="color: rgb(153, 0, 0);">return
new</span> BeanInfo[] {CompositeBeanInfo.<span
style="color: rgb(153, 0, 0);">class</span>, ControlBeanInfo.<span
style="color: rgb(153, 0, 0);">class</span>, WidgetBeanInfo.<span
style="color: rgb(153, 0, 0);">class</span>}</span>.&nbsp; However
doing so would be an attempt to hard code the names of the BeanInfo
classes that may currently be associated with the superclass chain of <span
style="font-family: monospace;">MyCustomPrompter</span> but would fail
if new BeanInfo classes were introduced or removed.&nbsp; The preferred
technique for picking up inherited properties is with the statement <span
style="font-family: monospace;"><span style="color: rgb(153, 0, 0);">return
new</span> BeanInfo[]{Introspector.<span style="font-style: italic;">getBeanInfo</span>(Composite.<span
style="color: rgb(153, 0, 0);">class</span>)}</span> where the
argument to the <span
style="font-style: italic; font-family: monospace;">getBeanInfo</span><span
style="font-family: monospace;">(Class aClass)</span> method is the
current bean's superclass.&nbsp; Rather than using <span
style="font-family: monospace;">Composite</span> as the starting point
for merging inherited properties which is the immediate superclass of <span
style="font-family: monospace;">MyCustomPrompter</span>, <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif">&nbsp;
<span style="font-family: monospace;">Control</span> is used
instead.&nbsp; The reason for this is that while <span
style="font-family: monospace;">MyCustomPrompter</span> extends <span
style="font-family: monospace;">Composite</span> it does this more for
physical reasons so it can have its three child controls (the <span
style="font-family: monospace;">Label</span>, <span
style="font-family: monospace;">Text</span> and <span
style="font-family: monospace;">Button</span>), however as a black box
custom class it itself doesn't want to inherit the behavior of <span
style="font-family: monospace;">Composite</span> such as the ability
to have its layout changed.&nbsp; For this reason it is logically a
subclass of <span style="font-family: monospace;">Control.</span></p>
<h3><a name="Testing_the_enumerated_values_for_type"></a>Testing the
enumerated values for <span style="font-style: italic;">type</span></h3>
<p>Having updated <span style="font-family: monospace;">MyCustomPrompterBeanInfo.java</span>
this must be re-exported to the <span style="font-style: italic;">customwidgets.jar</span>
file.&nbsp; The customwidgets.jar in the plugin is the one that the <span
style="font-style: italic;">Custom Prompter</span> classpath container
uses in its build path, and if the step of re-creating the <span
style="font-style: italic;">customwidgets.jar</span> file is not done
when you launch the Eclipse Application you will be using the old
version of the code.&nbsp; Currently Eclipse 3.1 does not support
classpath container entries pointing to folder structures otherwise the
RegisteredClassPathContainer could be coded to automatically look back
into the directory structure of the development environment that
launched it so for now don't forget to keep re-creating the <span
style="font-style: italic;">customwidgets.jar</span> file each time
any of its contents have changed.</p>
<img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;">
<p>The Visual Editor caches information about a class and under some
builds prior to VE 1.1 there are some issues with the cache going stale
and not being automatically refreshed.&nbsp; If this occurs you can
manually recycle the cache by selecting <span
style="font-weight: bold;">Project &gt; Clean</span> and also manually
removing the directory <span style="font-style: italic;">org.eclipse.ve.beaninfo/cache</span>
from the workbench directory.&nbsp;<br>
<br>
The changes to the <span style="font-family: monospace;">MyCustomPrompterBeanInfo</span>
should mean that the <span style="font-style: italic;">type</span>
property is now rendered with its display name rather than just the raw
<span style="font-family: monospace;">int</span> value.&nbsp; The
Properties view also will create a drop down list of the three
allowable values.&nbsp; The figure below shows the list of the three
values and when one is selected the argument to the <span
style="font-family: monospace;">setType(int)</span> method will be
generated with the initializationString as defined in the <span
style="font-family: monospace;">BeanInfo</span> array.<br>
<br>
<br>
<img style="border: 1px solid ; width: 808px; height: 527px;" alt=""
src="images/TypeCodeGeneration.png"><br>
<br>
The BeanInfo mechanism provides one technique to override default edit
behavior for a Java class.&nbsp; The Visual Editor uses BeanInfo
classes internally for many of its customizations and it recognizes
externally created BeanInfo classes according to the JavaBeans
specification.<br>
<br>
Some kinds of customization are not possible through the BeanInfo
mechanism because while it provides a powerful way to describe edit
time behavior and shape for a class the Visual Editor needs to be able
to export some of its innermost extension points to the creator of the
Java class, and the BeanInfo mechanism is designed to provide a
portable way of customizing a Java class that can be transported easily
between different IDEs and tools.&nbsp; For example, the next exercise
in the tutorial is to override the behavior that occurs when the <span
style="font-style: italic;">text</span> property is edited to launch a
dialog editor.&nbsp; This dialog editor will be written using the SWT
and implement Eclipse specific interfaces, so describing it on the
BeanInfo would violate the idea that BeanInfo classes are portable (as
Eclipse interfaces and the SWT are not necessarily available to other
visual design tools).<br>
<br>
For this reason the Visual Editor has a separate mechanism to extend a
class's edit time behavior that is done through <span
style="font-style: italic;">override</span> files<span
style="font-style: italic;">.</span> This works in conjunction with
the BeanInfo mechanism and provides the ability to leverage any Eclipse
IDE or Visual Editor specific behavior for a class.</p>
<h2><a name="The_EMF_override_mechanism"></a>The EMF override mechanism</h2>
<p>At the heart of the Visual Editor is an EMF model that describes a
class being edited.&nbsp; This model describes the instances, their
relationships, scope, and property settings. Instances of objects in
this model implement <span style="font-family: monospace;">org.eclipse.jem.internal.instantiation.base.IJavaInstance</span>.&nbsp;
For example, a visual editor class that has a <span
style="font-family: monospace;">Shell</span> whose size is 200,200
will contain two <span style="font-family: monospace;">IJavaInstance</span>
objects.&nbsp; The first of these is for the <span
style="font-family: monospace;">Shell</span> itself and the second is
for a <span style="font-family: monospace;">Point</span> representing
the size.&nbsp; An EMF relationship between the <span
style="font-family: monospace;">Shell</span> and the <span
style="font-family: monospace;">Point</span> instance will exist whose
structural feature represents the size property.<br>
<br>
EMF is a self describing structure, so behind the instance model there
is a meta-model that describes the classes themselves - their methods,
properties, events and hierarchy. The meta-model is created by the
Visual Editor using a combination of reflection and JavaBeans
Introspection.&nbsp; Instances in this metamodel consist of <span
style="font-family: monospace;">org.eclipse.jem.java.JavaClass</span>&nbsp;
for each Java class.&nbsp; The structural features in the model are
instances of EReference and represent the properties of the Java class.</p>
<p>There are times when it is necessary to provide additional
information that should be merged in with the EMF model of a
JavaClass.&nbsp; An example of this is a new feature has to be added
over and above those that can be determined by reflection.</p>
<p>The Visual Editor uses the EMF model of a JavaClass not only to
define its shape but also to define a number of helper classes used by
the Visual Editor.&nbsp; These are typically mediator classes that are
used by the different Visual Editor subsystems.&nbsp; The names of the
mediator classes to use for a given JavaClass are held in the EMF
model, thereby allowing specific classes to have custom behavior for
each subsystem.&nbsp; Rather than hold these directly against the
JavaClass (which is a generic model of Java classes that can be used by
Eclipse plugins other than the Visual Editor)&nbsp; they are held
against decorator classes that annotate the descriptive information of
a class.&nbsp; These can be thought of similar to key value pairs that
hold information rather than provide functionality.&nbsp;</p>
<p>In summary, override files are used as means to modify, add to or
delete from an EMF JavaClass whose shape is determined through using
standard Java reflection combined with BeanInfo introspection.</p>
<p>For a plugin to contribute override files its plugin manifest must
implement the extension point <span style="font-style: italic;">org.eclipse.jem.beaninfo.registrations</span>.&nbsp;
This specifies the trigger in the build path that will cause the
overrides to be applied (either a classpath container or pre-requisite
project) as well as the name of a Java package and where override files
for its contents are held within the plugin folder structure.&nbsp; The
code below shows the extension used for the plugin.xml for the <span
style="font-style: italic;">org.eclipse.ve.examples.customwidget</span>
example in this tutorial.</p>
<pre> &lt;extension<br> point="org.eclipse.jem.beaninfo.registrations"&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> &lt;registration container="org.eclipse.ve.example.PrompterContainer"&gt;<br> &lt;override<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> package="org.eclipse.ve.example.customwidget.prompter"<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> path="overrides/org/eclipse/ve/example/customwidget/prompter"&gt;<br> &lt;/override&gt;<br> &lt;/registration&gt;<br> &lt;/extension&gt;<br></pre>
<p>The classpath container with an id of <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> is
the one used by the <span style="font-style: italic;">Custom Prompter</span>
library.&nbsp; The class being overriden is <span
style="font-family: monospace;">org.eclipse.ve.example.customwidget.prompter.MyCustomPrompter</span>
so its<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> package is declared together with&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> a
folder location for where the override files will be stored.&nbsp; The
location of the override folder is up to the creator of the plugin and
is any arbitrary folder, however there is a convention that the Visual
Editor uses where override files are held in a top level folder called <span
style="font-style: italic;">overrides</span> and then sub folders
created for the package path. &nbsp; The Figure below shows the
directory structure of the <span style="font-style: italic;">org.eclipse.ve.example.customwidget</span>
plugin with the folder structure of <span style="font-style: italic;">/overrides/org/ecliose/ve/example/customwidget/prompter</span>
(which matches that defined in the registration path=<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">
extension point).&nbsp;</p>
<p><img style="border: 1px solid ; width: 361px; height: 253px;" alt=""
src="images/OverrideFileStructure.png"></p>
<p>The Figure also shows a file <font face="Courier New">MyCustomPrompter.override</font>
present in the override directory for the package.&nbsp; When the
Visual Editor builds up the EMF JavaClass instance representing the
shape of the MyCustomPrompter class this file will be read and merged
into the definition.&nbsp; The syntax of this file can become complex
due to the number of different ways in which different JavaClasses
needed to be leveraged to implement custom functionality.&nbsp;&nbsp;
The remainder of the three examples in this tutorial are each achieved
through settings in the .override file.&nbsp; These are:</p>
<ul>
<li>Custom cell editing for the text property</li>
<li>Overriding a GEF edit part</li>
<li>Overriding an expression decoder</li>
</ul>
<p>Each of these three is done through adding decorator classes.&nbsp;
Decorator classes are added to ECore elements in the EMF model
representing a class, either the JavaClass itself or an EReference
representing one of its structural features&nbsp;&nbsp; Decorators are
added through the &lt;annotations&gt; property of an ECore object.</p>
<p>The type <span style="font-family: monospace;">org.eclipse.ve.internal.cde.decorators.BasePropertyDecorator</span>
is responsible for specifying property sheet information such as the
name of the classes for the JFace label provider or cell editor, or
whether the entry in the property sheet should override the default
behavior for whether it is expandable, whether null values are allowed,
etc...</p>
<p>The type <span style="font-family: monospace;">org.eclipse.ve.internal.cde.decorators.ClassDescriptorDecorator</span>
is responsible for specifying custom GEF behavior such as custom edit
parts for the graphical editor or the Java Beans tree view.</p>
<h2><a name="Creating_A_SWT_cell_editor">Custom cell editing for the <span
style="font-style: italic;">text</span> property</a></h2>
<p>Because <span style="font-family: monospace;">MyCustomPrompterBeanInfo</span>
returns a <span style="font-style: italic;">text <span
style="font-family: monospace;">PropertyDescriptor</span></span> <span
style="font-family: monospace;"><span
style="font-family: arial,helvetica,geneva;">in</span></span> list of
properties from the method <span style="font-family: monospace;">getPropertyDescriptors()[]</span>
it will be included as an entry in the Properties view.&nbsp; Even
without the explicit BeanInfo the class's signature includes the two
methods <span style="font-family: monospace;"><span
style="color: rgb(153, 0, 0);">public</span> String getText()</span>
and <span style="font-family: monospace; color: rgb(153, 0, 0);">public</span>
<span style="font-family: monospace;">void setText(String aText)</span>
which, because they follow the JavaBeans specification naming
convention for a property's get and set methods, would be automatically
detected by the Visual Editor through Introspection.</p>
<p>The rules for the Properties view is that for a given property a
BasePropertyDecorator is first looked for on the EReference
representing the property in the EMF model.&nbsp; If one is found and
it has an explicit labelProviderClassName or cellEditorClassName then
this is used as appropiate.&nbsp; This is the mechanism that will be
used for the <span style="font-style: italic;">text</span>
property.&nbsp; If no decorator exists in the property defining an
editor then if the EReference came originally through introspection the
java.beans.PropertyDescriptor is queried to look for a
propertyEditorClass or key of <span style="font-style: italic;">enumerationValues.&nbsp;</span>
Failing both of these a default editor is used for the type of the
property.</p>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;">
To determine the default editor for a property based on its type a <span
style="font-family: monospace;">BasePropertyDecorator</span> on the <span
style="font-family: monospace;">JavaClass</span> EMF definition is
used.&nbsp; If no direct decorator can be found annotating the <span
style="font-family: monospace;">JavaClass</span> then the superclass
chain is searched to look for a decorator that provides a custom cell
editor or label provider. For example, the <span
style="font-style: italic;">text</span> property is typed to <span
style="font-family: monospace;">java.lang.String</span> and the plugin
<span style="font-style: italic;">org.eclipse.ve.java.core</span>
provides a <span style="font-style: italic;">String.override</span>
file that annotates the <span style="font-family: monospace;">JavaClass</span>
with a a <span style="font-family: monospace;">BasePropertyDecorator</span>
defining the label provider as <span style="font-family: monospace;">org.eclipse.ve.internal.java.core.StringJavaLabelProvider</span>
and the cell editor as <span style="font-family: monospace;">org.eclipse.ve.internal.java.core.StringJavaCellEditor.</span>&nbsp;
This is an example of where the Visual Editor's implementations of the
JFC and SWT are done thoroughly using its own API.</p>
<p>The cell editor that will be written for the <span
style="font-style: italic;">text</span> property will be placed in the
package <span style="font-family: monospace;">org.eclipse.ve.example.customwidget</span>.&nbsp;
This package will form part of the contents of the plugin jar that
makes up the code that runs in the workbench and extends the Visual
Editor with new Eclipse workbench behavior.&nbsp; The class created is <span
style="font-family: monospace;">org.eclipse.ve.example.customwidget.CustomLabelEditor</span>
and extends the abstract superclass <span
style="font-family: monospace;">org.eclipse.jface.viewers.DialogCellEditor</span>.&nbsp;</p>
<p>IDE specific extensions are defined by annotating the EMF JavaClass
meta object that the Visual Editor uses.&nbsp; This is done with a
.override file, and the contents of <span style="font-style: italic;">MyCustomPrompter.override</span>
should be written as follows:</p>
<pre> &lt;?xml version="1.0" encoding="UTF-8"?&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> &lt;xmi:XMI xmi:version="2.0" <br> xmlns:xmi="http://www.omg.org/XMI" <br> xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"<br> xmlns:org.eclipse.ve.internal.cde.decorators="http:///org/eclipse/ve/internal/cde/decorators.ecore"<br> xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore" <br> xmlns:event="event.xmi"&gt;<br><br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> &lt;event:Add featureName="eStructuralFeatures"&gt;<br> &lt;addedEObjects xsi:type="ecore:EReference" <img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif">name="text" unsettable="true"&gt;<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif"> &lt;eAnnotations<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_5.gif"> xsi:type="org.eclipse.ve.internal.cde.decorators:BasePropertyDecorator" <br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_6.gif"> cellEditorClassname="org.eclipse.ve.example.customwidget/org.eclipse.ve.example.customwidget.CustomLabelEditor"/&gt;<br> &lt;/addedEObjects&gt;<br> &lt;/event:Add&gt;<br><br> &lt;/xmi:XMI&gt;<br></pre>
<p>The header of a .override file declares the namespaces of the EMF
packages used.&nbsp; Two packages are required to define the objects
required for the CustomLabelEditor, the&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif">
decorators.ecore package and the event model's package.</p>
<p>The purpose of the file is to create a BasePropertyDecorator that
defines the cell editor and annotate the structural feature for the <span
style="font-style: italic;">text</span> property.&nbsp; This is done
by&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> adding a structural feature whose name is <span
style="font-style: italic;"><img style="width: 24px; height: 13px;"
alt="" src="../images/tag_3.gif"></span> <span
style="font-style: italic;">text.&nbsp;</span> Even through the object
used is an <span style="font-style: italic;">Add</span> from the event
model, the Visual Editor will pick up the fact that there is a <span
style="font-style: italic;">text</span> property defined from
introspection (the one explicitly specified in the
MyCustomPrompterBeanInfo or in its absence the one determined through
get and set method pair matching) and merge in with this
property.&nbsp; This way information that has come from introspection
such as the get and set method names are combined with the EReference
defined in the .override file.</p>
<p>The&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_4.gif"> eAnnocations property defines the
annotations for the EReference and the class we're creating is an
instance of <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_5.gif"> <font face="Courier New">org.eclipse.ve.internal.cde.decorators.BasePropertyDecorator</font>.&nbsp;
<img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;"> The <a name="xsi:type_structure"></a>xsi:type
structure does not point to the
Java package directly.&nbsp; The first portion of
org.eclipse.ve.internal.cde.decorators points to the name of a
namespace defined in the&nbsp;<img style="width: 24px; height: 13px;"
alt="" src="../images/tag_1.gif"> xmi:XMI opening tag.&nbsp; This
namespace relates to the URL of decorators.ecore EMF package that
itself is declared in the plugin org.eclipse.ve.cde with its own use of
the extension point <span style="font-style: italic;">org.eclipse.emf.ecore.generated_package</span>
to be the EMF package class
org.eclipse.ve.internal.cde.decorators.DecoratorsPackage.</p>
<p>The class
org.eclipse.ve.internal.cde.decorators.BasePropertyDecorator has an EMF
feature&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_6.gif"> cellEditorClassname.&nbsp; This will be
used by the Visual Editor in the Properties view when the property is
edited and points to our custom editor.</p>
<p>Having defined the .override file that extends the <span
style="font-family: monospace;">MyCustomPrompter</span>'s <span
style="font-style: italic;">text</span> feature to have a custom IDE
cell editor the next step is to write the code for the custom editor
itself.&nbsp; <span style="font-family: monospace;">CustomLabelEditor</span>
extends DialogCellEditor that provides the framework support for
displaying a button to open the actual dialog.&nbsp;</p>
<p><img style="border: 1px solid ; width: 211px; height: 46px;" alt=""
src="images/TextPropertyCellEditor.png"></p>
<p>The next step is to write the dialog that allows the user to edit
the <span style="font-style: italic;">text</span> property and ensure
that this is launched from CustomLabelEditor.</p>
<p>The dialog is created by extending the JFace helper class <span
style="font-family: monospace;">org.eclipse.jface.dialogs.TitleAreaDialog</span>
that provides support for the title area and buttons.&nbsp; The content
or client area of this will be built using the Visual Editor itself as
a visual component class <span style="font-family: monospace;">org.eclipse.ve.example.customwidget.LabelDialogContentArea.</span></p>
<p><img style="width: 719px; height: 524px;" alt=""
src="images/CustomTextEditorDialog.png"></p>
<p>&nbsp;</p>
<p>To logic for what occurs when the dialog is requested to be open is
done by specializing the method <span style="font-family: monospace;">openDialogBox(Control
cellEditorWindow)</span> in <span style="font-family: monospace;">CustomLabelEditor<span
style="font-family: arial,helvetica,geneva;">.</span></span> The
contents for this method are shown below and perform two important
steps.&nbsp; The first of these is to open an actual dialog that lets
the user specify their text property, and the second is to get the
result of this and create a new <span style="font-family: monospace;">IJavaInstance</span>
that represents the next String for the Visual Editor's EMF instance
model.&nbsp; The code below shows how to do this for <span
style="font-family: monospace;">CustomLabelEditor</span>.</p>
<pre><span style="color: rgb(153, 0, 0);">protected</span> Object openDialogBox(Control cellEditorWindow) {<br> Display display = cellEditorWindow.getDisplay();<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> TitleAreaDialog dialog = <span
style="color: rgb(153, 0, 0);">new</span> TitleAreaDialog(display.getActiveShell()) {<br> LabelDialogContent content;<br> <span
style="color: rgb(153, 0, 0);">protected</span> Control createContents(Composite parent) {<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_2.gif"> Control result = super.createContents(parent);<br> setTitleImage(CustomwidgetPlugin.getCustomImage());<br> setTitle(<span
style="color: rgb(51, 51, 255);">"Prompter's text property editor"</span>);<br> setMessage(<span
style="color: rgb(51, 51, 255);">"Enter the text property, or select a default one by checking the Hello or GoodBye"</span>,IMessageProvider.<span
style="font-style: italic;">INFORMATION</span>); <br> <span
style="color: rgb(153, 0, 0);">return</span> result;<br> }<br> <span
style="color: rgb(153, 0, 0);">protected</span> Control createDialogArea(Composite parent) {<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_3.gif"> content = <span
style="color: rgb(153, 0, 0);">new</span> LabelDialogContent(parent, SWT.<span
style="font-style: italic; color: rgb(51, 51, 255);">NONE</span>);<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif"> content.setString(stringValue);<br> <span
style="color: rgb(153, 0, 0);">return</span> content;<br> }<br> <span
style="color: rgb(153, 0, 0);">public</span> String toString() {<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_5.gif"> <span
style="color: rgb(153, 0, 0);">return</span> content.getString();<br> }<br> }; <br> <span
style="color: rgb(153, 0, 0);">if</span> (dialog.open() != Window.<span
style="font-style: italic; color: rgb(51, 51, 255);">CANCEL</span>) {<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_6.gif"> <span
style="color: rgb(153, 0, 0);">return</span> createStringJavaObject(dialog.toString());<br> } <span
style="color: rgb(153, 0, 0);">else</span> { <span
style="color: rgb(153, 0, 0);"> return</span> getValue();<br> }<br> }<br></pre>
<p>The dialog editor used is an&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif">
inner class that extends the jface abstract class
org.eclipse.jface.dialogs.TitleAreaDialog.&nbsp; Three methods are
specialized:</p>
<p>The createContents(Composite parent) method is used to build the
actual SWT content area of the dialog.&nbsp; The TitleAreaDialog
supeclass provides a default structure that is invoked through
calling&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_2.gif"> <span style="font-family: monospace;">super.createContents(parent)</span>,
although details such as the image and title are overridden. The
content area of the dialog is the area we're interested in putting out
custom editing experience into, and this is done by creating an
instance of&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_3.gif"> <span style="font-family: monospace;">LabelDialogContent</span>
(that is built below).</p>
<p>The content area for the TitleAreaDialog created by the
LabelCellEditor is the class
org.eclipse.ve.examples.customwidget.LabelDialogContent.&nbsp; This is
available in CVS <a
href="http://dev.eclipse.org/viewcvs/indextools.cgi/%7Echeckout%7E/org.eclipse.ve.examples/org.eclipse.ve.example.customwidget/src/org/eclipse/ve/example/customwidget/LabelDialogContent.java">LabelDialogContent.java</a>
and extends <span style="font-family: monospace;">org.eclipse.swt.Composite</span>
and was built using the Visual Editor.&nbsp; This has the methods <span
style="font-family: monospace;">public setString(String aString)</span>
to set the current value of the String, and <span
style="font-family: monospace;">public String getString()</span> to
return it.&nbsp; These are both called by the <span
style="font-family: monospace;">CustomLabelEditor</span> when it&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_4.gif">
initializes the content area and&nbsp;<img
style="width: 24px; height: 13px;" alt="" src="../images/tag_5.gif">
returns the value.&nbsp;</p>
<p>The <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_5.gif"> <span style="font-family: monospace;">toString()</span>
method is specialized to return the value of the LableDialogContent,
which represents the String entered by the user as the new <span
style="font-style: italic;">text</span> property.&nbsp; This is so
that the value can be referenced by the CustomLabelEditor itself when
it <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_6.gif">has created the actual object that will be
set into the Visual Editor model.</p>
<p>If the TitleAreaDialog isn't cancelled then the JFace cell editor
needs to return the value of the newly created object representing the
value of the <span style="font-style: italic;">text</span>
property.&nbsp; The LabelDialogContent returns a java.lang.String and
this requires conversion into an IJavaInstance representing the EMF
JavaClass instance for the Visual Editor's model.&nbsp; This is done
with the helper method&nbsp;<img style="width: 24px; height: 13px;"
alt="" src="../images/tag_6.gif"> <span style="font-family: monospace;">IJavaInstance
createStringJavaObject(String aString);</span></p>
<p>To create an <span style="font-family: monospace;">IJavaInstance</span>
requires two steps.&nbsp; First the EMF <span
style="font-family: monospace;">JavaClass</span> needs to be located
and then an instance of <span style="font-family: monospace;">IJavaInstance</span>
needs to be created using this with rules as to how the actual
instantion of the live Java object should occur (both in code and by
the target VM).</p>
<p>To locate a <span style="font-family: monospace;">JavaClass</span>
involves looking up for the object on the current resource set.&nbsp; A
resource set is a physical grouping of EMF documents and to locate the
one being used by the Visual Editor it is held on the editorPart's GEF
editDomain.&nbsp; The Visual Editor uses a subclass of default GEF edit
domain called <span style="font-family: monospace;">org.eclipse.ve.internal.cde.core.EditDomain</span>.&nbsp;
The editDomain provides a way of passing common objects (such as the
target VM helper classes, the set of viewers, and the EMF resource set)
around between different Visual Editor subsystems.&nbsp; For a cell
editor to be given a reference to the edit domain it should implement
the interface <span style="font-family: monospace;">org.eclipse.ve.internal.propertysheet.INeedData</span>
that has a single method <span style="font-family: monospace;">public
void setData(Object data);&nbsp;</span> The argument to this will be
set by the Visual Editor to the editDomin object and the cell editor
should store this in an instance variable.</p>
<pre><span style="font-family: monospace;"><span
style="color: rgb(153, 0, 0);">public class</span> CustomLabelEditor <span
style="color: rgb(153, 0, 0);">extends</span> DialogCellEditor <span
style="color: rgb(153, 0, 0);">implements</span> INeedData {<br> private EditDomain fEditDomain;<br></span><span
style="font-family: monospace;"><span style="font-family: monospace;"><span
style="color: rgb(51, 204, 0);"><span style="color: rgb(0, 153, 0);"> // Remainder of class definition ...</span></span></span><br></span></pre>
and<br>
<pre> <span style="color: rgb(153, 0, 0);">public void</span> setData(Object data) {<br> fEditDomain = (EditDomain) data;<br> }<br></pre>
<p>To lookup the resource set from an EditDomain can be done using the
static helper method<span style="font-family: monospace;">JavaEditDomainHelper.getResourceSet(EditDomain
anEditDomain);</span></p>
<p>Now that the <span style="font-family: monospace;">CustomLabelEditor</span>
has a handle to the Visual Editor's model's resource set it can look up
<span style="font-family: monospace;">JavaClass</span> objects using
the API <span style="font-family: monospace;">org.eclipse.jem.internal.beaninfo.core.Utilities.getJavaClass(String
className, ResourceSet resourceSet);</span>&nbsp;&nbsp;&nbsp; In EMF to
instantiate actual objects the package's factory should be used, so
having obtained the <span style="font-family: monospace;">JavaClass</span>
to get the <span style="font-family: monospace;">IJavaInstance</span>
requires the method call <span style="font-family: monospace;">javaClass.getEPackage().getEFactoryInstance().create(javaClass);</span>&nbsp;</p>
<p>Rather than having to do both steps however there is a helper API
method <span style="font-family: monospace;">org.eclipse.ve.internal.java.core.BeanUtilities.createJavaObject(String
qualifiedClassName, ResourceSet aResourceSet, String initString)</span>;&nbsp;
Examples of its usage are shown below:</p>
<pre>BeanUtilities.createJavaObject(<span
style="color: rgb(51, 51, 255);">"java.lang.Boolean"</span>, aResourceSet, <span
style="color: rgb(51, 51, 255);">"Boolean.TRUE"</span>); <span
style="color: rgb(0, 153, 0);">// Create a Boolean.TRUE instance</span><br>BeanUtilities.createJavaObject(<span
style="color: rgb(51, 51, 255);">"java.awt.Color"</span>, aResourceSet , <span
style="color: rgb(51, 51, 255);">"java.awt.Color.red"</span>); <span
style="color: rgb(0, 153, 0);">// Create an instance of the AWT color red</span><br>BeanUtilities.createJavaObject(<span
style="color: rgb(51, 51, 255);">"boolean"</span>, aResourceSet, <span
style="color: rgb(51, 51, 255);">"true"</span>); <span
style="color: rgb(0, 153, 0);">// Create an instance of the primitive boolean true</span><br>BeanUtilities.createJavaObject(<span
style="color: rgb(51, 51, 255);">"java.lang.String"</span>, aResourceSet, <span
style="color: rgb(51, 51, 255);">"\\"Hello World\\""</span>); <span
style="color: rgb(0, 153, 0);">// Create an instance of the String "Hello World"</span>
</pre>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;">
The third argument to the method represents the code fragment that will
be used to instantiate the actual live Java instance.&nbsp; This is the
actual argument that is used by the Visual Editor when it generates the
<span style="font-family: monospace;">setProperty(Object propertyValue)</span>
method.&nbsp; For the last example that was itself a String for the
quotation marks to be present in the String when the code is generated
they must be present in the literal itself which requires escaping them
with a <span style="color: rgb(51, 51, 255);">\\.</span></p>
<p>The protected helper method on <span style="font-family: monospace;">CustomLabelEditor</span>
and called by <img style="width: 24px; height: 13px;" alt=""
src="../images/tag_6.gif"> <span style="font-family: monospace;">openDialogBox(Control
cellEditorWindow)</span> can now be written as follows.</p>
<pre> <span style="color: rgb(153, 0, 0);">private</span> IJavaInstance createStringJavaObject(String aString) {<br> <span
style="color: rgb(153, 0, 0);">return</span> BeanUtilities.createJavaObject(<br> <span
style="color: rgb(51, 51, 255);">"java.lang.String"</span>,<br> JavaEditDomainHelper.getResourceSet(fEditDomain),<br><img
style="width: 24px; height: 13px;" alt="" src="../images/tag_1.gif"> BeanUtilities.createStringInitString(aString)<br> );<br> }<br></pre>
<p>Rather than just writing <span style="color: rgb(51, 51, 255);">"\\"</span>
+ aString + <span style="color: rgb(51, 51, 255);">"\\"</span> a
helper method on&nbsp;<img style="width: 24px; height: 13px;" alt=""
src="../images/tag_1.gif"> <span style="font-family: monospace;">BeanUtilities</span>
is used to quote the user's string.&nbsp; The helper handles cases such
as the string containing bona-fide escape characters the user put there
that themselves need quoting.</p>
<h3><a name="Rendering_the_text_value_in_the"></a>Rendering the <span
style="font-style: italic;">text value&nbsp;</span> in the Properties
view</h3>
<p>When the <span style="font-style: italic;">text</span> property is
displayed in the Properties view we wish the user to be able to see the
current value.&nbsp; This occurs with nothing extra to be done, because
the <span style="font-style: italic;">text</span> property is typed to
<span style="font-family: monospace;">java.lang.String</span> and there
is a default label provider class for this provided by the <span
style="font-style: italic;">org.eclipse.ve.java.core</span> plugin as
part of its <span style="font-style: italic;">String.override</span>.&nbsp;
For this reason file the Visual Editor already knows how to render
String properties as shown below.</p>
<p><span style="font-family: monospace;"><img
style="border: 1px solid ; width: 266px; height: 63px;" alt=""
src="images/TextPropertyDisplayed.png"></span></p>
<p>With the CustomLabelEditor however specific code is required to
ensure that it displays the current value of the <span
style="font-style: italic;">text</span> property</p>
<p><img style="border: 1px solid ; width: 265px; height: 66px;" alt=""
src="images/TextCurrentValue.png"></p>
<p>This is done by specializing the method <span
style="font-family: monospace;">doSetValue(Object value);&nbsp;</span>
This method is given an argument of an <span
style="font-family: monospace;">IJavaInstance</span> which represents
the current value of the String object in the Visual Editor's EMF
model.&nbsp; To convert from this to this to a <span
style="font-family: monospace;">java.lang.String</span> object can be
done by accessing the target VM to query the value of the live String
object.</p>
<p>To write the code for the <span style="font-family: monospace;">doSetValue(Object
value)</span> method requires an understanding of the API to work with
the Visual Editor target VM objects</p>
<h4><a name="Target_VM_and_its_APIs"></a>Target VM and its APIs</h4>
<p>Live objects used by the Visual Editor exist only on the target VM
and are never loaded by the Visual Editor inside the actual Eclipse
workbench's JVM.&nbsp; For every object created on the target VM there
is a proxy to it held by the Visual Editor inside the Eclipse
JVM.&nbsp;&nbsp;&nbsp; This proxy is an instance of <span
style="font-family: monospace;">org.eclipse.jem.internal.proxy.core.IBeanProxy</span>
and is able to perform tasks such as remote method&nbsp; invocation on
the actual target VM instance.<br>
<br>
The API for this is modelled on the<span style="font-family: monospace;">java.lang.reflect</span>
API however, unlike the reflection API which performs dynamic
invocation within a single JVM, the bean proxy mechanism works between
the Eclipse workbench's JVM where the proxies are, and Visual Editor's
target JVM where the live instances exist.</p>
<table style="text-align: left; width: 75%;" border="1" cellspacing="2"
cellpadding="2">
<tbody>
<tr>
<td style="vertical-align: top;">java.lang and java.lang.reflect
API</td>
<td style="vertical-align: top;">org.eclipse.jem.internal.proxy.core
API</td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Object</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBeanProxy</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Class</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBeanTypeProxy</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">object.getClass()</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBeanProxy.getTypeProxy()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Method</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IMethodProxy</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Class.getMethod(String methodName)</span>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBeanTypeProxy.getMethodProxy(String
methodName)</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Constructor</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IConstructorProxy</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Class.getConstructor(Class[] types)</span>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBeanTypeProxy.getConstructorProxy(IBeanTypeProxy[]
types)</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">Constructor.newInstance(Object[]
initArgs)</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IConstructorProxy.newInstance(IBeanProxy[]
initArgs)</span> </td>
</tr>
</tbody>
</table>
<p>To locate instances of <span style="font-family: monospace;">IBeanProxy</span>
(from which method and constructor proxies can be retrieved) a factory
is used that is held on a proxy factory registry.&nbsp; The registry is
used to create and cache instances of <span
style="font-family: monospace;">IBeanTypeProxy</span>, and can be
located through a helper method which retrieves it from the GEF edit
domain.&nbsp; The <span style="font-family: monospace;">IProxyFactoryRegistry</span>
can return factories for retrieving instances of IBeanTypeProxy through
the method getBeanTypeProxy(String typeName) as well as factories for
creating new instances of <span style="font-family: monospace;">IBeanProxy</span>
through the overloaded method <span style="font-family: monospace;">getBeanProxy(Object
anObject)</span> with arguments representing the nine Java primitives,
their <span style="font-family: monospace;">java.lang</span> peers as
well as <span style="font-family: monospace;">java.lang.String</span>.</p>
<p>The following code samples show how to create an instance of a <span
style="font-family: monospace;">java.io.File</span> for the file name <span
style="font-style: italic;">"C:\temp\foo.txt"</span> (i.e. the result
of evaluating <span style="font-family: monospace;"><span
style="color: rgb(153, 0, 0);">new</span> java.io.File(<span
style="color: rgb(51, 51, 255);">"C:\temp\foo.txt"</span>)</span> on
the target VM.</p>
<pre>IProxyFactoryRegistry aProxyFactoryRegistry = JavaEditDomainHelper.getBeanProxyDomain(anEditDomain).getProxyFactoryRegistry();<br>IBeanTypeProxy javaIOFileBeanTypeProxy = aProxyFactoryRegistry.getBeanTypeProxy(<span
style="color: rgb(51, 51, 255);">"java.io.File"</span>);<br></pre>
<p>Having obtained the <span style="font-family: monospace;">IBeanTypeProxy
<span style="font-family: arial,helvetica,geneva;">the instance of</span></span>
an <span style="font-family: monospace;">IBeanProxy</span> for the
java.io.File can be created by locating the correct <span
style="font-family: monospace;">IConstructorProxy</span> and calling <span
style="font-family: monospace;">newInstance(IBeanProxy[])</span> with
the correct arguments.</p>
<pre>IBeanProxy fooStringBeanProxy = aProxyFactoryRegistry.getBeanProxyFactory().createBeanProxyWith(<span
style="color: rgb(51, 51, 255);">"C:\temp\foo.txt"</span>);<br>IConstructorProxy fileConstructorProxy = javaIOFileBeanTypeProxy.getConstructorProxy(<span
style="color: rgb(51, 51, 255);">"java.lang.String"</span>);<br>IBeanProxy fileProxy = fileConstructorProxy.newInstance(fooStringBeanProxy);<br></pre>
<p>In addition to locating the IConstructorProxy and invoking as shown
above there is a shorthand way of creating a bean proxy with a specific
Java initialization string.&nbsp; This is with the method <span
style="font-family: monospace;">newInstance(String
javaInitializationString)</span> on <span
style="font-family: monospace;">IBeanTypeProxy</span>.&nbsp; Using
this the above code can be shortened to</p>
<pre>IBeanProxy fileProxy = javaIOFileBeanTypeProxy.newInstance(<span
style="color: rgb(51, 51, 255);">"C:\temp\foo.txt"</span>);<br></pre>
<p>The Visual Editor's model for the Java class being visually is an
EMF graph of <span style="font-family: monospace;">IJavaInstance</span>
objects. The API method <span style="font-family: monospace;">org.eclipse.jem.internal.proxy.core.BeanProxyUtilities.getBeanProxy(IJavaInstance
aJavaInstance)</span> exists to obtain the bean proxy fom a Visual
Editor EMF object.&nbsp; These are some more examples of the API for
working with bean proxies.</p>
<pre><span style="color: rgb(0, 153, 0);">// Retrieve a proxy to the result of calling the method getType() on a target VM for an IJavaInstance of MyCustomPrompter</span><br>IBeanProxy prompterProxy = BeanProxyUtilities.getBeanProxy(prompterJavaInstance); <span
style="color: rgb(0, 153, 0);">// Obtain an IBeanProxy from an IJavaInstance</span><br>IMethodProxy getTypeMethodProxy = prompterProxy.getTypeProxy().getMethodProxy(<span
style="color: rgb(51, 51, 255);">"getType"</span>);<br>IBeanProxy proxyToGetTypeResult = getTypeMethodProxy.invoke(prompterProxy);<br><br><span
style="color: rgb(0, 153, 0);">// Set the value of setType(String) method to the value "Frog"<br></span>IBeanProxy frogProxy = prompterProxy.getProxyFactoryRegistry().getBeanProxyFactory().createBeanProxyWith(<span
style="color: rgb(51, 51, 255);">"Frog"</span>);<br>IMethodProxy setTypeMethodProxy = prompterProxy.getTypeProxy().getMethodProxy(<span
style="color: rgb(51, 51, 255);">"setType"</span>,<span
style="color: rgb(51, 51, 255);">"java.lang.String"</span>);<br>setTypeMethodProxy.invoke(prompterProxy,frogProxy);<br></pre>
<p>Working with remote proxies from the Eclipse workbench's JVM that
point to instances of real live objects in the Visual Editor's target
JVM provides a way of ensuring that the two are totally insultated and
no class within the user's build path of a Java project needs to be
loaded by the class loader or instantantiated within Eclipse.&nbsp;
This provides a true editing sandbox which allows multiple instances of
classes to exist across different editors working with different build
paths and is the design principle that allows the Visual Editor to be
extended to support new target environment and topologies other than
just pure Java.&nbsp; However at some point the Visual Editor does need
to transport objects back from the target JVM to Eclipse.&nbsp; An
example of this is that having got an <span
style="font-family: monospace;">IBeanProxy</span> for a rectangle
result to the <span style="font-family: monospace;">getBounds()</span>
method this must be converted in its four constituient int values so
that a draw2D rectangle can be created for the GEF figure.&nbsp;
Likewise the Properties view shows the user the values of the target VM
objects.&nbsp; The point at which an object on the target VM can be
retrieved within the Eclipse workbench is when it is a primitive object
or a java.lang peer of a primitive or a String instance.&nbsp; This is
done by having four subinterfaces of <span
style="font-family: monospace;">IBeanProxy</span> in the package <span
style="font-family: monospace;">org.eclipse.jem.internal.proxy.core</span>.</p>
<table cellpadding="2" cellspacing="2" border="1"
style="text-align: left; width: 50%;">
<tbody>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;">java.lang Object lookup</td>
<td style="vertical-align: top;">primitive lookup</td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IStringBeanProxy</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">java.lang.String stringValue()</span> </td>
<td style="vertical-align: top;"> <br>
</td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">IBooleanBeanProxy</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">java.lang.Boolean getBooleanValue()</span>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">boolean booleanValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">ICharacterBeanProxy</span> </td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">java.lang.Character characterValue()</span>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">char charValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"><span
style="font-family: monospace;">INumberBeanProxy</span> </td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">int intValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">long longValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">byte byteValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">short shortValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">float floatValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">double doubleValue()</span> </td>
</tr>
<tr>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"> <br>
</td>
<td style="vertical-align: top;"><span
style="font-family: monospace;">number numberValue()</span> </td>
</tr>
</tbody>
</table>
<br>
<p><img src="../images/note.gif" alt="Note:"
style="width: 62px; height: 13px;">
It is possible to register custom sub instances of <span
style="font-family: monospace;">IBeanProxy</span> for plugin specific
objects and this occurs with <span style="font-style: italic;">org.eclipse.ve.jfc</span>
plugin that has introduces the types <span
style="