Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "SWT/Developer Guide"

< SWT
(eclipse.platform.swt)
Line 48: Line 48:
 
This repository is organized around five root folders
 
This repository is organized around five root folders
  
* bundles — where the code actually is written. It contains a project with the code of the SWT Tools (org.eclipse.swt.tools), a project org.eclipse.swt.fragments.localbuild (??? Don't know what it is about) and '''org.eclipse.swt''' the main project.
+
* '''bundles''' — where the code actually is written. It contains a project with the code of the SWT Tools (org.eclipse.swt.tools), a project org.eclipse.swt.fragments.localbuild (??? Don't know what it is about) and '''org.eclipse.swt''' the main project.
* features — contains only one feature: ''SWT Tools''. It is used to be able to install all [https://www.eclipse.org/swt/tools.php SWT Tools] (JNI Generator, Sleak and SWT Spy) in the IDE at once.
+
* '''features''' — contains only one feature: ''SWT Tools''. It is used to be able to install all [https://www.eclipse.org/swt/tools.php SWT Tools] (JNI Generator, Sleak and SWT Spy) in the IDE at once.
* local-build — <mark style="background:yellow">HELP NEEDED</mark>
+
* '''local-build''' — <mark style="background:yellow">HELP NEEDED</mark>
* examples — code samples and [https://www.eclipse.org/swt/snippets/ snippets]
+
* '''examples''' — code samples and [https://www.eclipse.org/swt/snippets/ snippets]
* tests — [http://junit.org/ JUnit] and performance tests.
+
* '''tests''' — [http://junit.org/ JUnit] and performance tests.
  
 
=== eclipse.platform.swt/bundles/org.eclipse.swt ===
 
=== eclipse.platform.swt/bundles/org.eclipse.swt ===

Revision as of 06:38, 17 March 2015

Introduction

SWT uses native operating systems widget toolkits. The most common supported operating system (or OS) supported by SWT Windows, Linux and OS X. The most common native toolkits (aka windowing system or WS) are: Win32 on Windows, GTK on Linux and Cocoa on OS X. Finally, SWT runs on several CPU architectures (or ARCH), the two most common being x86 (also known as i386, IA-32 or i586) and x86_64 (also known as amd64 or x64).

SWT is a Java framework. In order to be able to use the native toolkits, SWT has to use a feature of Java to call native code. This feature is called Java Native Interface (JNI). JNI lets you define methods in Java with the keyword native and the behavior of this method will be delegated to some native code (C/C++ or Objective C most of the time).

Usually with JNI, you would have to write the native code manually, and run the javah command on the Java files with native method to generate header that would bind your Java code and the native code (before compiling it). You would end up with something like that:

  • HelloWorld.java with a method declared as "native". This class is compiled with javac to a .class file.
  • HelloWorld.h is a C header file with the signature of the native method. It can be generated by the program javah (available with the Java SDK).
  • libHelloWorld.c, the native C code using system calls and JNI data structures to manipulate Java objects. This file requires to #include HelloWorld.h.

This method has several drawbacks. First, writing native code is very error prone. It is especially the case with SWT because it is only a very thin layer between Java and the native toolkit.

Note.png
Design choices
See article about SWT design choices for more background about it.

Basically, SWT is one-to-one mapping between a native Java method a a native system call. Lets take the gdk_window_set_cursor GTK system call. In the file OS.java, SWT developers write

public static final native void gdk_window_set_cursor(long window, long cursor);


and in the file os.c

JNIEXPORT void JNICALL gdk_window_set_cursor
	(JNIEnv *env, jclass that, jintLong arg0, jintLong arg1)
{
	gdk_window_set_cursor((GdkWindow *)arg0, (GdkCursor *)arg1);
}


This is pretty straightforward but cumbersome (and error prone) to write manually.

A second drawback about using javah is that it does not handle 32/64 bits automatically. You have to duplicate your code if you want to handle both of them. The overhead of writing both versions is heavyweight so SWT tackles the two drawbacks at once. You will read more about how it is done later, but first, lets dive inside the source code tree organization.

Important.png
Difference between using JNI on 32 bits and 64 bits OSes
The main difference when interacting with a 64 bits OS instead of a 32 bits one, is that pointer are 64 bits long instead of 32 bits. From a programmer point of view, Java is agnostic to the CPU's word size... except when doing native calls. So every integers representing a pointer in a system call has to mapped to Java long integer when using a 64 bits OS and mapped to a simple int when runnning on a 32 bits OS. In the previous example gdk_window_set_cursor, window and cursor are both pointers. This native method will work well with the 64 bits version of GTK, but not with the 32 bits as windows and cursor are declared as long integers.

Source tree organization

SWT is developed in two Git repositories:

eclipse.platform.swt

This repository is organized around five root folders

  • bundles — where the code actually is written. It contains a project with the code of the SWT Tools (org.eclipse.swt.tools), a project org.eclipse.swt.fragments.localbuild (??? Don't know what it is about) and org.eclipse.swt the main project.
  • features — contains only one feature: SWT Tools. It is used to be able to install all SWT Tools (JNI Generator, Sleak and SWT Spy) in the IDE at once.
  • local-buildHELP NEEDED
  • examples — code samples and snippets
  • testsJUnit and performance tests.

eclipse.platform.swt/bundles/org.eclipse.swt

It is a Java (JDT) project. It has a lot of source folders (between 25 and 30 depending on the platform you are building). The source code is split by features: printing support, browser support, OpenGL... Within each source folder, the code is organized by WS (win32, cocoa, gtk...). When some code does not require native call, it is written in pure Java and located in a folder named common (sometimes common_j2se or common_j2me when the WS is supported on mobile devices where only J2ME can be run). Let's take an example with the folder Eclipse SWT Drag and Drop (DnD). It contains 6 subfolders:

  • cocoa — OS X
  • common — Code common to all platforms (Java only)
  • emulated — Emulation of some features for platforms without native support (Java only)
  • gtk — Linux GTK
  • win32 — Windows Win32
  • wpf — Windows Presentation Foundation IS IT STILL MAINTAINED?

It means that for compiling DnD support on OS X with Cocoa, we need the sources in cocoa and common but for Windows, I need win32 and common. For platform without native DnD support both common and emulated are needed.

Note.png
Design choices
You know see another design choice of SWT: each platform has the same public API but classes and implementations are different. For instance, in the Windows implementation of the DnD support, there is a helper class OleEnumFORMATETC which is package private and specific to the DnD support on Windows. There is one Java source class file org.eclipse.swt.dnd.DropTarget.java in each subfolder of the DnD source folder. Each one must expose the same API as the others and must have the same Javadoc as client of these classes will only use one version running on their system later. Again, see article about SWT design choices for more background about it. The issue about the exposed API is even harder to maintain because with SWT, you code against classes and not interfaces. There is no inversion of control (with factory patterns or dependency injection framework). You call new Button(Composite, int).getText() wether you are on Windows, OS X or Linux and Button#getText() is not enforced in all implementations by the fact that Button implement an interface. REFERENCE NEEDED ABOUT THE FACT THAT THERE IS NO INTERFACES IN SWT.


Fortunately, you don't have to know the proper combination of source folders you need for your platform. org.eclipse.swt project has several .classpath files that defines all the source folders to take into account for each combination of WS/OS/ARCH:

  • .classpath_cocoa — OS X
  • .classpath_dojoWHAT IS DOJO? IS THERE AY RELATION TO http://dojotoolkit.org/? No natives, emulation only.
  • .classpath_gtk — Linux GTK
  • .classpath_gtk_j2me — Linux GTK on J2ME platforms
  • .classpath_win32 — Windows Win32
  • .classpath_win32_j2me — Windows Win32 on J2ME platforms
  • .classpath_wpf — Windows Presentation Foundation (IS IT STILL MAINTAINED?
  • .classpath_wpf_e4 — Windows Presentation Foundation for E4 (IS IT STILL MAINTAINED? WHY IS THERE SOMETHING SPECIFIC FOR E4?

eclipse.platform.swt.binaries

This repository contains only one folder: bundles which contains one folder/project per supported combination of WS/OS/ARCH

JNI Generator

SWT uses a home made tool call JNI Generator to generate both .c and .h files. The source of this tool are located in the project org.eclipse.swt.tools (JNI Generation subfolder). A introductory documentation of this tool is available online. Basically, it parses the file OS.java in the current classpath and generates os.c and os.h accordingly. Whenever you change something in OS.java in your IDE, a dedicated builder (org.eclipse.swt.tools.jnibuilder) is called along with the Java compilation to update os.c and os.h.

Back to the top