Eclipse RAP Tutorial for Beginners - e4 Workbench Application

1- Introduction

This document is based on:
  • Eclipse 4.5 (MARS)

  • Eclipse RAP e4

Document History:
  • 27-08-2014: Based on Eclipse 4.4 LUNA + RAP 2.3 + Old Model of Workbench
  • 21-07-2015: Update to Eclipse 4.5 MARS + Eclipse RAP e4 (e4 Workbench)

Note:

You can see Eclipse RAP 2.3 (With old model of workbench) tutorial at:

2- The installation requires

2.1- Installing Eclipse

You need the latest version of Eclipse. There currently is Eclipse 4.5 (Codes MARS).
 
In my opinion you to download package: "Eclipse IDE for Java EE Developers". The only different package quantities Plugin, for the purpose of different programming. During the programming process can install the plugin for other purposes.

2.2- Installing WindowBuilder

Install WindowBuilder plugin, there is a plugin that allows you to design SWT GUI applications using drag and drop convenience.
See installation instructions at:

2.3- Installing e4 Tools Developer Resources

You can see installation instructions at:

2.4- Install RAP e4 Tooling into Eclipse

You can see installation instructions at:

3- Create new Java Workspace

To programme  RAP e4 application you should create a new Java Workspace:
  • File/Switch Workspace/Other..
Enter:
  • F:\ECLIPSE_TUTORIAL\RAP_E4

4- Install RAP Target

For RAP e4 application programming, you need to install the environment (RAP Target Platform). Include at least two libraries:
  1. RAP Target Components
  2. RAP e4 Target Components
Create RAPTarget project, and create Target define file. You can see the instructions at:
Results:

5- Create RAP e4 Project

In this document, I will guide you to build an RAP e4 application from the beginning (Do not follow the available template), so I'll create a blank Eclipse RAP e4 application.
In Eclipse select: File/New/Other...
Enter:
  • Project Name: RAPe4Tutorial
  1. Check selected on (1)
  2. On the (2) select "No" to create Eclipse RAP Project (Running on Web), otherwise it will create RCP Project (Running on the Desktop).
Select "RAP e4 application"
Enter:
  • Application window title: Hello RAP E4
  • Java package name: org.o7planning.tutorial.rape4
Project was created:

Run application:

Right click RAPe4Tutorial project and select Run As/Eclipse Application
Eclipse browser can not display the RAP e4 application.
You need to copy the path to run on Firefox or Chrome:

6- Run Configurations

You can configure the port and the default browser to run RAP e4 application:
Right-click the RAPe4Tutorial project and select Run As/Run Configurations...
Using port 7777 and the default browser of the operating system:
Click Apply and run the application:
Results:

7- Structure of Empty Eclipse e4 RAP application

Empty  Eclipse RAP e4 applications was created by Eclipse, see its structure. Open  Application.e4xmi file:
Change the title of the application into "Eclipse E4 RAP Application" as shown below.
And rerun application:

8- Configuring additional Bundle

To build RAP e4 application with multiple functions, you need to declare use some other Bundles:
Open MANIFEST.MF file
Add the Bundles:
  • org.eclipse.e4.ui.model.workbench
  • org.eclipse.e4.ui.services
  • org.eclipse.e4.ui.workbench
Right-click the Project and select Run As/Run Configurations:

9- Handler and Command

RAP Framework built a lot of Command, for example 3 commands with the following ID:
  1. org.eclipse.ui.file.exit
    • Close the workbench
  2. org.eclipse.ui.file.save
    • Save the active editor.
  3. org.eclipse.ui.help.aboutAction
    • Displays the About dialog.
Create a Command named  quiteCommand , called to exit the application command which was built by RAP Framework.
Similarly we create 2 other Commands:
Save the active editor (or part).
  • ID: org.eclipse.ui.file.save
  • Name: saveCommand
AboutCommand:
  • ID: org.eclipse.ui.help.aboutAction
  • Name: aboutCommand
Handler is the classes handling for the commands of Menu or Toolbar. When you click on MenuItem or ToolItem, it means that the call to execute a command,Handler will be executed before the Command is executed, you can cancel (cancel) the command is executed in Handler.

Handler is the classes that when executed, it will execute the task is written in method annotated by @Execute.

I will create 3 Handler classes:
  • AboutHandler.java
package org.o7planning.tutorial.rape4.handler;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Shell;

public class AboutHandler {
   
   @Execute
   public void execute(Shell shell) {
       MessageDialog.openInformation(shell, "About", "Eclipse e4 RAP Application");
   }
}
  • QuitHandler.java
package org.o7planning.tutorial.rcp.handler;

import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.workbench.IWorkbench;
import org.eclipse.jface.dialogs.MessageDialog;
import org.eclipse.swt.widgets.Shell;


public class QuitHandler {
  @Execute
  public void execute(IWorkbench workbench, Shell shell){
      if (MessageDialog.openConfirm(shell, "Confirmation",
              "Do you want to exit?")) {
          workbench.close();
      }
  }
}
  • SaveHandler.java
package org.o7planning.tutorial.rcp.handler;

import org.eclipse.e4.core.di.annotations.CanExecute;
import org.eclipse.e4.core.di.annotations.Execute;
import org.eclipse.e4.ui.workbench.modeling.EPartService;

public class SaveHandler {

  @CanExecute
  public boolean canExecute(EPartService partService) {
      if (partService != null) {
          return !partService.getDirtyParts().isEmpty();
      }
      return false;
  }

  @Execute
  public void execute(EPartService partService) {
      partService.saveAll(false);
  }
}

Declaring  Handler classes with applications.

Declaring a Handler with Application, you must declare the ID, Handler class and Command.

For example, the user closes the application by clicking the menuItem Exit, the MenuItem associated with quiteCommand, QuiteHandler is class handling for this command (as declared above), class QuiteHandler will ask users really want to close the application or not,  if yes, quiteCommand Command will be executed.
Enter:
  • ID: handler.quiteCommand
Similarly declare other Handler.
  • handler.aboutCommand
  • handler.saveCommand

10- Create Menus

Add some icons to the project, used as a icons for menuItem and toolItem.
  1. sample.png
  2. save_edit.png
Create Main Menu:
Enter the ID of Main Menu, It must be named:
  • menu:org.eclipse.ui.main.menu
Create 3 submenus:
  • File, Function, Help
Create submenus of File menu.
  • Save
  • Exit
Rerun your application:

11- Create Toolbar

Create Main Toolbar, with ID:
  • ID: toolbar:org.eclipse.ui.main.toolbar
Add 2 Toolitem: open & save
Rerun your application:

12- Part

  • SamplePart.java
/*******************************************************************************
* Copyright (c) 2010 - 2013 IBM Corporation and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
*     IBM Corporation - initial API and implementation
*     Lars Vogel <lars.Vogel@gmail.com> - Bug 419770
*******************************************************************************/
package org.o7planning.tutorial.rape4.part;

import javax.annotation.PostConstruct;
import javax.inject.Inject;

import org.eclipse.e4.ui.di.Focus;
import org.eclipse.e4.ui.di.Persist;
import org.eclipse.e4.ui.model.application.ui.MDirtyable;
import org.eclipse.jface.viewers.TableViewer;
import org.eclipse.swt.SWT;
import org.eclipse.swt.events.ModifyEvent;
import org.eclipse.swt.events.ModifyListener;
import org.eclipse.swt.layout.GridData;
import org.eclipse.swt.layout.GridLayout;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.swt.widgets.Text;

public class SamplePart {

   private Text txtInput;
   private TableViewer tableViewer;

   @Inject
   private MDirtyable dirty;

   @PostConstruct
   public void createComposite(Composite parent) {
       parent.setLayout(new GridLayout(1, false));

       txtInput = new Text(parent, SWT.BORDER);
       txtInput.setMessage("Enter text to mark part as dirty");
       txtInput.addModifyListener(new ModifyListener() {
           @Override
           public void modifyText(ModifyEvent e) {
               dirty.setDirty(true);
           }
       });
       txtInput.setLayoutData(new GridData(GridData.FILL_HORIZONTAL));

       tableViewer = new TableViewer(parent);

       tableViewer.add("Sample item 1");
       tableViewer.add("Sample item 2");
       tableViewer.add("Sample item 3");
       tableViewer.add("Sample item 4");
       tableViewer.add("Sample item 5");
       tableViewer.getTable().setLayoutData(new GridData(GridData.FILL_BOTH));
   }

   @Focus
   public void setFocus() {
       tableViewer.getTable().setFocus();
   }

   @Persist
   public void save() {
       dirty.setDirty(false);
   }
}
Add new PerspectiveStack. This is a stack, it can contain the perspective.
Add new Perspective:
Rerun Application:
The change in the Part, may do SAVE button lights up.