Difference between revisions of "JFace"

Revision as of 09:57, 25 March 2008

Template:Platform UI JFace is a UI toolkit with classes for handling many common UI programming tasks. JFace is window-system-independent in both its API and implementation, and is designed to work with SWT without hiding it. JFace includes the usual UI toolkit components of image and font registries, text, dialog, preference and wizard frameworks, and progress reporting for long running operations. Two of its more interesting features are actions and viewers. The action mechanism allows user commands to be defined independently from their exact whereabouts in the UI. Viewers are model based adapters for certain SWT widgets, simplifying the presentation of application data structured as lists, tables or trees.

New in Eclipse 3.2 is the JFace data binding framework. Data binding allows linking UI elements and models so that users can edit or view the data in the model. The framework makes it easy to connect data sources to widgets such as text fields, combos, tables and trees, for viewing and editing. Using it relieves developers from writing and registering listeners with widgets and model objects.

More information

• Platform UI home page
• Plug-in Developer's Guide: JFace
• Workbench and JFace Articles
• JFace code snippets

Using JFace outside the Eclipse platform

JFace can be used in standalone SWT+JFace apps, without requiring the Eclipse Runtime or other parts of the Eclipse Platform. This was made easier to do in 3.2, with the only prerequisites for JFace being reduced to SWT, the new org.eclipse.equinox.common plug-in, and org.eclipse.core.commands plug-in.

For more details, see Bug 49497.

In 3.3 an optional dependency on the org.osgi.framework package was added which is defined in the org.eclipse.osgi. If this plug-in is absent JFace will continue to function but without the benefit of internationalization support for it's images.

Setting Up an Eclipse Project to use SWT and JFace

This section contains detailed instructions for creating an Eclipse project for developing a stand-alone Java program that uses SWT and JFace. This will be broken down into three steps, as follows:

1. Identify the required external JAR files for JFace.
2. Create an Eclipse project (called org.eclipse.swt) that will have all of the required SWT and JFace JAR files on it's build path and configure the Order and Export tab of the Build Path to export these files. This project will supply the required JAR files to any other Eclipse project that needs them.
3. On any new Java projects that need to use SWT or JFace, simply add the org.eclipse.swt project as a required project on the Projects tab of the Build Path.

Detailed instructions for each of these steps are outlined below.

Identify the Required External JAR Files for SWT and JFace

A JFace project requires the SWT classes, JFace classes, and other Eclipse classes that JFace is dependent on. The SWT classes will be provided in the file we download from the SWT Project Website. The JFace file, and the files the JFace is dependent upon, need to be added to the project manually.

The first step is to identify the required JAR files for JFace. The primary file is called org.eclipse.jface, followed by specific version information. In addition, this file requires classes from other Eclipse JAR files. For Eclipse version 3.3.1.1, the required JAR files for JFace are as follows (where <version info> is the specific version information):

• org.eclipse.core.commands_<version info>.jar
• org.eclipse.equinox.commands_<version info>.jar
• org.eclipse.jface_<version info>.jar
• org.eclipse.osgi_<version info>.jar
• org.eclipse.ui.workbench_<version info>.jar

The file org.eclipse.ui.workbench_<version info>.jar is not required to run the standard JFace classes. However, since it adds a number of very useful Dialogs (such as ListDialog, ListSelectionDialog, and others), it is included here as well.

You can find the JFace dependencies for any Eclipse version if you have the Plug-in Development Environment, which includes the Plug-ins and Plug-in Dependencies views. To do this:

1. Select Window/Show View/PDE/Plug-ins. (Note, if you don't have a PDE view folder, it means you don't have the Plug-in Developer Environment plug-in in your Eclipse installation.)
2. Select the org.eclipse.jface plug-in from the list.
3. Right-click and select Open Dependencies. This will open the Plug-in Dependencies view. An example of this view for Eclipse version 3.3.1.1 is shown below.
   
4. Press the Set Flat Layout button to see a simple flat list of the required plug-ins, as shown below.
   
5. Each plug-in on the list corresponds to a JAR file in the plugins directory for your Eclipse installation. If the list for your Eclipse version is different than the list above, make a note of it and modify the remaining instructions accordingly. At this point, we have the list of JAR files that we need.

Create the Eclipse SWT/JFace Project

In this step, we will create one project that will point to all of the JAR files needed for SWT and JFace development. Here are the steps:

1. Download the SWT stable release for your Eclipse version and your operating system from Eclipse SWT Project Page. For example, for Eclipse version 3.3 and Windows, select the Windows link under Releases / Stable, as shown in the screenshot below.
   
2. This will download a zip file that contains our org.eclipes.swt project. (For example, for Eclipse 3.3 and Windows, the file is called swt-3.3.1.1-win32-win32-x86.zip.) Do not unzip this file. Just download it and note the directory where you saved it.
3. Inside Eclipse, select Import / Existing Projects into Workspace, as shown below.
   
4. Press Next and select the option Select archive file. Browse to the zip file you just downloaded. A project called org.eclipse.swt will display in the Projects list. Make sure it is checked, as shown below, and press Finish.
   
5. Eclipse will create the project org.eclipse.swt in your workspace. This project already has the required SWT JAR file, including source code for the SWT classes. This is all you need to develop SWT applications. But for JFace applications, you need to continue with the remaining steps.
6. Make sure the org.eclipse.swt project is highlighted and select Project / Properties / Java Build Path and select the Libraries tab.
   
7. Next, we'll create a new Variable called ECLIPSE_HOME that points to the directory where Eclipse is installed. This will make it easier to keep this project updated as new Eclipse versions are installed.
8. Press the Add Variable... button to display the New Variable Classpath Entry dialog.
   
9. Press the Configure Variables button to display the Classpath Variables dialog.
   
10. Press New to display the New Variable Entry dialog. Enter ECLIPSE_HOME in the Name field. For the Path field, press Folder and browse to the top-level directory where Eclipse is installed. This is the directory that contains the Eclipse executable file (e.g., "eclipse.exe" on Windows) and has subdirectories including "configuration", "features", and "plugins". In the example below, Eclipse is installed in “c:\eclipse”.
    
11. Press OK. Now the ECLIPSE_HOME variable will display in the Classpath Variables list. Press OK again to return to the New Variable Classpath Entry. Press Cancel to return to the Libraries tab of the Java Build Path dialog.
12. Now, we're ready to add our JFace JAR files. We'll use the ECLIPSE_HOME classpath variable we just created. That way, if the location of our Eclipse installation changes, we can just change the ECLIPSE_HOME variable to point to the new location.
13. Press the Add Variable button to again display the New Variable Classpath Entry dialog. Make sure ECLIPSE_HOME is selected and press the Extend... button to display the Variable Extension dialog, shown below.
    
14. This will display the subdirectories of the ECLIPSE_HOME directory. The JAR files we need are in the plugins directory.
15. Expand the plugins directory and browse down to the org.eclipse.core.commands and select it as shown below. (Note that the JAR file version numbers may be different.)
    
16. You can select multiple JAR files from this list by holding down the Ctrl key while clicking. Scroll down the list and select the remaining JAR files. The complete list for Eclipse 3.3 is shown below.
    1. org.eclipse.core.commands_<version info>.jar
    2. org.eclipse.equinox.commands_<version info>.jar
    3. org.eclipse.jface_<version info>.jar
    4. org.eclipse.osgi_<version info>.jar
    5. org.eclipse.ui.workbench_<version info>.jar
17. If there are any other JAR files that displayed for your Eclipse version when you looked at the JFace dependencies above, select them here as well. As mentioned earlier, org.eclipse.ui.workbench is not actually part of JFace but is included here because it supplies some useful dialog classes. When you have selected all of the required files, press OK. The Libraries tab should now show all of the JAR files, similar to the screenshot below.
    
18. The source code for the SWT classes was added automatically when the org.eclipse.swt project was imported. If you like, you can add the source code to the JFace JAR file. Expand the JFace JAR file and select the Source Attachment, as shown below.
    
19. Press Edit to display the Source Attachment Configuration dialog. Press the Variable button, select the ECLIPSE_HOME variable, and press OK to display the screen below.
    
20. Now press the Extension... button. This will open the Variable Extension Selection dialog. Again, expand the plugins directory. Find the directory called org.eclipse.rcp.source_<version infomation>. Note that this is a directory, not a JAR file.
21. Expand this directory, expand the src subdirectory, scroll down to the directory called org.eclipse.jface_<version information>. Expand this, and select the file called src.zip, as shown below.
    
22. Press OK twice to return to the Libraries tab. At this point, you have attached the JFace source code and the screen should look like the one below.
    
23. Finally, select the Order and Export tab and check the check boxes next to each of the ECLIPSE_HOME JAR files so that the screen appears as shown below.
    
24. Press OK. At this point, the org.eclipse.swt project is set up and will supply all of the required libraries for a SWT and JFace project.

Add the org.eclipse.swt Project to Your Java Project

Once the steps above are complete, it is very easy to add the SWT and JFace libraries to any Java project.

1. Select the project that will be used to develop SWT and JFace programs (for example, "MyProject) and select Project / Properties / Java Build Path.
2. Select the Projects tab. Press Add. The org.eclipse.swt project will display in the Select projects to add: list. Select this project by checking the box. The screen should display as shown below.
   
3. Press OK to return to the Projects tab of the Java Build Path dialog. The screen should show the org.eclipse.swt project as shown below.
   

At this point, your Java project should have everything needed to create a stand-alone SWT or JFace application. You can test this with the following steps.

1. Create a new package called jface.test.
2. Create a new class called JFaceTest. In the New Java Class dialog, for the Superclass press Browse and enter ApplicationWindow. The class ApplicationWindow, in the org.eclipse.jface.window package, should display as an option.
3. Press Finish to create the class.
4. In the Java editor, click on the word ApplicationWindow and press F3. This should open the Java source code for the ApplicationWindow.class.

At this point, you are ready to create a stand-along Java program that uses any of the SWT or JFace classes.