1.3 Events and Listeners - SWT: The Standard Widget Toolkit
|
< Day Day Up > |
|
1.3 Events and ListenersAn event is simply an indication that something interesting has happened. Events, such as "mouse down" and "key press," are issued when the user interacts with a widget through the mouse or keyboard. Event classes, used to represent the event, contain detailed information about what has happened. For example, when the user selects an item in a list, an event is created, capturing the fact that a "selection" occurred. The event is delivered to the application via a listener. A listener is an instance of a class that implements one or more agreed-upon methods whose signatures are captured by an interface. Listener methods always take an instance of an event class as an argument. When something interesting occurs in a widget, the listener method is invoked with an appropriate event. Most widgets track sequences of events and redraw based on them, sometimes issuing a higher-level event to indicate a state change. For example, a button may track "mouse press," "move," and "release" in order to issue a "selection" event when the mouse is released inside the button. Some widget methods generate events. For example, when you call setFocus() on a control, "focus" events are issued. The rules governing which methods cause events and which do not are largely historical, based on the behavior of the Windows and X/Motif operating systems. In order to be able to write portable applications, these rules have been standardized across platforms. SWT has two kinds of listeners: untyped and typed. 1.3.1 Untyped ListenersUntyped listeners provide a simple, generic, low-level mechanism to handle any type of event. There are only two Java types involved: a single generic interface called Listener and a single event class called Event. Untyped listeners are added using the method addListener().
The type argument specifies the event you are interested in receiving. To help distinguish them from all the other SWT constants, type arguments are mixed upper- and lowercase by convention. All other constants in SWT are uppercase. The following code fragment uses addListener() to add a listener for SWT.Dispose.
widget.addListener(SWT.Dispose, new Listener() {
public void handleEvent(Event event) {
// widget was disposed
}
});
When multiple listeners are added, they are called in the order they were added. This gives the first listener the opportunity to process the event and possibly filter the data before the remaining listeners are notified (see Event Filters in the chapter Display). Adding the same instance of a listener multiple times is supported, causing it to be invoked once for each time it was added.[12]
It is also possible to remove listeners using removeListener().
In order for a listener to be removed, you must supply the exact instance of the listener that was added. If the same listener instance is added multiple times, it must be removed the same number of times it was added to remove it from the listener collection completely. Generally speaking, removing listeners is unnecessary. Listeners are garbage collected when a control is disposed of, provided that there are no other references to the listener in the application program. Application code can send events using notifyListeners().
An important point to note is that notifyListeners() does not cause the corresponding operating system event to occur. For example, calling notifyListeners() with SWT.MouseDown on a button will not cause the button to appear to be pressed. Also, notifyListeners() does not ensure that the appropriate fields for the event have been correctly initialized for the given type of event. You can use notifyListeners() to invoke listeners that you define but it is probably easier simply to put the code in a helper method. Class Event has a number of fields that are applicable only for a subset of the event types. These fields are discussed as each type of event is described. Table 1.1 shows the fields that are valid for all event types.
Table 1.2 shows the type constants that describe all of the untyped events that SWT implements. More details are available in the descriptions of the individual widgets. If you are writing your own widget, you may want to use notifyListeners() to support the built-in untyped events in SWT since this allows your widget to behave like the native widgets with respect to the mapping between untyped and typed listeners. However, for events that are particular to your widget, you will also typically implement typed listeners. 1.3.2 Typed ListenersA typed listener follows the standard JavaBeans listener pattern. Typed listeners and their corresponding event classes are found in the package org.eclipse.swt.events. For example, to listen for a dispose event on a widget, application code would use addDisposeListener().
The following code fragment listens for a dispose event on a widget.
widget.addDisposeListener(new DisposeListener() {
public void widgetDisposed(DisposeEvent event) {
// widget was disposed
}
});
DisposeListener is an interface. If there is more than one method defined by the listener, SWT provides an adapter class that contains no-op implementations of the methods.[13] For example, the interface SelectionListener has two methods, widgetSelected() and widgetDefaultSelected(), that take SelectionEvents as arguments. As a result, the class SelectionAdapter is provided that provides no-op implementations for each method.
Typed listeners are removed using the corresponding remove method for the listener. For example, a listener for a dispose event is removed using removeDisposeListener().
Table 1.3 shows all of the typed events that SWT implements. These are described in more detail in the descriptions of the individual widgets. 1.3.3 Why Are There Two Listener Mechanisms?In early versions of SWT, there were only untyped listeners. After considerable discussion between the Eclipse implementers, the SWT user community, and the developers, it was decided to include a more "JavaBeans-like" listener mechanism. It was felt that this would ease the transition to SWT for developers who were already familiar with AWT/Swing. The untyped listeners remain as the implementation mechanism for event handling in SWT. The typed listeners are defined in terms of them. We recommend that SWT applications always be implemented in terms of the typed listener mechanism, although this is largely based on the more familiar pattern they represent. Because of the simplicity of the untyped mechanism and our closeness to the implementation, we tend to use it in many of the small examples we write. To see a clear example of the typed mechanism in action, take a look at the FileExplorer example in the Applications part of the book. Effectively, the trade-off between the two listener models is one of space versus ease of use and adherence to a standard pattern. Using untyped listeners, it is possible to minimize the number of classes and methods used to listen for events. The same listener can be used to listen for many different event types. For example, the following code fragment listens for dispose as well as mouse events.
Listener listener = new Listener() {
public void handleEvent(Event event) {
switch (event.type) {
case SWT.Dispose: break;
case SWT.MouseDown: break;
case SWT.MouseUp: break;
case SWT.MouseMove: break;
}
System.out.println("Something happened.");
}
};
shell.addListener(SWT.Dispose, listener);
shell.addListener(SWT.MouseDown, listener);
shell.addListener(SWT.MouseUp, listener);
shell.addListener(SWT.MouseMove, listener);
In practice, unless space usage is the overwhelming constraint, we expect that most programmers will use the typed listener mechanism.[14] Note that typed events have very specific listener APIs, whereas the untyped events have only handleEvent(). Using untyped events can lead to switch logic that is more complicated. Refer to Table 1.3 to see the mapping between typed and untyped events.
1.3.4 Widget EventsSWT.Dispose (DisposeEvent)Table 1.4 shows the dispose events that are provided by SWT.
The SWT.Dispose event (typed event DisposeEvent) is sent when a widget is disposed of. Dispose events contain meaningful values in only the display, widget, and type fields. | ||||||||||||||||||||||||
|
|
< Day Day Up > |
|