org.eclipse.swt.events
Class TraverseEvent

java.lang.Object
  Event
      org.eclipse.swt.events.TypedEvent
          org.eclipse.swt.events.KeyEvent
              org.eclipse.swt.events.TraverseEvent

public final class TraverseEvent
extends KeyEvent

Instances of this class are sent as a result of widget traversal actions.

The traversal event allows fine control over keyboard traversal in a control both to implement traversal and override the default traversal behavior defined by the system. This is achieved using two fields, detail and doit.

When a control is traversed, a traverse event is sent. The detail describes the type of traversal and the doit field indicates the default behavior of the system. For example, when a right arrow key is pressed in a text control, the detail field is TRAVERSE_ARROW_NEXT and the doit field is false, indicating that the system will not traverse to the next tab item and the arrow key will be delivered to the text control. If the same key is pressed in a radio button, the doit field will be true, indicating that traversal is to proceed to the next tab item, possibly another radio button in the group and that the arrow key is not to be delivered to the radio button.

How can the traversal event be used to implement traversal? When a tab key is pressed in a canvas, the detail field will be TRAVERSE_TAB_NEXT and the doit field will be false. The default behavior of the system is to provide no traversal for canvas controls. This means that by default in a canvas, a key listener will see every key that the user types, including traversal keys. To understand why this is so, it is important to understand that only the widget implementor can decide which traversal is appropriate for the widget. Returning to the TRAVERSE_TAB_NEXT example, a text widget implemented by a canvas would typically want to use the tab key to insert a tab character into the widget. A list widget implementation, on the other hand, would like the system default traversal behavior. Using only the doit flag, both implementations are possible. The text widget implementor sets doit to false, ensuring that the system will not traverse and that the tab key will be delivered to key listeners. The list widget implementor sets doit to true, indicating that the system should perform tab traversal and that the key should not be delivered to the list widget.

How can the traversal event be used to override system traversal? When the return key is pressed in a single line text control, the detail field is TRAVERSE_RETURN and the doit field is true. This means that the return key will be processed by the default button, not the text widget. If the text widget has a default selection listener, it will not run because the return key will be processed by the default button. Imagine that the text control is being used as an in-place editor and return is used to dispose the widget. Setting doit to false will stop the system from activating the default button but the key will be delivered to the text control, running the key and selection listeners for the text. How can TRAVERSE_RETURN be implemented so that the default button will not be activated and the text widget will not see the return key? This is achieved by setting doit to true, and the detail to TRAVERSE_NONE.

Note: A widget implementor will typically implement traversal using only the doit flag to either enable or disable system traversal.

IMPORTANT: All public static members of this class are not part of the RWT public API. They are marked public only so that they can be shared within the packages provided by RWT. They should never be accessed from application code.

Since:

1.2

See Also:

TraverseListener

Field Summary

int	detail The traversal type.
static int	KEY_TRAVERSED

Fields inherited from class org.eclipse.swt.events.KeyEvent

character, doit, KEY_PRESSED, KEY_RELEASED, keyCode, stateMask

Fields inherited from class org.eclipse.swt.events.TypedEvent

data, display, widget

Constructor Summary

TraverseEvent(Control source)

TraverseEvent(Event e)
Constructs a new instance of this class based on the information in the given untyped event.

Method Summary

static void	addListener(Adaptable adaptable, TraverseListener listener)
protected boolean	allowProcessing()
protected void	dispatchToObserver(java.lang.Object listener)
protected java.lang.Class	getListenerType()
static boolean	hasListener(Adaptable adaptable)
static void	removeListener(Adaptable adaptable, TraverseListener listener)
java.lang.String	toString() Returns a string containing a concise, human-readable description of the receiver.

Methods inherited from class org.eclipse.swt.events.KeyEvent

addListener, removeListener

Methods inherited from class org.eclipse.swt.events.TypedEvent

executeNext, getSource, processEvent

Methods inherited from class java.lang.Object

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

Field Detail

KEY_TRAVERSED

public static final int KEY_TRAVERSED

See Also:

Constant Field Values

detail

public int detail

The traversal type.

• SWT.TRAVERSE_NONE
• SWT.TRAVERSE_ESCAPE
• SWT.TRAVERSE_RETURN
• SWT.TRAVERSE_TAB_NEXT
• SWT.TRAVERSE_TAB_PREVIOUS

Setting this field will change the type of traversal. For example, setting the detail to TRAVERSE_NONE causes no traversal action to be taken. When used in conjunction with the doit field, the traversal detail field can be useful when overriding the default traversal mechanism for a control. For example, setting the doit field to false will cancel the operation and allow the traversal key stroke to be delivered to the control. Setting the doit field to true indicates that the traversal described by the detail field is to be performed.

Constructor Detail

TraverseEvent

public TraverseEvent(Event e)

Constructs a new instance of this class based on the information in the given untyped event.

Parameters:

e - the untyped event containing the information

TraverseEvent

public TraverseEvent(Control source)

Method Detail

toString

public java.lang.String toString()

Returns a string containing a concise, human-readable description of the receiver.

Overrides:

toString in class KeyEvent

Returns:

a string representation of the event

dispatchToObserver

protected void dispatchToObserver(java.lang.Object listener)

Overrides:

dispatchToObserver in class KeyEvent

getListenerType

protected java.lang.Class getListenerType()

Overrides:

getListenerType in class KeyEvent

allowProcessing

protected boolean allowProcessing()

Overrides:

allowProcessing in class KeyEvent

addListener

public static void addListener(Adaptable adaptable,
                               TraverseListener listener)

removeListener

public static void removeListener(Adaptable adaptable,
                                  TraverseListener listener)

hasListener

public static boolean hasListener(Adaptable adaptable)