org.eclipse.swt.events.TraverseEvent Maven / Gradle / Ivy
/*******************************************************************************
* Copyright (c) 2008, 2012 Innoopract Informationssysteme GmbH and others.
* All rights reserved. This program and the accompanying materials
* are made available under the terms of the Eclipse Public License v1.0
* which accompanies this distribution, and is available at
* http://www.eclipse.org/legal/epl-v10.html
*
* Contributors:
* Innoopract Informationssysteme GmbH - initial API and implementation
* EclipseSource - ongoing development
******************************************************************************/
package org.eclipse.swt.events;
import org.eclipse.swt.widgets.Event;
/**
* 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.
*
*
* @see TraverseListener
*
* @since 1.2
*/
public final class TraverseEvent extends KeyEvent {
private static final long serialVersionUID = 1L;
/**
* The traversal type.
*
*
* - {@link org.eclipse.swt.SWT#TRAVERSE_NONE}
* - {@link org.eclipse.swt.SWT#TRAVERSE_ESCAPE}
* - {@link org.eclipse.swt.SWT#TRAVERSE_RETURN}
* - {@link org.eclipse.swt.SWT#TRAVERSE_TAB_NEXT}
* - {@link org.eclipse.swt.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.
*/
@SuppressWarnings("javadoc")
public int detail;
/**
* Constructs a new instance of this class based on the information in the
* given untyped event.
*
* @param e the untyped event containing the information
*/
public TraverseEvent( Event e ) {
super( e );
detail = e.detail;
}
/**
* Returns a string containing a concise, human-readable description of the
* receiver.
*
* @return a string representation of the event
*/
@Override
public String toString() {
String string = super.toString();
return string.substring( 0, string.length() - 1 ) // remove trailing '}'
+ " detail="
+ detail
+ "}";
}
}