Artem Ananiev's Blog

Using JWebPane: common scenarios

In the last blog posting I introduced a new component called JWebPane that renders HTML content in Java applications. Today I'd like to discuss the details of the practical use of this component. Let me start with typical use cases.

1. HTML Rendering

Since the necessity of employing this component in GUI applications appeared a long time ago, each solution, even simple rendering of web pages, is greatly appreciated. Moreover, in spite of the fact that the importance of interactivity is rising steeply, the correct rendering of up-to-date web content still remains a crucial requirement for an HTML component. It's worth mentioning that JWebPane copes with this task successfully along with the help of WebKit, one of the most advanced web engines.

2. Load event notifications

Let's move on to more interesting items. The load control of web pages and its resources is another highly demanded function required by many users. For this purpose JWebPane provides the following events: page loading start, external resource loading start, loading progress, loading stop or error, page loading finish, and resources loading finish. The exact set of events is not finalized yet, and new event types will appear soon.

3. Navigation

Sometimes using the HTML component is limited to one document, however, the HTML format itself implies tie-up and cross linking of documents. Navigation control, such as Back, Forward, Get URL and other commands, is naturally provided by JWebPane. The navigation function is closely related to transfers from one page to another. This is quite a controversial point: on the one hand, the application should maintain the history, but on the other hand, the component possesses information about which web sites were visited during the current session. That's why JWebPane provides the basic tools for history maintenance as well as the ability to retrieve history from the application.

4. Chrome

I always wondered where did the "chrome" term come from :-) This term is used to specify the HTML component environment, which is usually a browser window. Chrome typically includes support of the following elements: status bar, window title and icon, tooltips, window size, the component itself, and others. JWebPane, as an HTML component, doesn't have built-in support of these controls, however, it provides an API to implement those in the application.

5. What next?

Undoubtedly, the list of the JWebPane features is incomplete. I'm going to tell you more about the coolest ones, for example, how to create new windows or how to work with JavaScript. Additionally, we would like developers that are ready to use JWebPane share their ideas and visions. After all, they indeed define what kind of features should the convenient and handy HTML component have. Don't they?

Introducing JWebPane component

Recently, at the JavaOne conference, Sun has introduced several new JavaFX related technologies and products. The Scene Graph and WebKit session was one of the technical sessions to present such advanced technologies:

Inside The JavaFX™ Script Technology-Based Runtime APIs: Scene Graph & JWebPane Component

This blog entry opens a series of articles about the technology described in the second part of the presentation - HTML component JWebPane. I'm set to explain what is it, when it could be employed in your application and when it couldn't be. :)

For many years, Java lacked a worthy component to render HTML content. HTML support in Swing was limited to the 3.2 version. Although the SwingLabs JDIC library provides a browsing component, it is hard to integrate into Swing applications because of its heavyweight implementation. The new component - JWebPane is not intended to substitute all known alternatives, however, it brings HTML support and easiness of use up to the high-level standard.

Those who attended the JavaOne session already know that JWebPane is based on the widely recognized open sourced engine - WebKit. It is not a secret any more. :) The WebKit architecture consists of two considerable parts. The first one is cross-platform, it is responsible for parsing documents, generating DOM, supporting JavaScript. Another part, platform-dependent, so called "port", is intended for communicating with network, rendering graphic content on the screen and other devices, event handling, and other features. JWebPane is a Java port, in which all cross-platform calls are implemented in Java.

Additionally, each port provides an API to develop browsing functionality using a particular library. For Java port, it is non surprisingly JavaFX. Moreover, JWebPane will became available in Swing applications. At the moment the API provides the following capabilities: adding the JWebPane component to the hierarchy of graphic components, documents loading control, handling the loading status events, navigation history support, and new windows control (both adding and removing). This API is supposed to be extended, if needed.

Finally, I'd like to demonstrate a small screen shot of the JWebPane application with new Nimbus Look and Feel available in JDK 6u10:

Next time I'll expose some technical details of the Java-port implementation and its interaction with WebKit.

Other blogs related to JWebPane:

HTML component at http://blogs.sun.com

java.awt.TrayIcon: isSupported vs isAvailable

Description of the problem

When the java.awt.SystemTray class was first introduced in JDK 6.0, there was only one method to check if the system tray and tray icons can be used: isSupported(). The value returned by this method is constant for the given desktop/environment, for example, on Windows platform it always return true.

Another thing that can help the developers with the system tray is AWTException thrown by SystemTray.add(TrayIcon icon) method. According to the JavaDoc for this method, this exception is thrown "if the desktop system tray is missing". One of the common cases when the system tray is missing is when the notification area applet is removed from the GNOME desktop manually by user.

Recently I have faced another problem, on Windows. There are several projects that make possible to install a Java application as a Windows NT/2K/XP service. Some of such Java applications may interact with the user using SystemTray and TrayIcons. Here the problem lies: Windows services may start before any user is logged in, so no taskbar and system tray are present.

Introducing `isAvailable` method

Obviously, the isSupported() method is not enough. Developers should be able to detect not only whether Java supports the system tray on the given platform, but also whether the system tray is currently present and tray icons can be added into it.

The most probable name for the new method will be isAvailable. Additionally, it may be useful to have another method in the SystemTray class that works the following way: if the system tray is available, adds the given tray icon into it, if not - waits until the tray becomes available and then adds the icon. AWTException is not required for this case.

Introducing a new property

There is another problem to be resolved to make the using of tray icons easier. Consider an application like an instant messenger that is run as an icon in the system tray, without any other visible window. If the system tray is removed or made unavailable this application may lose some of its functionality.

Alternatively, using a property that changes its value when the system tray becomes available/unavailable, enables an application to listen for that property change and behave correspondingly. For example, an application can show some toplevel window.

There is already a property called 'trayIcons' in the SystemTray class. The new property will be accessible as a parameter of the java.beans.PropertyChangeListener interface instance by using the same methods: addPropertyChangeListener and removePropertyChangeListener.

Improved top-level icons support in Mustang

What's the problem?

In Java™ 2 SE 5.0 and previous releases a single method in java.awt.Frame class enables developers to specify an icon for the frame: setIconImage(Image image). This image had an arbitrary size and it was scaled to represent frame's icon in a different locations.

Let's assume that application is running on Windows platform. Icon that was set to the frame is used in several places: on the frame's title bar, on the button on the system taskbar, in the window list when switching to another application by pressing Alt-Tab. The taskbar icon usually has a 16x16 pixels size, the title bar icon size varies depending on the user settings, window list uses a 32x32 sized icons. Thus, if we specify an image of 16x16 pixels size, it will look fine in a taskbar and ugly when switching to another application. The 32x32 pixels image has the similiar problems.

More icons

In the Mustang release the following new method is introduced to the java.awt.Window class: setIconImages(List icons). Using this method you can supply as many images as you need to represent window's icon.

How does it work? Every time either the system or window manager needs an icon for Java window, it examines the list of specified images and searches for the image of the most appropriate size. Exact definition for this 'most appropriate' size is platform-dependent.

Dialogs icons

You may have already noticed that the new method is added to the java.awt.Window class, not to the java.awt.Frame class. In particular, this fact means that you can now set an icon for Java dialogs as well as for frames. This feature is extremely important for parentless dialogs introduced in earlier Mustang builds.

If no icon is set for a dialog, it inherits the icon from its parent window. If a parent is null - that means the dialog is parentless - the platform-default icon is used. If a parent is not-null and no icon was explicitly set for the dialog, then the icon is inherited from the parent window.

When will this API be available?

The answer is: it is already available, since Mustang b85 build was released at the end of May. However, some minor improvements are planned for the next Mustang builds.

java.awt.Desktop vs Runtime.exec()

Desktop API vs Runtime.exec()

I'm often asked why is that new class, java.awt.Desktop, is introduced. They state all the required actions can be performed with the call to one of Runtime.exec() methods:

    Desktop.getDesktop().open(new File(filename));

is close to

    Runtime.getRuntime().exec("start " + filename);

So I decided to write a couple of words about this issue to answer the most of such questions at once:)

The difference is...

The problem with the "start" invocation is that it only works on the Windows platform. It will fail on the Mac, Linux, and Solaris platforms. With the Desktop API, you can be guaranteed that it will start an application on all platforms.

There are also lots of other handy features in the new API, such as open, edit, print, and two special actions - browse and mail - that launch separate processes.

See java.awt.Desktop JavaDoc for details.

Using JPopupMenu in TrayIcon

What's the problem?

Tray icons introduced in Mustang have several properties and methods corresponding to image for the icon, tooltip text, popup menu and ability to show some message to the user. Let's inspect the popup menu more closely.

Popup menu used in tray icons must be an instance of java.awt.PopupMenu. This class represents a menu and allows to insert or delete simple menu items and separators. You cannot change its appearance or even provide an image for particular menu item.

Use JPopupMenu instead

There is another class to create popup menus provided by Swing: javax.swing.JPoupMenu. As all Swing components this class can be customized in any way and makes use of the current Look&Feel. Here is a short illustrating example how it can be used:

First, create a tray icon with a null popup since we're going to use our own one:

    TrayIcon trayIcon = new TrayIcon(someImage, "Tooltip", null);

Then, create a custom JPopupMenu:

    JPopupMenu jpopup = new JPopupMenu();

    JMenuItem javaCupMI = new JMenuItem("Example", new ImageIcon("javacup.gif"));
    jpopup.add(javaCupMI);

    jpopup.addSeparator();

    JMenuItem exitMI = new JMenuItem("Exit");
    jpopup.add(exitMI);

At last, show the popup menu when user clicks a right mouse button on the tray icon:

    trayIcon.addMouseListener(new MouseAdapter() {
        public void mouseReleased(MouseEvent e) {
            if (e.isPopupTrigger()) {
                jpopup.setLocation(e.getX(), e.getY());
                jpopup.setInvoker(jpopup);
                jpopup.setVisible(true);
            }
        }
    });

And enjoy the result:

Magic?

You may probably ask me: "What is that magic line 'jpopup.setInvoker(jpopup);' for?" The answer is not as simple as quiestion is, though.

JavaDoc for JPopupMenu.setInvoker() method says that invoker is the component in which the popup menu menu is to be displayed. This property can be set to null, but it leads to popup menu to operate incorrectly.

Setting popup's invoker to itself has some side-effect too. Usually, if you dispose all the windows in your application, Java exits automatically. If you show JPopupMenu with self invoker, it won't, so the only way to terminate the whole application is to call to System.exit().

Both of these issues are well known to Swing team and will be corrected before the Mustang final release. See 6421284 and 6400183 for details.

Headless toolkit basics

Toolkit

java.awt.Toolkit is an abstract superclass of all actual implementations of the Abstract Window Toolkit (AWT). Subclasses of java.awt.Toolkit are used to bind various components to particular native resources.

You may have noticed that many of the methods in java.awt.Toolkit, java.awt.GraphicsEnvironment and other classes require the availability of display, keyboard and mouse. You may easily find such methods as they throw java.awt.HeadlessException in headless mode.

What is that headless mode?

Headless mode

Headless mode is a system configuration in which graphic adapter, keyboard or mouse are lacking. For example, mainframes or dedicated servers do not support a display, keyboard or mouse. On the other hand, such environments possess a substantial computing power, which can be used for the non-visual features realization.

All the AWT components with the exception of Canvas and Panel can not be operated in Headless mode. These include: applets, buttons, checkboxes, choices, dialogs, file dialogs, frames, labels, lists, menus, menubars, popup menus, page and print dialogs, scrollbars, scrollpanes, text components, windows, and their descendants. Such heavyweight components require a native "peer" at the operating system level, which cannot be guaranteed on "headless" machines.

Here is a brief list of what is available in Headless mode:

    * lightweight components: canvas, panels, Swing components (with the exception of JApplet, JDialog, JFrame and JWindow)
    * fonts and font metrics
    * colors
    * images
    * printing using java.awt.PrintJob, java.awt.print.* and javax.print.*
    * audio beep

Headless mode setup

To set up the Headless mode you should set the appropriate system property using System.setProperty() method. Property name is "java.awt.headless" and possible values are "true" or "false". Note, that this property shoult be set before the toolkit is initialized with Toolkit.getDefaultToolkit() method.

To check up the availability of the Headless mode you should use GraphicsEnvironment.isHeadless() method. This method checks the "java.awt.headless" property: if it equals to "true", it is assumed that java.awt.HeadlessException will be thrown from all the methods that are dependent on a display, keyboard, or mouse. This method *does not check* hardware configuration of the system, so it is possible to run the application in the Headless mode on a usual desktop.

Example

All the capabilities described above are represented in the integrated HeadlessBasics example. There are some comments in the source code to better understang Headless mode basics.

Compile the source code using javac compiler. Download grapefruit.jpg image and put it to the directory where the HeadlessBasics class is located and then run the example with `java HeadlessBasics`. You can run it without any display, keyboard or mouse in the system, for example, using a remote console.

Artem Ananiev's Blog

Using JWebPane: common scenarios

1. HTML Rendering

2. Load event notifications

3. Navigation

4. Chrome

5. What next?

Introducing JWebPane component

java.awt.TrayIcon: isSupported vs isAvailable

Description of the problem

Introducing isAvailable method

Introducing a new property

Improved top-level icons support in Mustang

What's the problem?

More icons

Dialogs icons

When will this API be available?

java.awt.Desktop vs Runtime.exec()

Desktop API vs Runtime.exec()

The difference is...

Using JPopupMenu in TrayIcon

What's the problem?

Use JPopupMenu instead

Magic?

Headless toolkit basics

Toolkit

Headless mode

Headless mode setup

Example

Introducing `isAvailable` method