MainGettingStarted modified by Remo Loetscher

Remo Loetscher — Tue, 20 May 2014 09:13:17 -0000

Getting Started with RCPForms

First step is to install an Eclipse IDE including Java and PDE tooling, e.g. Eclipse for RCP/Plug-in Developers,
see Eclipse IDE Packages; make sure that RCP/Platform is included with source.
For the versions supported see Preconditions?.

Please use the newest rcpforms version which fits your Eclipse Platform Version. In general the main development line should suppport Eclipse 3.3 and newer; there is a backport to Eclipse 3.2 which needs some special versions of databinding.

Creation of a local Folder to install from

If you want to install the SDK, you need SWTBot 1.2 installed first, since this is used by the automated unit tests included in SDK; download it here:
https://sourceforge.net/project/showfiles.php?group_id=188411

Since currently there are problems with the update site zip of rcpforms, download the needed feature zips from here:
http://sourceforge.net/project/showfiles.php?group_id=213050.

To install the RCPForms SDK (which is recommended since it contains examples and tests as good starting point to explore rcpforms),
you need to download the following zip files and unzip them into the given location (or any other base location you like):

unzip net.sf.swtbot-x.x.x.x.zip to c:\rcpforms (if you do not install the SDK, but only net.sf.rcpforms feature, you do not need to install swtbot)
unzip net.sf.rcpforms.sdk.feature-x.x.x.x.zip to c:\rcpforms*eclipse*
if you like to use EMF (ATTENTION: still alpha as of v1.0 !): net.sf.rcpforms.emf.sdk.feature-x.x.x.x.zip to c:\rcpforms*eclipse*, make sure emf is installed already in your eclipse distribution

Now you should have a folder c:\rcpforms which containls only one folder eclipse, which contains a features and a plugins folder containing all features and plugins from the zip files mentioned above.

Looks like a complex, fat framework with loads of features and plugins ?
No, its only a very thin layer above existing eclipse technologies; the runtime of rcpforms is less than 500 KB '''

Its the fine-grained packaging and modular design, which leads to lots of very small plugins; the advantage: you can use the lower layers without needing the other stuff;
just pick what you like. Layering will tell you more about this.

Installation of the Feature

ATTENTION: The Installation process with the Update Manager shown is for Eclipse 3.4; 3.3 and 3.2 versions might differ. Check the Eclipse help file on details of the installation process.

Start Eclipse with a new workspace (or an existing one if you want to add to that one)
Start Update Manager under Help->Software Updates
Add Site…
Archive… select folder created above, e.g. c:\rcpforms

The Features included in rcpforms (and swtbot) are shown, recommended is to select the SDK feature since this comes with sources, examples and Unit Tests.
If you want to use EMF, additionally select the RCPFORMS EMF SDK Feature (if not, leave it away):

Install… and confirm the features to install
Finish
Restart Eclipse

If you installed the SDK, now you should have a Test Menu in your Eclipse main menu, where you can start the example application embedded into different eclipse parts,
like Dialog, Wizard, Editor, Multipage Editor.

Import of Plugins into Workspace (OPTIONAL)

If you develop stuff using a framework, you'd like to peek into the sources.
The easiest way to peek around rcpforms is importing all plugins as source plugins into your workspace,
giving you the ability to browse them easily, maybe patch them (not recommended, better provide patch to us ;-))
and have a look at the examples delivered.

File -> Import, select Plug-ins and Fragments

Make sure to select "Projects with source folders" ! Target platform should be the eclipse installation, where you installed rcpforms.
select all net.sf.rcpforms.* plugins and add them to the right side

Then click finish and the workspace should look like shown in the picture below.

Debug Example Application

If you're looking for the minimal running Forms example, open the SimpleSampleStackform.java from net.sf.rcpforms.simplesample,
and Debug -> As Java Application. This should start the following swt app, already equipped with required field validators:

Note for Eclipse 3.5.1:
If you want to run the Sample under 3.5.1 as standalone you just open the Manifest.mf of the net.sf.rcpforms.examples Plugin switch to the Dependencies tab and add org.eclipse.core.databinding.property" to the required plugins. Otherwise you'll get a java.lang.NoClassDefFoundError?: org/eclipse/core/databinding/property/value/IValueProperty Exception.

This is the code for the form part shown above, all fields are automatically validated and two-way synced with the bean used as data model; compare it to an SWT implementation using eclipse databinding,
to get an idea how much much easier to use the rcpforms api is, leading to much cleaner forms code:

package net.sf.rcpforms.simplesample.example;

import java.util.Date;

import net.sf.rcpforms.bindingvalidation.ValidationManager;
import net.sf.rcpforms.bindingvalidation.forms.RCPFormPart;
import net.sf.rcpforms.modeladapter.converter.AbstractModelValidator;
import net.sf.rcpforms.modeladapter.converter.RequiredValidator;
import net.sf.rcpforms.widgetwrapper.builder.GridBuilder;
import net.sf.rcpforms.widgetwrapper.wrapper.EControlState;
import net.sf.rcpforms.widgetwrapper.wrapper.RCPCombo;
import net.sf.rcpforms.widgetwrapper.wrapper.RCPSection;
import net.sf.rcpforms.widgetwrapper.wrapper.RCPText;

import org.eclipse.core.runtime.IStatus;
import org.eclipse.swt.widgets.Composite;
import org.eclipse.ui.forms.widgets.FormToolkit;
import org.eclipse.ui.forms.widgets.Section;

public class PersonFormPart extends RCPFormPart
{

    /**
     * Class DateFutureValidator is an example for a custom validator
     *
     * @author Remo Loetscher
     */
    public static final class DateFutureValidator extends AbstractModelValidator
    {
        public Object[] getProperties()
        {
            return new String[]{PersonDataModel.P_Birthdate};
        }

        public IStatus validate(Object value)
        {
            PersonDataModel model = (PersonDataModel) value;
            IStatus result = ok();
            if (model.getBirthdate() != null && model.getBirthdate().after(new Date()))
            {
                result = error("Birthdate has to be in the past!");
            }
            return result;
        }
    }

    private RCPSection section;

    private RCPText name;

    private RCPText firstName;

    private RCPText street;

    private RCPText streetNumber;

    private RCPText city;

    private RCPCombo country;

    private RCPText birthdate;

    @Override
    public void bind(ValidationManager bm, Object modelBean)
    {
        bm.bindValue(name, modelBean, PersonDataModel.P_Name);
        bm.bindValue(firstName, modelBean, PersonDataModel.P_FirstName);
        bm.bindValue(street, modelBean, PersonDataModel.P_Street);
        bm.bindValue(streetNumber, modelBean, PersonDataModel.P_StreetNumber);
        bm.bindValue(city, modelBean, PersonDataModel.P_City);
        bm.bindValue(country, modelBean, PersonDataModel.P_Country);
        bm.bindValue(birthdate, modelBean, PersonDataModel.P_Birthdate);

        // add required validator
        bm.addValidator(this, new RequiredValidator(PersonDataModel.P_Name,
                PersonDataModel.P_FirstName, PersonDataModel.P_Birthdate));

        // add date validator
        bm.addValidator(this, new DateFutureValidator());
    }

    @Override
    public void createUI(FormToolkit toolkit, Composite parent)
    {
        // create RCPForm elements
        section = new RCPSection("This title will be invisible", Section.NO_TITLE);
        name = new RCPText("Name: ");
        name.setState(EControlState.MANDATORY, true);
        firstName = new RCPText("Firstname: ");
        firstName.setState(EControlState.MANDATORY, true);
        street = new RCPText("Street/Number: ");
        streetNumber = new RCPText(null);
        city = new RCPText("City: ");
        country = new RCPCombo("Country: ");
        birthdate = new RCPText("Birthdate: ");
        birthdate.setState(EControlState.MANDATORY, true);

        // add elements to container
        GridBuilder formPartBuilder = new GridBuilder(toolkit, parent, 1);
        GridBuilder sectionBuilder = formPartBuilder.addContainer(section, 4);
        // 1st line
        sectionBuilder.addLineGrabAndFill(name, 3);
        // 2nd line
        sectionBuilder.addLine(firstName);
        // 3rd line
        sectionBuilder.add(street);
        sectionBuilder.add(streetNumber);
        sectionBuilder.fillLine();
        // 4th line
        sectionBuilder.addLine(city);
        // 5th line
        sectionBuilder.addLine(country);
        // 6th line
        sectionBuilder.addLine(birthdate, 10);
    }

    @Override
    public void setState(EControlState state, boolean value)
    {
        section.setState(state, value);
    }

}

Advanced Example

There is an example application delivered with RCPForms, which demonstrates nearly all features available,
including complex tables with disabled rows.

You can start this example application; there should be 2 launch configurations already installed in your workspace,
select Run --> Debug Configurations to see the following dialog. If you want to run the example as plain SWT application,
select "RCPForms Example (SWT)". If you want to start an RCP application running on osgi, select "RCPForms Example Application".

Have a look at Example to see how it should look; the links there go directly to the SVN repository trunk; in your workspace you find all relevant sources for the example application in net.sf.rcpforms.examples/src/net/sf/rcpforms/examples/complete/, the Part classes contain all UI code, the Model classes contain the plain JavaBean model.

You might want to experiment with the example by changing things, or go directly to the User Manual to understand the concepts.

Use the Form DSL

There is a domain specific language available to generate Forms from a very compact textual description (what's called declarative UI in e4, with RCPForms you have it much easier, more expressive, readable, printable and perfectly fitted for Eclipse). See [FormGenerator] for Details.

Recent changes to MainGettingStarted