RAP look and feel
Eclipse RAP provides an API to change the look and feel of a RAP application.
This article is a step-by-step guide to using the this socalled "interaction
design API" to control the look of the WorkbenchWindow. All look and feel artefacts
can be bundled into a separate plug-in and contributed to an existing application
without touching the application itself.
Let's have a look at a RAP application that with a customized look and feel:
Thesea are the elements that we will be working with.
WorkbenchWindow components such as the ToolBar, MenuBar and the ViewToolbar.
Presentations for Stacks or, in other words, the look and feel of views and
editors. You'll see later how the interaction design API allows you to make
stack independent changes on-the-fly.
The graphical layout. When you change the look and feel of an application, you
generally also need to change elements in the graphical layout, such as moving
a menubar or the perspective switcher, or selecting a different font.
Activation by servlet name. You can leverage the servlets in RAP and use the
servlet name to access the whole layout from a single point.
Reusable web components. Elements such as the header for an application are
very likely to be reused in their web versions. Layout information can also be
reused for web components. So a developer has not to develop many different
web components, he can use the technique described bellow to create a component
which can be reused in many applications.
Finally, one additional but important requirement for a good look and feel is
to change interaction concepts to match the new UI. To assist in this, the API
provides an automatic service called personalization. For instance it hides all
ViewActions by default and makes it's visibility customizable.
The best place to start is to create a PresentationFactory. You will need to
create an extension for the
Here is the same as it appears in the plugin.xml.
The presentationFactory contains the following attributes:
The class refers to an implementation of
org.eclipse.rap.ui.interactiondesign.PresentationFactory. It is
very important not to extend from the original
org.eclipse.ui.presentation.AbstractPresentationFactory as this
class does not support the concepts described here.
A human readable name for the PresentationFacotry implementation.
abstract, so you will need to implement its abstract methods. Most are create
methods for different Managers, for example, the MenuBar MenuManager or the
Manager for the ToolBar. A ToolBar or MenuBar manager is a contribution manager
which realizes itself and its items in a control. In these implementations you can
change the look of the components such as styling a toolbar with icons and text
or making it transparent.
Presentations for Stacks
If you are not familiar with the original AbstractPresentationFactory you might
consider reading up on StackPresentations. You'll find a basic overview of the
partstack in the
Inside the Workbench article.
The look and feel of a partstack can be changed using StackPresentations. In the
previous PresentationFactory the presentation had to be implemented
programatically. The interaction design API allows you to declare
StackPresentations as an extension for the extension point
Here is the same as it appears in the plugin.xml.
contain the following attributes:
To be backward compatible with Eclipse 3.4 or earlier, you can
org.eclipse.ui.presentation.StackPresentation. But to use
all the features of the interaction design API the
org.eclipse.rap.ui.interactiondesign.ConfigurableStack. should be
implemented. The ConfigurableStack is an abstract class and provides additional
methods i.e. to get the part's ToolbarManager.
The parts ToolbarManager contains all the actions of the parts toolbar and adds
the personalization features. To create a clean UI all actions are invisible,
but this visibility can be changed by the user during runtime.
Another benefit of the ConfigurableStack is the ability to change the
look of the stack during runtime without reloading the whole
application. Therefore it provides a method called
setCurrentStackPresentation( String id ). The id should be the id
of the presentation defined in the extension. When you call this method, you
will change the presentation of a whole stack to the presentation defined with
the given id. The reloading happens automatically.
There are three types of stacks. Editor-, view- and standaloneViewStacks. You
can define a presentation for a specific type using the following arguments:
view, standaloneView, editor.
This should be an implementation of
org.eclipse.rap.ui.interactiondesign.ConfigurationAction. This is
an abstract class providing methods for personalization. For example, you can
use this to implement a popup dialog which allows the user to configure
viewaction visibility or the stack's presentation. To apply configuration
changes in your ConfigurableStack you will need to implement the Interface
and register it in the ConfigurationAction.
A ConfigurationAction can contain an icon which can be used i.e. as a button's
icon. The icon is associated with the
This is the icon for the view's menu and can be used to replace the standard
triangle. To access this image use the
getMenuIcon() Method inside
The graphical layout
RAP provides the ability to define graphical layouts where you have control over
the elements such as the position of the workbench components like the toolbar,
menubar or the perspective switcher. The WorkbenchWindowAdvisors
createWindowContents( Shell ) method is one method, but the
result of this technique is a fixed coupling between the look and feel and your
You can now separate the application code and the look and feel by using the
org.eclipse.rap.ui.interactiondesign.IWindowComposer Interface. An
createWindowComposer() which is called within the
WorkbenchWindow. This is a simple replacement for the advisor's method that
results in a loose coupling between application elements.
In order to organize graphical layout information such as images, colors, fonts
and position data, the following registry was created.
The LayoutRegistry is a singleton object which contains all existing layouts
A Layout can be declared by creating an extension for the extension point
And here is the same as it appears in the plugin.xml.
Layout contains the following attributes:
This id can be used to get a Layout object from the LayoutRegistry.
A human readable name for this layout.
Every Layout can have multiple layoutSets:
A layoutSet is a representation of the following class:
object contains the information described above. Every layoutSet has a
maximum of one Layout as a parent and has the following attributes:
This id can be used to get a LayoutSet object from a Layout using the
getLayoutSet( String id ) method.
This should be an implementation of the following interface:
This interface contains one method which is used to declared layout information
for a LayoutSet object. All IlayoutSetInitializers will be called during the
The following is an example use case for a declarative layout.
A button should display its text in a specific font. Instead of defining the
font directly in the source code, you can define a layout and a layoutSet over
the extension described above. Let start by creating two id's.
For the Layout =
For the layoutSet =
To define the font you can call the
LayoutSet.addFont( String key, Font font )
method in your
IlayoutSetInitializer implementation. We use "fontKey" as the key value. Here
is the source code for this font definition:
Button button = new Button( composite, SWT.NONE );
LayoutRegistry registry = LayoutRegistry.getInstance();
registry.setActiveLayout( "org.eclipse.layout" );
Layout layout = registry.getActiveLayout();
LayoutSet set = layout.getLayoutSet( "org.eclipse.layoutSet" );
button.setFont( set.getFont( "fontKey" );
An alternative to accomplish this is theming, but the declarative layout give
you more options such as defining images or position data. Another big advantage
of using the declarative layout is that you can change a layout during runtime.
And, to do this is just a two step process.
Define two layouts with layoutSets. The layoutSets must have the same ids as in
their equivalent and the key values for the information need to be identical.
setActiveLayout( String id ) method within the
LayoutRegistry. This sets the active layout to the one with the given id.
The PresentationFactory will be called automatically and prompt a rebuild of the
Activation by servlet name
Different layouts can be activated from a central point by using the servlet
name. To activate a PresentationFactory and a Layout by a servlet name, you
can use the
org.eclipse.rap.ui.branding extension point.
And here is the same as it appears in the plugin.xml.
As you can see, the presentationFactory is an element of the branding extension
and has the following attributes:
This is the id of the PresentationFactory which should be loaded when the
servlet name defined in the branding has been called.
This optional argument represents the id of the Layout which should be activated
when the servlet name has been called. If no id is defined, the standard workbench
layout should be loaded.
The presentationFactory element can have two different sub elements.
This represents the StackPresentation which is loaded for all parts if nothing
else is defined. You need to specify the id of the StackPresentation if a
different presentation should be loaded.
This element couples a stackPresentation to a specific part. The id attribute
should be the id of the stackPresentation to load. The partId represents the id
of a part which has been defined in a perspective.
Reusable web components
To style the look and feel of a RAP application many web components are also
required. For example, you may want to place the menubar on a header with
rounded corners or place the statusline in a nicely styled footer. You can
accomplish this with SWT Widgets but if you want to reuse these components,
you'll need to use also
ElementBuilder is an abstract class which works hand in hand with the
declarative layout. You can extend it to build your own web components.
This is a two step process.
implement its abstract methods. The most important method is
build(). You should build your component with SWT widgets when
build() is called. Every ElementBuilder is associated to a LayoutSet
id which will get from the LayoutRegsitry during the instantiation of the
ElementBuilder. During the instantiation the builder register itself in the
LayoutRegistry. If a new Layout is activated the
from all registered ElementBuilders will be called. This means that you need to
be sure you dispose your component correctly in this method. If not, switching the
Layout on-the-fly may not work correctly.
The second step is to instantiate an ElementBuilder. As an example, YourBuilder
is instantiated by the following snippet:
Composite parent = new Composite( aShell, SWT.NONE );
ElementBuilder builder = new YourBuilder( parent, "org.eclipse.layoutSet" );
Be sure that your ElementBuilder implementation is initialized with a layoutSet
you've associated with it.
You may recognize the idea behind the ElementBuilder - it is based on the
builder design pattern. This separates the component from your application
code allowing you to reuse the component in different places.
This completes our tour of the interaction design API. For questions please
feel free to visit the
RAP newsgroup. We'd also be glad to hear about your experiences with this
API and to have a look at the great new look and feels you're building for