qflib 0.98.0

de.qfs.lib.gui
Class EventQueue

java.lang.Object
  |
  +--java.awt.EventQueue
        |
        +--de.qfs.lib.gui.EventQueue

public class EventQueue
extends java.awt.EventQueue

This EventQueue enables exception handling for exceptions raised in the AWT event loop thread. Since version 0.98.0 this works even with JDK 1.1.

Additionally, a workaround is provided for a problem with some JDKs on Motif systems (linux for example), where no KEY_PRESSED and KEY_TYPED events are generated for the Shift_Tab combination under certain circumstances. This hack generates the neccessary events so tab traversal works both forwards and backwards.

New in qflib 0.98.0 is another hack needed for some Motif systems like the IBM JDKs on linux: They generate Alt-Key events with the modifier bits for ALT and META set, which causes keyboard access of menus to fail (among other Alt-... bindings). If you enable the meta hack, the META modifier will be removed from these key events.

Yet another hack is needed for the blackdown JDK 1.3 on linux: It generates a KEY_TYPED event for the delete key, causing weird symbols to appear in text components. These events are filtered if the delete hack is enabled.

Different ways are used to install an EventQueue as the system event queue for JDKs 1.1 and 1.2. With JDK 1.1, make sure that the class is in your CLASSPATH and add the line
AWT.EventQueueClass=de.qfs.lib.gui.EventQueue
to the file awt.properties in the lib directory of your JDK. In any case you must call install.

Warning: If you use this EventQueue with JDK 1.1 and install it, EventQueue.getNextEvent and EventQueue.peekEvent() will return WrapperEvents instead of the normal events and EventQueue.peekEvent(int) will cease to work. If you want to use these methods, either check for WrapperEvents and call WrapperEvent.getWrappedEvent to access the original event (but dispatch the event through the WrapperEvent's dispatch method), or temporarily disable the EventQueue with uninstall.

Warning: If you use this EventQueue with JDK 1.2 or above, you must use the EventQueue returned by the instance method instead of Toolkit.getSystemEventQueue to poll events with EventQueue.getNextEvent etc. You can EventQueue.postEvent to the system event queue as usual.

Version:
$Revision: 1.12 $
Author:
Gregor Schmid

Inner Class Summary
 class EventQueue.WrapperEvent
          ActiveEvent that wraps itself around an AWTEvent and dispatches it in JDK 1.2 style through the EventQueue's dispatchEvent method.
 
Field Summary
protected  boolean installed
          Whether the queue is currently installed.
protected static EventQueue theQueue
          The installed Queue or null.
static int WRAPPER_ID
          Id for WrapperEvents.
 
Constructor Summary
EventQueue()
          Create a new EventQueue.
 
Method Summary
 void dispatchEvent(java.awt.AWTEvent event)
          Dispatch an event.
static boolean install()
          Install the EventQueue instance as the System EventQueue.
static java.awt.EventQueue instance()
          Get the EventQueue instance, if it has been installed.
static boolean isDeleteHackEnabled()
          Query whether the delete hack is enabled.
static boolean isInstalled()
          Check, whether the EventQueue has been installed.
static boolean isMetaHackEnabled()
          Query whether the meta hack is enabled.
static boolean isTabHackEnabled()
          Query whether the tab hack is enabled.
 void pop()
          Public version of pop.
static void setDeleteHackEnabled(boolean enabled)
          Set whether the delete hack should be enabled.
static void setExceptionHandler(ExceptionHandler handler)
          Set a handler for Exceptions that occur in the AWT event dispatch thread.
static void setMetaHackEnabled(boolean enabled)
          Set whether the meta hack should be enabled.
static void setTabHackEnabled(boolean enabled)
          Set whether the tab hack should be enabled.
protected  boolean tabHack(java.awt.AWTEvent e)
          At least on Motif systems (linux for example), no KEY_PRESSED and KEY_TYPED events are generated for the Shift_Tab combination, but only under certain circumstances.
static void uninstall()
          Uninstall the EventQueue.
 
Methods inherited from class java.awt.EventQueue
getNextEvent, invokeAndWait, invokeLater, isDispatchThread, peekEvent, peekEvent, postEvent, push
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

WRAPPER_ID

public static final int WRAPPER_ID
Id for WrapperEvents.

theQueue

protected static EventQueue theQueue
The installed Queue or null.

installed

protected boolean installed
Whether the queue is currently installed.
Constructor Detail

EventQueue

public EventQueue()
Create a new EventQueue. This constructor must be public so the AWT Toolkit can create an EventQueue. It should not be called directly.
Method Detail

instance

public static java.awt.EventQueue instance()
Get the EventQueue instance, if it has been installed. Otherwise get the SystemEventQueue.
Returns:
The EventQueue instance.

install

public static boolean install()
Install the EventQueue instance as the System EventQueue. With JDK 1.1 additional support is needed (see class doc).
Returns:
True, if the EventQueue has been installed.

uninstall

public static void uninstall()
Uninstall the EventQueue. With JDK 1.2 the EventQueue is truly uninstalled. With JDK 1.1 this is not possible, so the EventQueue acts as if it weren't there.

isInstalled

public static boolean isInstalled()
Check, whether the EventQueue has been installed.
Returns:
True, if the EventQueue is installed.

dispatchEvent

public void dispatchEvent(java.awt.AWTEvent event)
Dispatch an event. This is the method of choice to access events on the event loop for JDK 1.2. This method is called from inside the event loop thread, so exception ahndling is possible.

This method is public for the sake of SwingUtil.withEvents. Don't use it unless you really know what you are doing.

Overrides:
dispatchEvent in class java.awt.EventQueue
Parameters:
event - The event to dispatch.

pop

public void pop()
Public version of pop.
Overrides:
pop in class java.awt.EventQueue

setExceptionHandler

public static void setExceptionHandler(ExceptionHandler handler)
Set a handler for Exceptions that occur in the AWT event dispatch thread. Only works with JDK 1.2 and only if the EventQueue is installed.
Parameters:
handler - The ExceptionHandler to set.

isTabHackEnabled

public static final boolean isTabHackEnabled()
Query whether the tab hack is enabled.
Returns:
True if it is enabled.

setTabHackEnabled

public static final void setTabHackEnabled(boolean enabled)
Set whether the tab hack should be enabled.
Parameters:
enabled - True to enable the hack.

isMetaHackEnabled

public static final boolean isMetaHackEnabled()
Query whether the meta hack is enabled.
Returns:
True if it is enabled.
Since:
0.98.0

setMetaHackEnabled

public static final void setMetaHackEnabled(boolean enabled)
Set whether the meta hack should be enabled.
Parameters:
enabled - True to enable the hack.
Since:
0.98.0

isDeleteHackEnabled

public static final boolean isDeleteHackEnabled()
Query whether the delete hack is enabled.
Returns:
True if it is enabled.
Since:
0.98.0

setDeleteHackEnabled

public static final void setDeleteHackEnabled(boolean enabled)
Set whether the delete hack should be enabled.
Parameters:
enabled - True to enable the hack.
Since:
0.98.0

tabHack

protected boolean tabHack(java.awt.AWTEvent e)
At least on Motif systems (linux for example), no KEY_PRESSED and KEY_TYPED events are generated for the Shift_Tab combination, but only under certain circumstances. This hack generates the neccessary events when it comes across a KEY_RELEASED event without a preceding KEY_PRESSED event, so tab traversal works both ways again.
Parameters:
e - The event to check.
Returns:
True, if the hack was executed. In this case the original event should be ignored, since it will be reposted after the KEY_PRESSED and KEY_TYPED events.

qflib 0.98.0