Dimitry Karpenko
Java/Eclipse developer in MyEclipse and Webclipse teams.
Posted on May 30th 2016

In previous articles, I’ve discussed how to create custom XML bindings and custom editing UI for an editor based on the great Eclipse Sapphire framework. Now let’s take a look at another aspect of editor UI creation, customizing standard actions like Add or Browse, or creating completely custom actions for your Sapphire-based editor.


As in previous articles, it is good to know basic Eclipse plug-in development and Sapphire framework principles.

In this example, Sapphire 9 is used. To download it, go to https://eclipse.org/sapphire/releases/9/.

For Sapphire documentation, refer to https://eclipse.org/sapphire/releases/9/documentation/index.html.

Also, this article doesn’t completely describe action or browsing customization API supported by Sapphire, for more information refer to the following:

Sample Project

Let’s create an editor for plugin_info.xml—syntethic sample file, which contains the project id from the workspace and the list of plugins on which this project depends. You need to create an Eclipse plugin project making UI contributions and put standard Sapphire editor infrastructure inside it. Please refer to the sample below or Sapphire help for details.


There are only 2 model classes in our sample project—IPluginsInfo is a root model class containing ProjectName string value property for the project name and Plugins list property containing the plugins list. Each element of that list is an instance of IPluginDescr model class, which only contains a single property, Name.


So, let’s start and create an editor for the project name property. For user convenience, let’s add the ability to select a project from the workspace. To do this, we’ll need to specify a custom Browse action handler in the sdef file.

Handler implementation is extending SapphireActionHandler and has only one method, run, which is pretty straightforward.

Now let’s say we want to create an action which isn’t overriding any standard action, but is completely custom, launching some code on a button click. Custom actions can be added to several different areas of the UI, including the editor page itself, section, etc. Let’s add one more action button to the right of our editing field, which would allow us to launch the import wizard and import a project into the workspace.

Now we’ll need to add two elements into our <property-editor> tag.

In <action> tag, action’s id, textual label and image are specified. In <action-handler> tag, we specify a particular action handler for this action. Handler class is like the previous one, containing overridden run method and one helper method responsible for showing a wizard using its id.


Let’s see how our editor looks after all our customizations:


Handler Parametrization

We can use the same action handler in several places across the editor with little customizations, like different title, initial selections, etc. In these cases, handler can easily be parametrized. Let’s customize dialog title for our project selection dialog—add a param to our sdef file.

To load given param, add init method to your handler.

dialogTitle here is a field, which is set to dialog when creating it. See attached source for more details.

Another customization option is obtaining value from some annotation used with model property. For this, we’ll need to have a simple annotation containing only a string value—DialogTitle, and add it to the model’s ProjectName property:

Also, let’s slightly modify init method to obtain given annotation from the model.

As you can see, using nearest(), property(), definition(), etc. you can walk through Sapphire data and UI models to obtain different settings specified in model or sdef.

Let’s see, how our dialog would look after one of these customizations:


List Editing

But what if we want to customize a bit more complex stuff, like adding a new item to the list of items? This is also possible, however it would require a bit more effort. For the list property editor, we’ll need to specify Action Handler Factory, which would be responsible for creating a custom action handler for the action we want to override. So, our plugin list property editor in sdef file should look like following:

CustomAddActionHandlerFactory is very simple, and just returns a list containing custom handlers—only one handler in our case:

Handler itself is opening a plugin selection dialog with the ability to select a single plugin, and, if selected, add a new item to the list property containing the selected plugin’s id:

Let’s launch our editor and see, whether it works:


Hmm… Why after clicking “+” do we see two items instead of our custom dialog? That’s because we haven’t actually overridden standard add action handler, and a shortcut for it is also being added to “+” action. To get rid of it, we’ll need to add Action Handler Filter to our list property editor.

To do this, let’s add the following under </action-handler-factory> tag in sdef:

Filter class extends SapphireActionHandlerFilter and contains one small method checking handler’s id to cut off unnecessary handlers:

Now, let’s try it…works like a charm!

Can we add a fully custom action to the list property editor? Sure, the way of doing it is quite the same as for the value property editor. Let’s make an action, adding several plugins at once to our list. Add the following inside the <property-editor> tag for Plugins property:

The handler class for it is pretty much like the handler for adding a single plugin name, except configuring the dialog for selecting multiple plugins, and adding selected plugin id’s to a list inside a loop.

Let’s try it:


Works perfectly. So, finally our editor would look like the following:



sapphire_customactions_tutorial—Sample project

Related Articles

Coding Tip: Using Custom Bindings for Property Editing in Sapphire
Creating Custom Editors in Sapphire
Creating a Custom Eclipse Sapphire Editor to Edit Two XML Files Simultaneously

Let Us Hear from You!

If you have any comments or questions, we would love to hear from you @MyEclipseIDE on twitter or via the MyEclipse forum. Happy coding!

If you’re not already subscribing to our blogs, why not do it today?