1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
/*******************************************************************************
* Copyright (c) 2000, 2008 IBM Corporation 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:
* IBM Corporation - initial API and implementation
*******************************************************************************/
package org.eclipse.swt.events;
import org.eclipse.swt.widgets.*;
/**
* Instances of this class are sent as a result of
* widget traversal actions.
* <p>
* 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, <code>detail</code> and <code>doit</code>.
* </p><p>
* 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 <code>TRAVERSE_ARROW_NEXT</code>
* and the doit field is <code>false</code>, 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 <code>true</code>, 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.
* </p><p>
* How can the traversal event be used to implement traversal?
* When a tab key is pressed in a canvas, the detail field will be
* <code>TRAVERSE_TAB_NEXT</code> and the doit field will be
* <code>false</code>. 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 <code>TRAVERSE_TAB_NEXT</code> 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 <code>false</code>, 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 <code>true</code>, indicating
* that the system should perform tab traversal and that the key should not
* be delivered to the list widget.
* </p><p>
* 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 <code>TRAVERSE_RETURN</code> and the doit field
* is <code>true</code>. 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 <code>false</code> 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 <code>TRAVERSE_RETURN</code> 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 <code>true</code>, and the detail
* to <code>TRAVERSE_NONE</code>.
* </p><p>
* Note: A widget implementor will typically implement traversal using
* only the doit flag to either enable or disable system traversal.
* </p>
*
* @see TraverseListener
* @see <a href="http://www.eclipse.org/swt/">Sample code and further information</a>
*/
public final class TraverseEvent extends KeyEvent {
/**
* The traversal type.
* <p><ul>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_NONE}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_ESCAPE}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_RETURN}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_TAB_NEXT}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_TAB_PREVIOUS}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_ARROW_NEXT}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_ARROW_PREVIOUS}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_MNEMONIC}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_PAGE_NEXT}</li>
* <li>{@link org.eclipse.swt.SWT#TRAVERSE_PAGE_PREVIOUS}</li>
* </ul></p>
*
* Setting this field will change the type of traversal.
* For example, setting the detail to <code>TRAVERSE_NONE</code>
* causes no traversal action to be taken.
*
* When used in conjunction with the <code>doit</code> field, the
* traversal detail field can be useful when overriding the default
* traversal mechanism for a control. For example, setting the doit
* field to <code>false</code> will cancel the operation and allow
* the traversal key stroke to be delivered to the control. Setting
* the doit field to <code>true</code> indicates that the traversal
* described by the detail field is to be performed.
*/
public int detail;
static final long serialVersionUID = 3257565105301239349L;
/**
* 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);
this.detail = e.detail;
}
/**
* Returns a string containing a concise, human-readable
* description of the receiver.
*
* @return a string representation of the event
*/
public String toString() {
String string = super.toString ();
return string.substring (0, string.length() - 1) // remove trailing '}'
+ " detail=" + detail
+ "}";
}
}
|
