Real world migration of 3.x RCP applications to 4 · Real world migration of 3.x RCP applications to 4.x Lars Vogel (vogella GmbH) / Daniel Rolka (IBM)

Real world migration of 3.x RCP applications to 4.x

Lars Vogel (vogella GmbH) / Daniel Rolka (IBM)

About us

Lars Vogel

Eclipse platform developer, Co-founder of vogella GmbH which provides Eclipse RCP

development and training supportContact: [email protected]

Daniel Rolka

Eclipse Platform-UI and E4 tools committer as well as Platform-UI co-lead, senior software

engineer at IBM

Why migrate to Eclipse 4?

● Simple and consistent design of the API

● Usage of dependency injection and a dynamic application model

● Flexible styling based on CSS and the renderer framework

● No new development for 3.x API

● Allows to create clear design of application.

● The source code is better unit testable.

As a result there are less maintenance costs and new functionality requested by the customers can be introduced faster

Because….

In short: Because Eclipse RCP is better.

So how do you migrate?

1.) Change target platform to Eclipse 4.x and solve internal API conflicts

2.) Create new appearance of your application with CSS in order to show that the major change of it is coming. How to use CSS in your application?

3.) Migrate parts of your application (e4view, toolbar, menu)

4.) Migrate full application and replace the stuff which is not yet available

Typical migration steps

Now you can go for an easy win






● Definition of the default CSS style sheet for application

<extension id="product" point="org.eclipse.core.runtime.products"> <product name="RCP4.x" application="org.eclipse.e4.ui.workbench.swt.E4Application"> <property name="applicationCSS" value="platform:/plugin/RCP4.x/css/default.css"/> </product> </extension>

How to use CSS in your application?

● Definition of the CSS themes for application<extension point="org.eclipse.e4.ui.css.swt.theme"> <theme basestylesheeturi="css/e4_classic_win7.css" id="org.eclipse.e4.ui.css.theme.e4_classic" label="Windows Vista Classic" os="win32" os_version="6.0"/> <theme basestylesheeturi="css/e4_default_win7.css" id="org.eclipse.e4.ui.css.theme.e4_default" label="Windows Vista" os="win32" os_version="6.0"/> </extension>

● Selecting default theme for application by the plugin.xml file<extension id="product" point="org.eclipse.core.runtime.products"> <product name="RCP4.x" application="org.eclipse.e4.ui.workbench.swt.E4Application"> <property name="cssTheme" value="org.eclipse.e4.ui.css.theme.e4_default"/> </product> </extension>


● Switching CSS theme in the runtime

@Inject org.eclipse.e4.ui.css.swt.theme.IThemeEngine themeEngine;

themeEngine.setTheme(“org.eclipse.e4.ui.css.theme.e4_classic”, true);


● CSS style sheet syntax

@import url("platform:/plugin/org.eclipse.ui.themes/css/dark/e4-dark_basestyle.css");

CTabItem.highlighted {

font-weight: bold;

}

.MPartStack, .MPart {

font-family: 'Arial';

}

.MPartStack {

swt-tab-renderer: url('bundleclass://bundle/org.eclipse.e4.ui.workbench.renderers.swt.CTabRendering');

swt-selected-tab-fill: #FFFFFF #000000 100% 100%;

padding: 0px 2px 2px;

color: black;

}

.MPartStack.active.noFocus > CTabItem:selected {

color: COLOR-GRAY;

}

#PerspectiveSwitcher { eclipse-perspective-keyline-color: rgb(170, 176, 191) rgb(170, 176, 191);

}


● CSS elements = SWT widgetsLabel, Button, Ctab, …

● CSS ids of elementsWidget widget;

widget.setData(org.eclipse.e4.ui.css.swt.CSSSWTConstants.CSS_ID_KEY, “cssID”);

● Model elements and tags are considered as CSS classes Mapplication, Mpart, MpartStack, .active, .Draggable, ...

● Custom CSS classesWidget widget;

widget.setData(org.eclipse.e4.ui.css.swt.CSSSWTConstants.CSS_CLASS_NAME_KEY, “cssClassName”);


● Modifying CSS class and calling the re-styling of the GUI in the runtime

@Injectorg.eclipse.e4.ui.services.IStylingEngine stylingEngine;Widget widget;

stylingEngine.setId(widget, “cssIdForWidget”);stylingEngine.setClassname(widget, “someCSSClass”);stylingEngine.style(widget);


● Eclipse 3.x theme API

● Initial stage of migration - CSS bridge

● Final stage of migration - custom CSS property handlers

Migration of 3.x theme to CSS



● Eclipse 3.x theme APIhttp://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP

<extension point="org.eclipse.ui.themes">

<themeElementCategory id="org.eclipse.examples.widgetsample.theme" label="Chart widget sample theme"/>

<colorDefinition categoryId="org.eclipse.examples.widgetsample.theme"

id="org.eclipse.examples.widgetsample.theme.fontColor"

label="Font color" value="0, 0, 0"/>

<colorDefinition categoryId="org.eclipse.examples.widgetsample.theme"

id="org.eclipse.examples.widgetsample.theme.chartGradBgColor"

label="Chart gradient start color" value="255, 0, 0"/>

<colorDefinition id="org.eclipse.examples.widgetsample.theme.chartGradEndColor"

label="Chart gradient end color" value="0, 255, 0"/>

</extension>


http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP




Chart chart = new Chart(parent, SWT.NONE);

chart.addTrend(new Chart.Trend("Trend one", 20));

chart.addTrend(new Chart.Trend("Trend two", 40));

chart.addTrend(new Chart.Trend("Trend three", 10));

chart.addTrend(new Chart.Trend("Trend four", 5));

chart.addTrend(new Chart.Trend("Trend five", 15));

ITheme currentTheme = PlatformUI.getWorkbench().getThemeManager().getCurrentTheme();

ColorRegistry colorRegistry = currentTheme.getColorRegistry();

RGB fontColor = colorRegistry.getRGB("org.eclipse.examples.widgetsample.theme.fontColor");

chart.setFontColor(fontColor);

RGB gradBgColor = colorRegistry.getRGB("org.eclipse.examples.widgetsample.theme.chartGradBgColor");

RGB gradEndColor = colorRegistry.getRGB("org.eclipse.examples.widgetsample.theme.chartGradEndColor");

chart.setChartGradient(new RGB[] {gradBgColor, gradEndColor});


● Initial stage of migration - CSS bridgehttp://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP_firstStage

@import url("platform:/plugin/org.eclipse.ui.themes/css/e4_default_winxp_olv_fixed.css");

ColorDefinition#org-eclipse-examples-widgetsample-theme-fontColor { color: #635c5c;

}

ColorDefinition#org-eclipse-examples-widgetsample-theme-chartGradBgColor { color: #ff523b;

}

ColorDefinition#org-eclipse-examples-widgetsample-theme-chartGradEndColor { color: #ffd045;

}


http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP_firstStage



● Final stage of migration - custom CSS property handlershttp://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP_lastStage

<extension point="org.eclipse.e4.ui.css.core.elementProvider">

<provider class="org.eclipse.examples.widgetsample.rcp.css.ChartElementProvider">

<widget class="org.eclipse.ui.examples.chart.Chart"/>

</provider>

</extension>

<extension point="org.eclipse.e4.ui.css.core.propertyHandler">

<handler adapter="org.eclipse.examples.widgetsample.rcp.css.ChartElement"

composite="false" handler="org.eclipse.examples.widgetsample.rcp.css.ChartPropertiesHandler">

<property-name name="color"/>

<property-name name="chart-gradient"/>

</handler>

</extension>


http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.demo.migration.themeapitocss/WidgetSampleRCP_lastStage




public class ChartElement extends org.eclipse.e4.ui.css.swt.dom.WidgetElement {

public ChartElement(Widget widget, CSSEngine engine) {

super(widget, engine);

}

}

public class ChartElementProvider implements org.eclipse.e4.ui.css.core.dom.IElementProvider {

@Override

public Element getElement(Object element, CSSEngine engine) {

if (element instanceof Chart) {

return new ChartElement((Chart) element, engine);

}

return null; }

}



public class ChartPropertiesHandler implements org.eclipse.e4.ui.css.core.dom.properties.ICSSPropertyHandler {

@Override

public boolean applyCSSProperty(Object element, String property, CSSValue value, String pseudo,

CSSEngine engine) throws Exception {

if (element instanceof ChartElement) {

Chart chart = (Chart) ((ChartElement) element).getNativeWidget();

if ("color".equals(property) && value.getCssValueType() == CSSValue.CSS_PRIMITIVE_VALUE) {

Color color = (Color) engine.convert(value, Color.class, chart.getDisplay());

chart.setFontColor(color.getRGB());

return true; }

if ("chart-gradient".equals(property) && value.getCssValueType() == CSSValue.CSS_VALUE_LIST) {

Gradient grad = (Gradient) engine.convert(value, Gradient.class, chart.getDisplay());

if (grad != null && grad.getRGBs().size() == 2) {

chart.setChartGradient((RGB[]) grad.getRGBs().toArray(new RGB[2]));

return true; }

}

...



public void createPartControl(Composite parent) {

parent.setLayout(new FillLayout());

Chart chart = new Chart(parent, SWT.NONE);

chart.addTrend(new Chart.Trend("Trend one", 20));

chart.addTrend(new Chart.Trend("Trend two", 40));

chart.addTrend(new Chart.Trend("Trend three", 10));

chart.addTrend(new Chart.Trend("Trend four", 5));

chart.addTrend(new Chart.Trend("Trend five", 15));

IStylingEngine stylingEngine = getStylingEngine();

if (stylingEngine != null) { stylingEngine.style(chart);

}

}

...



@import url("platform:/plugin/org.eclipse.ui.themes/css/e4_default_win7.css");

Chart {

color: #4b6476;

chart-gradient: #208800 #feffc0;

}








Partial migration

Eclipse 3.x view registration

Eclipse 3.x view

Eclipse 4.x part

Eclipse 3.x view registration with the pojo

Toolbar, menus, handlers

Super easy use

Menu contributions I

Menu contribution II

Menu contribution III

Done!

Menus, toolbars, views are migrated






Overview of typical problems during customer migrations

● Possible but harder (3.x and 4.x mixed mode)

● Alternatively you have to re-program it or migrate it

● First Workbench view extracted from the org.eclipse.ui.workbench bundle is E4 Progress one

○ Still in beta phase and it is not shipped with Eclipse SDK package

○ Available by the following update site - https://hudson.eclipse.org/platform/job/eclipse4-progress-view/lastSuccessfulBuild/artifact/releng/org.eclipse.e4.ui.progress.update/target/repository/

○ Sample plugin with use cases of the view can be found - http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.ui.examples.job

Reuse of Eclipse IDE views

https://hudson.eclipse.org/platform/job/eclipse4-progress-view/lastSuccessfulBuild/artifact/releng/org.eclipse.e4.ui.progress.update/target/repository/




http://git.eclipse.org/c/platform/eclipse.platform.ui.git/tree/examples/org.eclipse.e4.ui.examples.job




● Custom property dialog for managing of properties used by the applicationSample of such dialog - http://www.eclipse.org/forums/index.php/t/246345/

● Exposure properties via CSS and putting accepted value ranges in the comments

IEclipsePreferences#org-eclipse-ui-workbench {

/* All values below are in RGB format */

preferences:

'ACTIVE_HYPERLINK_COLOR=138,201,242'

'CONFLICTING_COLOR=240,15,66'

'CONTENT_ASSIST_BACKGROUND_COLOR=52,57,61'

'CONTENT_ASSIST_FOREGROUND_COLOR=238,238,238'

'ERROR_COLOR=247,68,117'

'HYPERLINK_COLOR=111,197,238'

'INCOMING_COLOR=31,179,235'

'OUTGOING_COLOR=238,238,238'

'RESOLVED_COLOR=108,210,17'

}

Missing preference page support

http://www.eclipse.org/forums/index.php/t/246345/

Migrate it yourself (and contribute it back to platform or wait for platform to do it for you)

Can be a one-liner for certain dialogs

Missing dialogs, like FilteredDialog

https://bugs.eclipse.org/bugs/show_bug.cgi?id=440366

Dependency to other Eclipse frameworks

Contact the team around this framework

For example Xtext plans better Eclipse 4 support in their next release, see https://bugs.eclipse.org/bugs/show_bug.cgi?id=401309



Easy, reuse the existing help system and open it in

To set the help ID, register your custom implementation of IHelpService (EHelpService in Mars) in the IEclipseContext wrapping IWorkbenchHelp and allow to set the help ID via this service.

For example implementation and for Eclipse Mars see Bug 445600.


Using the Eclipse help system



A significant part of every RCP application can already be migrated to the new programming model (partial migration)

If little IDE functionality (IDE views) is used in the RCP application a full migration is also relatively fast

Summary

Additional information

http://www.vogella.com/tutorials/Eclipse4MigrationGuide/article.html (Update to 4.4 pending)

vogella GmbH offers migration workshops and migration support: [email protected]

http://www.vogella.com/training/eclipse/eclipsercpmigration.html

Professional support

http://www.vogella.com/tutorials/Eclipse4MigrationGuide/article.html




Documents

Real world migration of 3.x RCP applications to 4 · Real world migration of 3.x RCP applications to 4.x Lars Vogel (vogella GmbH) / Daniel Rolka (IBM)