Using SWT - SWT: The Standard Widget Toolkit
|
< Day Day Up > |
|
Using SWTSo far, we have been looking at the rationale and history behind SWT. Before we begin taking a closer look at its structure and how to use it, we pause for a moment to show you some code. Your First SWT ProgramSWT applications almost always have the same shape. They begin by creating a connection to the platform window system, then they create a window using that connection, then they react to the events that are generated by the platform window system until some action by the user causes the application to exit. Here is an example of what that looks like in the form of a simple SWT "Hello World"[5] program.
import org.eclipse.swt.widgets.*;
public class HelloWorld {
public static void main(String[] args) {
Display display = new Display();
Shell shell = new Shell(display);
shell.setText("Hello, World.");
shell.open();
while (!shell.isDisposed()) {
if (!display.readAndDispatch())
display.sleep();
}
display.dispose();
}
}
If you want a complete breakdown of what the code in the HelloWorld program does, you can check the introduction to Part 1 (see HelloWorld in SWT). You can also see the subsection Running SWT Applications for detailed information about compiling and running SWT applications. Ignoring those details for the moment, if you invoke the HelloWorld program, it will cause a window to open that looks something like Figure I.1 Figure I.1. Result of running the HelloWorld program.
A Few Words about Screen ShotsSWT runs on many platforms. On each one, applications that are built with SWT take on the look and feel of the underlying window system. For example, the screen shot in Figure I.1 was made on Macintosh OS X. Figure I.2 shows what the window produced by running the HelloWorld program would look like on Microsoft Windows XP. Figure I.2. The HelloWorld program on Windows XP.
To remind you that SWT applications take on the native look and feel of the platform, some of the screen shots in this book are taken from each one梐t least each one that we could convince to do screen captures. The choice of platform for a particular screen shot is arbitrary unless the point under discussion is specific to that platform. SWT PackagesThe SWT library is divided into a number of Java packages, based on logical groupings of functionality. In Eclipse terms, most of these packages are defined to be API packages, meaning that all publicly visible elements contributed by the package (i.e., the definitions of the public and protected classes, methods, and fields) are available for your use and will remain constant over time, except in certain very restricted circumstances.[6] In practice, releases of SWT are binary-compatible, meaning that a program compiled against the API packages of a previous version of SWT will run on later versions without recompilation.
The SWT library also includes packages that are not API. These packages are identified by the word internal embedded in their package names. You should treat these packages purely as part of the implementation of SWT, even when they contain public elements. Typically, they have been marked as public only so that they can be shared by several parts of the implementation. There are absolutely no guarantees that the classes and methods visible in internal packages will continue to be available from release to release. Another way that the SWT packages are characterized is based on the platforms on which they are available: Packages that exist on only one platform contain the unique name for the platform (called the platform code) embedded in their package name. Because SWT is intended to be portable, platform-specific packages are almost always also internal. As of the writing of this book, the only platform-specific API package is the one that provides access to OLE (also called Active X) in Microsoft Windows. A list of the SWT API packages and the functionality they provide can be found in Table I.1. Note that this list reflects the situation at the time this book was written.
In this book, we will be looking predominantly at the first five packages.
These packages represent the "meat" of SWT; almost all applications will make use of them, and understanding them is fundamental to using SWT. The remaining packages will be touched on in context but will not be covered in detail. SWT Packages and Memory ConstraintsThis section will predominantly be helpful to you if you are planning to use SWT in a context where there is limited memory. However, it also provides some useful insight into the relationship between various SWT packages. The SWT API packages have been arranged into a dependency hierarchy, so that classes defined in packages that are lower in the hierarchy never reference objects that are in higher packages. Aside from being simply good programming practice, making it simpler to separate and debug different areas of functionality, this has two other significant benefits.
The simplest way to reduce the size of the library is by removing entire packages that contain functionality not required by your application. Table I.2 shows the dependencies between the SWT packages.
From the table, you can see that the packages that provide program, printing, layout, drag-and-drop support, the Web browser, SWT/AWT interoperability, and the custom widgets package can be deleted if their functionality is not needed. The custom widgets package, by virtue of the high-level functionality it provides, ends up tying together most of the other packages. The org.eclipse.swt.events package is interesting because although the typed event mechanism it implements is used throughout the native widget API, the native widgets themselves use a simpler, untyped event mechanism internally. Because of this, it would be possible to remove the events package, as well, if the matching API methods in the native widgets package were also removed. Obviously, this type of pruning would be attempted only if space constraints were critical. Event handling in SWT, both high-level and low-level, is described further in the section Events and Listeners. After all this, if SWT was still too large to fit your required memory footprint, the native widgets package (org.eclipse.swt.widgets) can also be removed! At this point, all you are left with is the ability to use the graphics routines to draw directly on the screen and platform-specific API methods in the native interface layer to handle input. Although this is beyond the requirements of almost all reasonable situations, it is still possible, should extreme circumstances arise. The SWT implementers are serious about making SWT useful across the widest possible range of targets. In addition to making it possible to remove unused packages as described above, care has been taken to minimize the set of features that SWT uses from the standard Java base class libraries. This means that SWT does not need the most current Java Runtime Environment to run. In fact, SWT will run on Java2 Micro Edition (J2ME), because any Standard Edition features that are used by the native widgets and graphics packages have been factored out, and J2ME-compatible versions have been created. For example, both J2SE and J2ME versions of SWT for Microsoft Window CE on ARM processors have been prebuilt and are available at Eclipse.org. These versions have had the custom widgets removed and have only a 500K footprint. Running SWT ApplicationsTo run an SWT application, you need two sets of components.
Getting SWTSWT is available from www.eclipse.org. The link to the main download page is http://www.eclipse.org/downloads/index.php. Eclipse is a very dynamic, active project, and this page can provide you with a bewildering number of choices for drops (i.e., versions) of Eclipse to choose from. You need to pick one of these to get to a page that contains both full Eclipse drops and separate SWT drops for each platform. There are really only two interesting choices here.
For most uses, the stable build is the best choice. You would only pick the latest release if the extra product testing is worth sacrificing the new features and bug fixes that were made since then. Of course, if you are shipping a product based on SWT, you might consider this extra testing to be important. There are also weekly integration builds that are even more current than stable builds. You would move to an integration build only if it provided a missing feature or a particular bug fix that you needed in your application that was not available in the last stable build.[7] Integration builds are typically stable, but this is not always the case. Very little testing is done beyond running the automated regression test suites. In most cases, waiting for the next stable build is a better choice.
Once you have picked which drop you want, you need to select the version of SWT that is appropriate for your platform. The drops Web page enumerates the available choices. If you scroll to the bottom of the page, you will find stand-alone SWT drops for the platforms shown in Table I.3.
The list of supported platforms changes over time. There are always efforts within the open source community to produce versions for new platforms. As these mature, they will be added to the list. The dual of this is that if the support for a particular platform disappears, it will be removed from the list. The mainstream platforms, at least, will continue to be supported for the foreseeable future. The Eclipse Project Draft Plan, available at www.eclipse.org, contains a full list of supported platforms, including operating system version numbers. Regardless of the SWT drop you choose, the ZIP file will contain at least the following files.
Depending on the platform you are running, there may be several shared libraries provided with the drop. For example, the drops for Linux and the various Unix variants contain, in addition to the main shared library, one or more shared libraries that provide SWT with access to the active desktop manager (Gnome, CDE, etc.). In addition, the Linux X/Motif-based version includes the OpenMotif shared libraries that it requires. It is also possible to have more than one JAR file included in the drop. For example, the GTK port of SWT has three JAR files, swt.jar, swt-pi.jar, and swt-mozilla.jar. The swt.jar file contains the SWT implementation classes. The swt-pi.jar file contains the Java code for the GTK platform interface routines. Similarly, the swt-mozilla.jar contains the classes that interface to the Mozilla browser code. In this case, for each JAR there is a matching shared library. All JARs and shared libraries that are included with a given SWT drop must be accessible when your application runs. The next section describes how to do this. Installing as an ExtensionOnce you have an SWT drop, you need to make the classes that it contains available to your programs. There are various ways to do this, but the simplest by far is to install SWT as a Java extension. This makes SWT available to all Java programs in exactly the same way as the Java base classes. The steps to create an extension vary, depending on the platform and the VM you are running, so you may need to check the documentation that came with your Java install. If you are using the Sun Java VM on Windows, you would do the following.
where NNNN is just the four-digit SWT build number that shows up in the DLL included with the drop. Similarly, to install SWT as an extension on Solaris, you would do the following.
where, as above, NNNN is the four-digit build number that shows up in the names of the .so files included with the drop. When SWT is installed as an extension, you can compile the HelloWorld example by simply typing javac HelloWorld then run it by typing java HelloWorld This makes developing using SWT as simple as developing using AWT or any other part of the Java base libraries. Using Command Line ArgumentsIf you want to make SWT available to a single program, you can reference the SWT library using command line arguments. The swt.jar file and any other JAR files that are included need to be added to the classpath using the 朿lasspath or 朿p options when compiling and running the application, and the directory containing the shared library files must be added to the java.library.path system property using the 朌 command line argument when the application is run. As an example of what this looks like in practice, if you had installed the GTK version of SWT in your /home/me/swt directory, you could run the HelloWorld example on Linux like this.[8]
java \ 朿p .:/home/me/swt/swt.jar:/home/me/swt/swt-pi.jar \ 朌java.library.path=/home/me/swt \ HelloWorld In order to run the Linux X/Motif version, you need to make sure that the OpenMotif libraries that are included with the SWT distribution are visible. This can be achieved by setting the LD_LIBRARY_PATH to include the directory where they are found. Thus, if you had installed the X/Motif version of SWT in your /home/me/swt directory, you could run the HelloWorld example as follows. export LD_LIBRARY_PATH=/home/me/swt java \ 朿p .:/home/me/swt/swt.jar \ 朌java.library.path=/home/me/swt \ HelloWorld If you are using command line arguments to specify the SWT information, you will typically build a batch file or shell script to invoke your application. Stand-Alone SWT and Mac OS XAs of the writing of this book, the Java VM on Macintosh OS X has some oddities that make running stand-alone SWT programs problematic. The issues have been reported to Apple, and the hope is that they will eventually be resolved, but to work around them in the meantime, a custom Java launcher was created. This launcher is embedded within the Eclipse application but is also included in the Macintosh SWT drops. Given java_swt, you can run a stand-alone SWT application by passing in the locations of the swt.jar file and shared library directory exactly as you would on other platforms. For example, if java_swt were in the current directory and SWT were installed in the swt subdirectory, you could run the HelloWorld program by typing the following command into a Terminal window. ./java_swt \ 朿p .:./swt/swt.jar \ 朌java.library.path=./swt \ HelloWorld Unfortunately, there are several problems with this approach, not the least of which is that most Macintosh users would rather not type commands in Terminal windows. In addition, the menu bar of the resulting application has "java_swt" as the name of the application. What is really needed here is a "distiller," such as the MRJAppBuilder that is included with the OS X developer tools, that creates double-clickable SWT applications. The SWT implementers are actively working on improving the integration between SWT and Macintosh OS X. We hope that in the near future, the Macintosh version of Eclipse will include extensions for creating double-clickable applications directly from within the environment. Whatever form this takes, it will almost certainly support creating SWT applications, because using it to create the Eclipse application itself would be an important requirement. Using Eclipse to Get SWTWhen you download an SWT drop, you get only the subset of the codebase that is applicable to a particular platform. That is almost always the right answer for a stand-alone application developer. This section describes how to get the full source for SWT. It is a relatively complex process, and you can safely skip this section if you are not one of the following.
Even if you are using Eclipse to develop your application, you can still download SWT and configure your environment as described in the previous section. For those who want to see the full picture of SWT across all platforms, the first step is to connect to the Eclipse CVS repository. The repository can be found at dev.eclipse.org, and it accepts anonymous pserver connections. The main SWT project module is called org.eclipse.swt. This contains the SWT Java code for all supported platforms. Included in the org.eclipse.swt project are a number of XML files with names of the form .classpath_<platform> or .classpath_<platform>_j2me where <platform> is the platform code that identifies a particular implementation of the SWT library. The _j2me variant is intended for use on Java2 Micro Edition virtual machines; the other version is for use with J2SE and J2EE. Table I.4 shows the possible values of <platform>.
The .classpath files describe which subdirectories in the SWT source need to be included in order to create a working SWT implementation for that platform. They are human-readable and could presumably be used manually to select the subdirectories to compile and use, but the best way to deal with them is the same way that the SWT implementers do: Use Eclipse. Assuming you are familiar with Eclipse,[9] you can check out either the HEAD stream or a version of the org.eclipse.swt project from the repository, using the CVS Repository Exploring perspective. The versions are named with tags that contain the same build numbers found in the SWT shared library files.
Once you have checked out the project, you will need to select which platform you are going to develop for. To do this, take the following steps.
When the .classpath file is modified, Eclipse will automatically recompile the project if the Perform build automatically on resource modification preference is enabled (as it is by default). By requiring the extra step of setting the classpath when loading the project, the code for all SWT implementations can be kept in one project. This makes simultaneously managing all the platforms much simpler. At this point, you have the SWT Java code configured for use on a particular platform. To allow it to be referenced from another project in the workspace, you need to select the org.eclipse.swt project in the Java Build Path (pop up the context menu on the project and select Properties) of the project you want to compile. To run an application from within Eclipse that uses the SWT you have loaded, you will also need the shared libraries that match it. For each platform, there is a project in the dev.eclipse.org repository named org.eclipse.swt.<platform> where <platform> is one of the platform codes described above. These projects contain all of the required shared libraries for that platform. You should load the version of the appropriate org.eclipse.swt.<platform> project with the version tag that matches the version of org.eclipse.swt you are using. Locate the shared libraries within that project; the path is different for each platform to allow the libraries for more than one platform to be installed in a single location (for example, to allow Linux GTK and X/Motif versions to coexist). To run your application, create a Run… launch configuration as you normally would, then add a 朌java.library.path=… line to the VM Arguments that points at the directory containing the libraries. Now you are ready to go. You should be able to run and debug both applications that use SWT and the SWT code itself from within Eclipse.
OnwardThis part of the book has provided you with the rationale and history behind SWT and the details of how to compile and run SWT-based applications. The remainder of the book covers the SWT widgets and graphics API in detail, then provides some real-world examples of applications built with SWT. |
|
|
< Day Day Up > |
|