bundles/org.eclipse.swt.win32.win32.x86_64/src/org/eclipse/swt/events/TraverseEvent.java

   1 /*******************************************************************************
   2  * Copyright (c) 2000, 2011 IBM Corporation and others.
   3  *
   4  * This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License 2.0
   6  * which accompanies this distribution, and is available at
   7  * https://www.eclipse.org/legal/epl-2.0/
   8  *
   9  * SPDX-License-Identifier: EPL-2.0
  10  *
  11  * Contributors:
  12  *     IBM Corporation - initial API and implementation
  13  *******************************************************************************/
  14 package org.eclipse.swt.events;
  15
  16
  17 import org.eclipse.swt.widgets.*;
  18
  19 /**
  20  * Instances of this class are sent as a result of
  21  * widget traversal actions.
  22  * <p>
  23  * The traversal event allows fine control over keyboard traversal
  24  * in a control both to implement traversal and override the default
  25  * traversal behavior defined by the system.  This is achieved using
  26  * two fields, <code>detail</code> and <code>doit</code>.
  27  * </p><p>
  28  * When a control is traversed, a traverse event is sent.  The detail
  29  * describes the type of traversal and the doit field indicates the default
  30  * behavior of the system.  For example, when a right arrow key is pressed
  31  * in a text control, the detail field is <code>TRAVERSE_ARROW_NEXT</code>
  32  * and the doit field is <code>false</code>, indicating that the system
  33  * will not traverse to the next tab item and the arrow key will be
  34  * delivered to the text control.  If the same key is pressed in a radio
  35  * button, the doit field will be <code>true</code>, indicating that
  36  * traversal is to proceed to the next tab item, possibly another radio
  37  * button in the group and that the arrow key is not to be delivered
  38  * to the radio button.
  39  * </p><p>
  40  * How can the traversal event be used to implement traversal?
  41  * When a tab key is pressed in a canvas, the detail field will be
  42  * <code>TRAVERSE_TAB_NEXT</code> and the doit field will be
  43  * <code>false</code>.  The default behavior of the system is to
  44  * provide no traversal for canvas controls.  This means that by
  45  * default in a canvas, a key listener will see every key that the
  46  * user types, including traversal keys.  To understand why this
  47  * is so, it is important to understand that only the widget implementor
  48  * can decide which traversal is appropriate for the widget.  Returning
  49  * to the <code>TRAVERSE_TAB_NEXT</code> example, a text widget implemented
  50  * by a canvas would typically want to use the tab key to insert a
  51  * tab character into the widget.  A list widget implementation, on the
  52  * other hand, would like the system default traversal behavior.  Using
  53  * only the doit flag, both implementations are possible.  The text widget
  54  * implementor sets doit to <code>false</code>, ensuring that the system
  55  * will not traverse and that the tab key will be delivered to key listeners.
  56  * The list widget implementor sets doit to <code>true</code>, indicating
  57  * that the system should perform tab traversal and that the key should not
  58  * be delivered to the list widget.
  59  * </p><p>
  60  * How can the traversal event be used to override system traversal?
  61  * When the return key is pressed in a single line text control, the
  62  * detail field is <code>TRAVERSE_RETURN</code> and the doit field
  63  * is <code>true</code>.  This means that the return key will be processed
  64  * by the default button, not the text widget.  If the text widget has
  65  * a default selection listener, it will not run because the return key
  66  * will be processed by the default button.  Imagine that the text control
  67  * is being used as an in-place editor and return is used to dispose the
  68  * widget.  Setting doit to <code>false</code> will stop the system from
  69  * activating the default button but the key will be delivered to the text
  70  * control, running the key and selection listeners for the text.  How
  71  * can <code>TRAVERSE_RETURN</code> be implemented so that the default button
  72  * will not be activated and the text widget will not see the return key?
  73  * This is achieved by setting doit to <code>true</code>, and the detail
  74  * to <code>TRAVERSE_NONE</code>.
  75  * </p><p>
  76  * Note: A widget implementor will typically implement traversal using
  77  * only the doit flag to either enable or disable system traversal.
  78  * </p>
  79  *
  80  * @see TraverseListener
  81  * @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
  82  */
  83
  84 public final class TraverseEvent extends KeyEvent {
  85
  86         /**
  87          * The traversal type.
  88          * <ul>
  89          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_NONE}</li>
  90          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_ESCAPE}</li>
  91          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_RETURN}</li>
  92          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_TAB_NEXT}</li>
  93          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_TAB_PREVIOUS}</li>
  94          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_ARROW_NEXT}</li>
  95          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_ARROW_PREVIOUS}</li>
  96          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_MNEMONIC}</li>
  97          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_PAGE_NEXT}</li>
  98          * <li>{@link org.eclipse.swt.SWT#TRAVERSE_PAGE_PREVIOUS}</li>
  99          * </ul>
 100          *
 101          * Setting this field will change the type of traversal.
 102          * For example, setting the detail to <code>TRAVERSE_NONE</code>
 103          * causes no traversal action to be taken.
 104          *
 105          * When used in conjunction with the <code>doit</code> field, the
 106          * traversal detail field can be useful when overriding the default
 107          * traversal mechanism for a control. For example, setting the doit
 108          * field to <code>false</code> will cancel the operation and allow
 109          * the traversal key stroke to be delivered to the control. Setting
 110          * the doit field to <code>true</code> indicates that the traversal
 111          * described by the detail field is to be performed.
 112          */
 113         public int detail;
 114
 115         static final long serialVersionUID = 3257565105301239349L;
 116
 117 /**
 118  * Constructs a new instance of this class based on the
 119  * information in the given untyped event.
 120  *
 121  * @param e the untyped event containing the information
 122  */
 123 public TraverseEvent(Event e) {
 124         super(e);
 125         this.detail = e.detail;
 126 }
 127
 128 /**
 129  * Returns a string containing a concise, human-readable
 130  * description of the receiver.
 131  *
 132  * @return a string representation of the event
 133  */
 134 @Override
 135 public String toString() {
 136         String string = super.toString ();
 137         return string.substring (0, string.length() - 1) // remove trailing '}'
 138                 + " detail=" + detail
 139                 + "}";
 140 }
 141 }