Jump to: navigation, search

Difference between revisions of "JFace"

m (More information)
(adding a link into the JFace section in the Platform Plug-In Developer's Guide in Eclipse help - with a footnote about this documentation being available in Eclipse online help)
Line 7: Line 7:
==More information==
==More information==
* [http://help.eclipse.org/helios/index.jsp?topic=/org.eclipse.platform.doc.isv/guide/swt.htm The JFace UI framework] section, within the  [http://help.eclipse.org/helios/nav/2 Eclipse Platform Plug-In Developer's Guide] - also available from Eclipse online help, in Eclipse platforms with the plug-in development documentation installed
* [[The Official Eclipse FAQs#JFace| JFace Section]] of [[The Official Eclipse FAQs]]  
* [http://dev.eclipse.org/viewcvs/index.cgi/%7Echeckout%7E/platform-ui-home/main.html Platform UI home page]

Revision as of 10:01, 6 August 2010


More information on JFace is available in the JFace section of The Official Eclipse FAQs.


More information

Using JFace outside the Eclipse platform


For more details, see Bug 49497.


Setting Up an Eclipse Project to use SWT and JFace


  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 its 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.

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, 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.common_<version info>.jar
  • org.eclipse.jface_<version info>.jar
  • org.eclipse.osgi_<version info>.jar
  • org.eclipse.ui.workbench_<version info>.jar



  2. Select the org.eclipse.jface plug-in from the list.
    Jface dependencies2.png
    Jface dependencies.png

Create the Eclipse SWT/JFace Project


    Swt web page.png
    Import wizard1.png
    Import wizard2.png
  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.
    Build path before.png
  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.
    New variable classpath entry.png
    Classpath variables.png
  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”.
    New variable entry.png
  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.
    Variable extension.png
  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.)
    Core commands.png
  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.common_<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.
    JFace jars added.png
  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. Note that the JFace source code comes as part of the Eclipse Platform Plug-in Developer Resources feature, which is included in the Eclipse for RCP/Plug-in Developers download. If you don't have this Eclipse package, you can download the Eclipse Platform Plug-in Developer Resources feature from the Eclipse Project Updates update site, as shown below.
    Updates developer resources.png
  19. To attach the JFace source code, expand the JFace JAR file and select the Source Attachment, as shown below.
    Jface source attachment1.png
  20. 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.
    Jface source attachment1a.png
  22. 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.
    Jface source attachment2.png
  23. 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.
    Jface source attachment3.png
  24. 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.
    Order and export.png

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.
    Required project selection.png
  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.
    Myproject build path.png

Test Your org.eclipse.swt Project

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. In your Java project, create a new package called jface.test.
  2. Create a new class called JFaceTest, as shown below.
    New java class.png
  3. 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, as shown below.
    Superclass selection.png
  4. Select ApplicationWindow and press Finish to create the class.
  5. 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 start developing stand-alone SWT and JFace applications.

Deploying a Java Program That Uses SWT and JFace

Once you have developed a stand-alone Java program that uses SWT and JFace, you will want to be able to deploy it to other computers. This section includes detailed instructions for doing this.

Deploying a SWT / JFace application is similar to deploying any Java application that uses external JAR libraries, with one important difference. Starting with Eclipse version 3.3, the SWT JAR file (e.g., swt.jar in the org.eclipse.swt project referenced above), contains platform-specific executable files (e.g., *.DLL files for Windows, *.so files for Linux) as well as Java classes. For this reason, the SWT JAR file must be matched to the target runtime platform. If you want to target more than one platform (e.g., Windows and Linux), you will need a separate SWT JAR file for each target platform.

Step by Step Instructions

  1. Create a runtime folder for the desired runtime target on your system (e.g., c:\jface\runtime-linux). Note that the target platform does not need to be the same as your development platform.
  2. Find the correct SWT JAR file for the desired target platform. You can download the desired ZIP file from the SWT Project Page. For example, for Eclipse 3.3 and a target platform of Linux, download the file swt- Expand this ZIP file and copy the swt.jar file to the runtime folder.
  3. Copy the JAR files that JFace needs to the runtime folder. They are found in the Eclipse plugins subfolder under your Eclipse installation. For Eclipse version 3.3, these files are as follows:
    • org.eclipse.core.commands_<version info>.jar
    • org.eclipse.equinox.common_<version info>.jar
    • org.eclipse.jface_<version info>.jar
    • org.eclipse.osgi_<version info>.jar
    • org.eclipse.ui.workbench_<version info>.jar
  4. If desired, and to save some typing, rename the JAR files to remove the detailed version information. For example, rename the org.eclipse.jface JAR file to "org.eclipse.jface.jar" or "org.eclipse.jface_3.3.jar".
  5. Create a manifest file for your application using the Eclipse text editor (e.g., myapplication-manifest.txt). The text of the manifest should be as follows:
    Manifest-Version: 1.0
    Class-Path: swt.jar 
    Main-Class: mypackage.MyClassWithMainMethod
    (blank line at end of file)
  6. Make sure the JAR file names in the manifest file exactly match the names in your runtime folder. Also, make sure the manifest file ends with a blank line and that there are at least one space before the continuation lines for Class-Path:. Finally, put the name of your package and class that contains the main() method for the Main-Class.
  7. In Eclipse, select File/Export/Java/Jar file and press Next.
  8. On the JAR File Specification dialog, select the source files for the classes you want in the application. In the export destination, browse to the runtime folder and enter in the desired name of the JAR file (e.g., myapplication.jar or myapplication_linux.jar). Press Next.
  9. On the JAR Packaging Options dialog, make sure the "Export class files with compile warnings" box is checked. Otherwise, if your source files have any compile warnings, they will not be included in the JAR file. Press Next.
  10. In the JAR Export dialog, select the option "Use existing manifest from workspace". Browse to the manifest file you created above. Press Finish.
  11. If the JAR file already exists, you will be asked to overwrite it. Select Yes. If your project had any compile warnings, a message will display. If so, press OK.
  12. At this point, the JAR file for your application has been created in the runtime directory. In your operating system's file explorer, browse to the runtime directory and run your JAR file. For example, in Windows, you can just double-click on it in the Windows File Explorer or, from the "cmd" prompt, you can enter the command: java -jar myapplication.jar. The application should run and the main application window should display.

Troubleshooting Errors

A common error message when trying to run a stand-alone application is: "Could not find the main class. Program will exit.", This error can be caused by any of the following problems:

  1. One or more of the required JFace JAR file names is missing or misspelled in the mainfest file.
  2. One or more of the of the required JFace JAR files is missing in the runtime folder.
  3. The Main-Class: is incorrect in the manifest file.