swingintegration.example
Class AwtEnvironment

java.lang.Object
  swingintegration.example.AwtEnvironment

public final class AwtEnvironment
extends Object

An environment to enable the proper display of AWT/Swing windows within a SWT or RCP application. This class extends the base Eclipse SWT/AWT integration support by

• Using the platform-specific system Look and Feel.
• Ensuring AWT modal dialogs are modal across the SWT application.
• Working around various AWT/Swing bugs

This class is most helpful to applications which create new AWT/Swing windows (e.g. dialogs) rather than those which embed AWT/Swing components in SWT windows. For support specific to embedding AWT/Swing components see EmbeddedSwingComposite.

There is at most one instance of this class per SWT Display. In almost all applications this means that there is exactly one instance for the entire application. In fact, the current implementation always limits the number of instances to exactly one.

An instance of this class can be obtained with the static getInstance(Display) method.

Method Summary

Frame	createDialogParentFrame() Creates an AWT frame suitable as a parent for AWT/Swing dialogs.
Frame	createDialogParentFrame(Shell parent) Creates an AWT frame suitable as a parent for AWT/Swing dialogs.
static AwtEnvironment	getInstance(Display display) Returns the single instance of AwtEnvironment for the given display.
void	invokeAndBlockSwt(Runnable runnable) Invokes the given runnable in the AWT event thread while blocking user input on the SWT event thread.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getInstance

public static AwtEnvironment getInstance(Display display)

Returns the single instance of AwtEnvironment for the given display. On the first call to this method, the necessary initialization to allow AWT/Swing code to run properly within an Eclipse application is done. This initialization includes setting the approprite look and feel and registering the necessary listeners to ensure proper behavior of modal dialogs.

The first call to this method must occur before any AWT/Swing APIs are called.

The current implementation limits the number of instances of AwtEnvironment to one. If this method is called with a display different to one used on a previous call, UnsupportedOperationException is thrown.

Parameters:

display - the non-null SWT display

Returns:

the AWT environment

Throws:

IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the display is null

UnsupportedOperationException - - on attempt to use multiple displays.

invokeAndBlockSwt

public void invokeAndBlockSwt(Runnable runnable)

Invokes the given runnable in the AWT event thread while blocking user input on the SWT event thread. The SWT event thread will remain blocked until the runnable task completes, at which point this method will return.

This method is useful for displayng modal AWT/Swing dialogs from the SWT event thread. The modal AWT/Swing dialog will always block input across the whole application, but not until it appears. By calling this method, it is guaranteed that SWT input is blocked immediately, even before the AWT/Swing dialog appears.

To avoid unnecessary flicker, AWT/Swing dialogs should have their parent set to a frame returned by createDialogParentFrame().

This method must be called from the SWT event thread.

Parameters:

runnable - the code to schedule on the AWT event thread

Throws:

IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the runnable is null

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the SWT event thread

createDialogParentFrame

public Frame createDialogParentFrame()

Creates an AWT frame suitable as a parent for AWT/Swing dialogs.

This method must be called from the SWT event thread. There must be an active shell associated with the environment's display.

The created frame is a non-visible child of the active shell and will be disposed when that shell is disposed.

See createDialogParentFrame(Shell) for more details.

Returns:

a Frame to be used for parenting dialogs

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the SWT event thread

IllegalStateException - if the current display has no shells

createDialogParentFrame

public Frame createDialogParentFrame(Shell parent)

Creates an AWT frame suitable as a parent for AWT/Swing dialogs.

This method must be called from the SWT event thread. There must be an active shell associated with the environment's display.

The created frame is a non-visible child of the given shell and will be disposed when that shell is disposed.

This method is useful for creating a frame to parent any AWT/Swing dialogs created for use inside a SWT application. A modal AWT/Swing dialogs will flicker less if its parent is set to the returned frame rather than to null or to an independently created Frame.

Returns:

a Frame to be used for parenting dialogs

Throws:

SWTException -

• ERROR_THREAD_INVALID_ACCESS - if not called from the SWT event thread

IllegalStateException - if the current display has no shells