• Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL

Chapter 1. Widget Fundamentals > Events and Listeners

1.3. Events and Listeners

An 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 Listeners

Untyped 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().

addListener(int event, Listener listener) Adds the listener to the collection of listeners that will be notified when an event of the given type occurs. When the event occurs in the widget, the listener is notified by calling its handleEvent() method.

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]

[12] We can't think of any reason you would want to add the same listener multiple times but there is no restriction to stop you from doing this.

It is also possible to remove listeners using removeListener().

removeListener(int type, Listener listener) Removes the listener from the collection of listeners that will be notified when an event of the given type occurs.

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().

notifyListeners(int type, Event event) Sets the type of the event to the given type and calls Listener.handleEvent() for each listener in the collection of listeners.

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.1. Public Fields in Class Event That Are Applicable to All Untyped Events
displaythe Display on which the event occurred
widgetthe Widget that issued the event
typethe event type

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.

Table 1.2. Untyped Events
Event Type ConstantDescription
SWT.KeyDownA key was pressed
SWT.KeyUpA key was released
SWT.MouseDownA mouse button was pressed
SWT.MouseUpA mouse button was released
SWT.MouseMoveThe mouse was moved
SWT.MouseEnterThe mouse entered the client area of the control
SWT.MouseHoverThe mouse lingered over a control
SWT.MouseExitThe mouse exited the client area of the control
SWT.MouseDoubleClickA mouse button was pressed twice
SWT.PaintA control was asked to draw
SWT.MoveThe position of the control was changed
SWT.ResizeThe size of the client area of the control changed
SWT.DisposeThe widget was disposed
SWT.SelectionA selection occurred in the widget
SWT.DefaultSelectionThe default selection occurred in the widget
SWT.FocusInKeyboard focus was given to the control
SWT.FocusOutThe control lost keyboard focus
SWT.ExpandA tree item was expanded
SWT.CollapseA tree item was collapsed
SWT.IconifyThe shell was minimized
SWT.DeiconifyThe shell is no longer minimized
SWT.CloseThe shell is being closed
SWT.ShowThe widget is becoming visible
SWT.HideThe widget is being hidden
SWT.ModifyText has changed in the control
SWT.VerifyText is to be validated in the control
SWT.ActivateThe control is being activated
SWT.DeactivateThe control is being deactivated
SWT.HelpThe user requested help for the widget
SWT.DragDetectA drag-and-drop user action occurred
SWT.MenuDetectThe user requested a context menu
SWT.ArmThe menu item is drawn in the armed state
SWT.TraverseA keyboard navigation event occurred
SWT.HardKeyDownA hardware button was pressed (handhelds)
SWT.HardKeyUpA hardware button was released (handhelds)

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 Listeners

A 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().

addDisposeListener(DisposeListener listener) Adds the listener to the collection of listeners that will be notified when a widget is disposed. When the widget is disposed, the listener is notified by calling its widgetDisposed() method.

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.

[13] Adapter classes are provided for convenience and to adhere to JavaBeans listener conventions.

Typed listeners are removed using the corresponding remove method for the listener. For example, a listener for a dispose event is removed using removeDisposeListener().

removeDisposeListener(DisposeListener listener) Removes the listener from the collection of listeners that will be notified when the widget is disposed.

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.

Table 1.3. Typed Events
EventListenerMethodsUntyped Event
ControlEventControlListener (and ControlAdapter)controlMoved(ControlEvent) controlResized(ControlEvent)SWT.Move SWT.Resize
FocusEventFocusListener (and FocusAdapter)focusGained(FocusEvent) focusLost(FocusEvent)SWT.FocusIn SWT.FocusOut
KeyEventKeyListener (and KeyAdapter)keyPressed(KeyEvent) keyReleased(KeyEvent)SWT.KeyPressed SWT.KeyReleased
MenuEventMenuListener (and MenuAdapter)menuHidden(MenuEvent) menuShown(MenuEvent)SWT.Hide SWT.Show
MouseEventMouseListener (and MouseAdapter)mouseDoubleClick(MouseEvent)




MouseEventMouseTrackListener (and MouseTrackAdapter)mouseEnter(MouseEvent)




SelectionEventSelectionListener (and SelectionAdapter)widgetDefaultSelected(SelectionEvent) widgetSelected(SelectionEvent)SWT.DefaultSelection SWT.Selection
ShellEventShellListener (and ShellAdapter)shellActivated(ShellEvent)








TreeEventTreeListener (and TreeAdapter)treeCollapsed(TreeEvent) treeExpanded(TreeEvent)SWT.Collapse SWT.Expand

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.

[14] All of the typed listeners provided by the native widgets in SWT are found in the package org.eclipse.swt.events. When space is extremely limited, this package and all of the corresponding addXXXListener() and removeXXXListener() methods in org.eclipse.swt.widgets can be safely removed.

1.3.4. Widget Events

SWT.Dispose (DisposeEvent)

Table 1.4 shows the dispose events that are provided by SWT.

Table 1.4. Dispose Events
Untyped EventDescription
SWT.DisposeThe widget was disposed

Typed EventListenerMethods

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.

  • Creative Edge
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint