FAQ for the AWT
===============

AWT Implementations
-------------------

Since Kaffe 1.1.5, we have successfully merged the peerful AWT implementation
based on GTK+ from GNU Classpath, and the old one, peerless lightweight AWT,
is renamed as kaffe-awt. The so-called peerful AWT implementation intends to
map Java AWT peers into the corresponding widget set of specific environment,
and that is GTK+ for the case of current GNU Classpath development. In other
side, the original peerless kaffe-awt is lightweight, which means that it
only makes use few necessary dependencies for basic requirements, such as 
window creation, drawing operation, color allocation, etc. You could find
that peerless AWT implementations look alike among different backends, while
the peerful AWT implementations differ a lot. Jim Huang prepares a compre-
hensive comparisons of existing AWT implementations as the following
screenshot:
  http://www.kaffe.org/~jserv/awt-implementations.png

Selection among different AWT implementations in Kaffe is very easy, just
use "kaffe -help" to dump help message. For example pass -Xkaffe-xlib-awt 
to force KaffeVM to use Xlib-based AWT backend, while GNU Classpath's AWT
is selected by default.

GNU Classpath AWT implementation
--------------------------------

GNU Classpath AWT implementation is enabled in default build process, but
the original peerless AWT ones are turned off. We attempt to merge AWT/Swing
implementation from recent GNU Classpath cvs repository. To build this, make
sure if GTK+ 2.4 and its development packages are available. Optionally, you
might need Cairo Graphics framework (http://www.cairographics.org/) to enable
the new Graphics2D implementation, which is reported to let many complex AWT
and Swing applications, such as JFreeChart, run well. Tell configure script
with --enable-gtk-cairo to enable new Graphics2D, and drive your Java startup
command with -Dgnu.java.awt.peer.gtk.Graphics=Graphics2D to use Cairo-based
Graphics2D implementation.

GNU Classpath AWT is very excellent to meet the specifications of Sun JDK,
and you can look into the latest comparison from [Results of comparison 
between jdk14 and classpath]:
  http://www.kaffe.org/~stuart/japi/htmlout/h-jdk14-classpath.html


Peeless AWT implementations
---------------------------

[= 1.0.2 Event Model / Deprecated methods =]

We do support the old 1.0.2 event model and all 1.0.2 deprecated methods,

[= Swing =]

We completely support Swing. The version that works best with kaffe is
the JFC 1.1 with Swing 1.1.1, which is labeled as EOL (End-Of-Life), and
you might have to browse Sun's web page to seek for archive download:
  http://java.sun.com/products/archive/index.html

Note: Later versions may or may not run. Patches to get them to run are 
welcome. It would be in general preferable to help out GNU Classpath to 
implement SWING, though.

Whatever Sun may tell you about Swing being 100% pure Java - just don't
believe them.  Swing make a number of assumptions about the underlying AWT
implementation and makes calls to a number of "banned" methods - oh and it
makes extensive use of deprecates.

[= Selecting an peerless AWT implementation =]

Currently, the peerless AWT implementations are disabled in default build,
and you have to pass --with-kaffe-x-awt to configure script. Also, there 
are different peerless AWT backends for Kaffe. You can configure it to
use a specific one, by using the --with-awt option of the configure script.

So far, you have the following choices:

* --with-kaffe-x-awt

  an X lib based AWT backend. It is the default AWT backend if the X
  Window system is detected by the configure script.

  The X lib based AWT backend has been written by Peter Mehlitz from
  Transvirtual.

  See http://www.x.org for information on X Window System.

  You need to run kaffe with -Xkaffe-xlib-awt option, in order for it
  to load the correct classes for this AWT. So you should run your
  code with

  kaffe -Xkaffe-xlib-awt YourClass

* --with-kaffe-qt-awt

  a Qt based AWT backend. It uses Trolltech's cross-platform graphical
  library. It works with Qt 3 and Qt 2, Qt/Embedded or Qt/X11 version. 
  It should also work with Qtopia. 

  It may work with other versions of Qt 3 or Qt 2 (Win32, OS X), but
  it has not been tested in such configurations. If you can test it in
  such configurations, please report your experiences to the Kaffe
  Mailing List, kaffe@kaffe.org.

  If you are developing against a dynamically linked version of Qt,
  you need to compile kaffe with dynamically linked libraries. If you
  are developing against a static version of Qt, you need to compile
  kaffe with statically linked libraries. In general, you should try
  to match linking types of libraries.

  In order to compile the Qt based AWT backend, you need to have an
  installation of Qt libraries including the moc compiler and the Qt
  header files. You have to pass the full path to the directory of
  your Qt installation to the configure script using the --with-qtdir
  option. 

  You also have to make sure the moc compiler is in your $PATH. It can
  usually be found in the bin directory of your Qt installation. If
  you can not find it, you need to install the developer version of the
  Qt libraries. How to do that is system dependent, on Linux you may
  have to get a libqt3-developer package for your distribution, or
  compile Qt from scratch.

  Finally, in order to be able to dynamically link Kaffe's AWT backend
  with the Qt libraries, you may have to add the lib directory of your
  Qt installation to your native linker's library lookup path. On
  Linux, that means you may have to add the lib directory to
  LD_LIBRARY_PATH.

  The initial Qt based AWT backend was written by Murphy Chen and Ken-Hao
  Liu from Dialogue Technologies, Inc.

  More information on Qt is available from http://www.trolltech.com.

  You need to run kaffe with -Xkaffe-qt-awt option, in order for it
  to load the correct classes for this AWT. So you should run your
  code with

  kaffe -Xkaffe-qt-awt YourClass

* --with-kaffe-nanox-awt

  a Nano-X based AWT backend. It uses famous Nano-X library provided
  by Nano-X Window System (formly known as MicroWindows, the project 
  has been renamed to The Nano-X Window System, due to conflicts with 
  the Windows trademark registered by Microsoft.)

  The latest version of Nano-X we developed with is 0.9.0, and it 
  should be API-compatible with earlier versions.

  The initial Nano-X based AWT backend was written by Exor International 
  Inc. and Sinby Corporatin in 2001, and we have reviewed their design
  and implementation to merge in.

  To enable Nano-X based AWT backend, you should also pass the extra
  two options to configure script, --with-nanox-include and 
  --with-nanox-library, to specify the the corresponding Nano-X path.

  See http://www.microwindows.org/ for informations on Nano-X.

  You need to run kaffe with -Xkaffe-nanox-awt option, in order for it
  to load the correct classes for this AWT. So you should run your
  code with

  kaffe -Xkaffe-nanox-awt YourClass

Troubleshooting
---------------

* Qt-based AWT backend

  * Compilation problems

    Make sure that either QTDIR is set, or that you passed a
    --with-qtdir flag to the configure sript. Don't use relative
    paths to specify directories.

  * Moc trouble

    Make sure that the build system picks up the right moc for the
    version of qt you are compiling against. So if you have several
    versions of qt installed on your system, put QTDIR/bin to the
    front of your PATH before you start configuring and building
    kaffe.

  * Linker complains about missing symbols

    That could be an instance of moc trouble above, but more often
    it's a problem between C++ ABIs of the compiler used to build qt
    you want to link against, and the compiler you used to build
    kaffe's Qt-based AWT with.

    The GNU C++ compiler g++ had a short period where the ABI changed
    with almost every release, so if you are using a Qt library
    compiled with one of those 'interim' versions, your best bet is to
    rebuild Qt frim scratch with your current compiler.

  * QTDIR, QTEDIR, QPEDIR is pointing to the wrong directory.

    Qt uses QTDIR to find its fonts, and may use the other environment
    variables to locate other crucial bits for execution. Make sure
    that you've got them pointing to the right directories, i.e. the
    versions you compiled against. Read Qt toolkits installation
    description for more information on those environment variables.

  * Dynamical linking fails 

    Make sure that you've linked to correct versions of Qt
    library. Use ldd to check if KAFFE_HOME/jre/lib/your-cpu/libawt.so
    links to it.

    Other that that, you should make sure that the Qt libraries can be
    found by the linker. Putting QTDIR/lib in LD_LIBRARY_PATH might
    help.

  * Qt AWT backend can't show GIF images

    Currently, Qt AWT backend handles all images routines via Qt
    toolkit, and this behavior is totolly different to X AWT backend.
    The GIF support is disabled by Qt's default configuration, and
    you need to reconfigure to enable the feature if you would like
    to let Qt AWT backend support it.

  * Qt/Embedded AWT doesn't work in console

    You need to redirect the stdout and stderr streams so that they
    don't interfere with the framebuffer. The Qt based AWT
    implementation is still rather rough, so it prints a lot of
    debugging output which confuses the framebuffer, apparently.

  * Qt AWT backend crashes, how can I help?

    First, Qt AWT backend in Kaffe is still buggy, so any feedback 
    is important to developers for improving. You may attempt to 
    enable the debug option in Kaffe (configure as --enable-debug 
    support, read FAQ/FAQ.debugging), and execute a Java AWT 
    application like:

      kaffe -vmdebug AWT -cp <CLASSPATH> <CLASSNAME>

    Qt AWT backend will dump debug messages in stderr, and you could
    redirect to text file. To specify the Qt AWT native part, you
    pass some arguments, such AWT_EVT, AWT_CLR, etc. to -vmdebug 
    option.

  Finally, try to figure out what's wrong using a debugger according
  to the debugging messages you obtain. Good luck and please keep in
  touch with the kaffe mailing list kaffe@kaffe.org.

Other AWT backends
------------------

The source code for the PocketLinux version of Kaffe includes AWT
backends for many other graphical toolkits. If you are interested in
helping the Kaffe developers merge them with the Kaffe.org sources,
contact us on the Kaffe Mailing List kaffe@kaffe.org.

The list of backends from PocketLinux includes Gtk1, grx, peg, Allegro
and a few others. The major difference in native AWT implementation
between Kaffe.org's and PocketLinux's is that PocketLinux's AWT 
depends on more native functions from graphics toolkit / widget set 
for the advanced usage. For example, PocketLinux's AWT implementation
even supports the dynamic theme switching feature with more 
decorations.

There are other AWT backends written by third party developers that
haven't been merged in yet:

* DirectFB

See the following posts for more information:
http://www.kaffe.org/pipermail/kaffe/2002-December/028462.html
http://www.kaffe.org/pipermail/kaffe/2005-February/101410.html .

If you are interested in merging them in, contact the Kaffe Mailing
List on kaffe@kaffe.org.

Projects
--------

If you want to contribute to kaffe's AWT developement, you could

* Write documentation

  Document the workings of kaffe's AWT to make life easier for porters
  and mergers.

* Refactor current AWT implementation

  The AWT implementations share some common native code that should be
  in a common AWT library. Take a look at Pocketlinux for an idea.

  Kaffe's AWT doesn't follow Sun's peer concepts, and makes it hard to
  'override' the default AWT implementation. Refactor kaffe's AWT to
  allow alternative AWT implementations (like PJA) to be plugged in
  easily, and to allow multiple native AWT backends to be built and
  selected at runtime.

* Merge in another AWT implementation

  Pick one of the Pocketlinux AWT implementations, and merge it in.

* Write another AWT implementation

  If your platform has a native graphical library, then the presumably
  fastest AWT implementation would use the native toolkit.

  Or go the other way around, and write an AWT implementation for a
  cross platform graphical toolkit, like wxWidgets, or SDL, bringing
  AWT to platforms where no Qt or X11 are available.