Introduction

I’m a guy who can’t use a tool until I have some model of how it works under the hood. If you are that way, you will like this essay. If you are the kind of programmer who simply wants to use the tool without any interest of how it works inside, all you need pay attention to in this essay is how EventListeners work.

Overview

• A way one object can call a method in another, but with a delay. Instead of doing the work right away, the work is postponed by putting a note to do it later into a queue, so that the caller can get on with more important work.
• A flexible way of deciding at run time precisely which objects should have their methods called when something interesting happens.
• A way for letting the callee decide when it wants to be called rather than leaving that decision totally up to the caller.
• A way of scheduling work for other Threads to do when they have time.

1. A callback delegate mechanisms so that Sun-written Components can call code you write when something interesting happens via the various listener interfaces. The listener mechanism is more complex than your usual callback. The callee, remembers multiple callers, then calls them back later, asynchronously when something interesting happens.
2. A queuing mechanism to procrastinate work. Basically it is a to-do list. High priority work gets done first. If the system gets behind, it can skip some of the validates or repaints since the later ones will cover the earlier ones. The queue mechanism also co-ordinates many Threads all making changes to the screen at once. They put their requests into a queue and a single Thread does all the work without any worries of other Threads interfering.
3. It is also an Event delivery mechanism so that an Event (notification of something interesting happening) can be easily forwarded to other possibly interested parties.

The new Event model gives you three places to hook in your code to process Events.

1. via listeners. This is by far the most common way and the easiest to set up. The listener can be any object, e.g. the enclosing frame, the component itself, a non-GUI code object, a "mom" object to mother a set of components. A given listener can service several sources, and a given source can notify several target listeners. listener methods have names like actionPerformed, windowClosed, mouseMoved. Listeners are often implemented with Adapter classes so you don’t have to write dummy methods for Events you are not interested in. Adapter classes have names like: java.awt.event.FocusAdapter, KeyAdapter and WindowAdapter. Note, there is no such thing as ActionAdapter since it has only one method. Often you use inner classes or anonymous classes to handle fielding Events by extending an adapter class. Be very careful in extending adapter classes to get your method names and signatures exactly right. Otherwise you won’t override the corresponding dummy method, and your code won’t ever be executed, leaving you wondering where all the Events went.
2. via processEvent which receives all raw Events for the component. It does not see Events coming in via listeners. If you override it, be sure to call super.processEvent to ensure all the finer Event handlers, like processKeyEvent, ProcessActionEvent etc. also get called and the listeners alerted. If you attempt to restrict the Events coming to processEvent with enableEvents(mask), if there are listeners registered for Events not in the mask, those Event classes will arrive anyway.
3. via processXXXX(SomeEventClass e), e.g. processActionEvent, processItemEvent. Every raw Event for the component of that class comes through here. It does not see Events coming in via listeners. Be sure to call super.processXXXX to ensure the listeners are alerted.

The Cast Of Players

The AWT informs the list of registered listeners that an Event has occurred by calling the generic source.processEvent which in turn calls the more specific Event handler: source.processActionEvent, processAdjustmentEvent, processComponentEvent, processContainerEvent, processItemEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, firePropertyChange, processTextEvent, fireVetoableChange, processWindowEvent… These routines would in turn use the AWTEventMulticaster to inform all the listeners and invoke their actionPerformed, keyPressed, windowOpened etc. methods in turn. These processXXX routines typically work by calling the relevant dispatching routines on the listener targets. It is unlikely you will ever deal with these methods directly.

Your listener object must implement one or more interfaces such as: ActionListener, ComponentListener, ContainerListener, FocusListener, KeyListener, ItemListener, MouseListener, MouseMotionListener, TextListener, WindowListener…

The easiest way to implement those interfaces is to extend one of the related adapter classes. The adapter classes provide dummy methods to deal with the subcategories of Events that are of no interest to you. ComponentAdapter, ContainerAdapter, FocusAdapter, KeyListener, ItemAdapter, MouseAdapter, MouseMotionAdapter, TextAdapter, WindowAdapter…

The Event is dispatched to each target Listener by invoking its listening method. These have names like: target.actionPerformed, adjustmentValueChanged, componentHidden, componentMoved, componentResized, componentShown, componentAdded, componentRemoved, focusGained, focusLost, itemStateChanged, keyPressed, keyReleased, keyTyped, mouseClicked, mouseEntered, mouseExited, mousePressed, mouseReleased, textValueChanged, windowActivated, windowClosed, windowClosing, windowDeactivated, windowDecionified, WindowIconified, windowOpened… You need to write custom versions of these routines.

If there is a listener for an Event type registered, then Events from the GUI for that Event type will be delivered to that component’s processEvent. The component can control which additional types are delivered to processEvent by calling enableEvents with a mask. This way events that no one is interested in are not even delivered to processEvent. It is unlikely you will be directly involved with enableEvents.

A key point to understand is that a component has two kinds of acceptor routines for Events.

1. The generic processEvent routine primarily accepts Events indirectly coming from the native GUI. Application programmers do not normally use these methods.
2. The listener methods, e.g. actionPerformed, accept Events from other components. This is the main tool for application programmers to deal with Events. Component writers can also use the EventListener interface by registering a custom component as a listener to Events arising in itself.

The Life Cycle Of An Event

Where do Events Come From Daddy?

Toolkit.getDefaultToolkit().getSystemEventQueue().postEvent( Event e );

Most Events arise in the native GUI. They can enter the Java system in one of two ways:

1. Notification of interesting happenings in the GUI arrive as a single stream of messages mentioning native GUI components. This is the traditional native GUI Event loop handled by hidden code, that calls getMessage() in a loop. The AWT uses a hash table to convert references to native GUI components into the corresponding Java components and peers, and composes corresponding Java Events and enqueues them in the SystemEventQueue.
2. Java peer components generate Events based on information they glean from the native GUI. These too are enqueued in the SystemEventQueue.

Where is the Event Loop?

The loop that processes Events does not even start until your main program has finished executing!! This Event loop code is not visible to the application programmer.

You might naively imagine there is some sort of mail delivery service that delivers Events to their destinations. It is much simpler than that. The Event object contains a reference to the target object. To deliver/dispatch the Event, all the system has to do is call a method on that reference. It is a little more complicated than that since an Event handler may call a chain of Event handlers. The target object is confusingly called the source. It makes sense if you consider that Events usually come back to the same object that generated them. From the point of view of listeners, the Events appear to come from these source objects.

You can think of Events as a way of enqueing work to be done later, usually by other objects.

Creation

1. The native GUI indirectly notifies the Java Button peer object which creates a new Event using the ActionEvent constructor.
2. The GUI creates a native format message that a button has been clicked. Hidden code in the AWT reads this stream of messages and translates this one into a new Event using the ActionEvent constructor. It has a Hashtable to convert references to native peer components to the corresponding Java components.

4. event source

   A Java component closely associated with this event, namely myButton. At first this field acts as the destination for the Event. Later it informs listeners where the Event came from.

   event id

   the type of event, in this case ActionEvent.ACTION_PERFORMED.

   event command

   the command string for this action event. In this case it would be the string "OK".

   event modifiers

   the modifiers held down during this click, e.g. CTRL_MASK if the Ctrl key is held down

Enqueuing

EventQueue q = Toolkit.getDefaultToolkit().getSystemEventQueue();

q.postEvent( e );

Dispatching

Having said that, this single-thread behaviour is not part of the specification. There are some JVMs where you have several threads processing Events simultaneously.

It looks at the source field in the Event object, and delivers the Event to that source object.

First it checks the java.awt.Component.eventMask to be sure the myButton component is willing to accept that flavour of Event.

The button could conceivably have used java.awt.Component.disableEvents to filter out Events such as ours. disableEvents takes bit masks for groups of Events such as java.awt.AWTEvent.MOUSE_MOTION_EVENT_MASK. You cannot feed it individual Events such as java.awt.event.MouseEvent.MOUSE_ENTERED, because these constants are not in bit mask form. One my main bitches about Java is this bit map / enumeration ambiguity.

It also checks if there are listeners for our type of Event. If there are, even if our Event type is blocked, our Event will still be delivered.

It delivers the Event to the button component by calling myButton’s generic processEvent Event handler:

myButton.processEvent( e );

e.getSource().processEvent( e );

Classification

Notifying Listeners

Raw Events arrive via processEvent. They are classified and redirected to more specialised Event processors like processActionEvent.

processActionEvent can further classify the incoming Events and can do whatever special processing it wants. Then it notifies any listeners, one after the other. (If you override processActionEvent, make sure you call super.processActionEvent to ensure the listeners are notified.)

Each listener effectively gets a fresh cloned copy of the original Event. Unfortunately, this wastes cpu cycles and creates a ton of run time garbage. The intent is to make Events effectively read-only and to render harmless any malicious component that stored a reference to an Event. Once an Event enters Component.processKeyEvent, it isn’t replicated anymore so presumably some of its fields could be modified and used for communication. Ideally Event objects would be read-only and recyclable.

There is no guarantee that the listeners will be notified in any particular order, however they will be notified one at a time, never in parallel.

To notify each registered listener, the speaker’s processActionEvent calls each listener’s actionPerformed(e) method by chasing the AWTEventMultiCaster listener chain.

AWTEventMulticaster contains generic code that most components use for implementing addXXXListener and the notification of listeners. Component has various add/remove listener methods that use AWTEventMulticaster that all Components inherit.

If we had been processing a mouse motion, we would have called the listener’s mouseMoved method instead. processActionEvent methods are designed to be called by processEvent; methods like actionPerformed and mouseMoved are part of listener interfaces. Most application coding uses only listeners. Only if you were inventing a new sort of component would you get involved with processEvent and processActionEvent.

What Are Listeners?

1. implements one of the EventListener interfaces such as ActionListener. E.g. an ActionListener must implement an actionPerformed method to be called when an Action Event occurs.
2. Has hooked itself (or been hooked by a third party) onto one or more Event-generating components with a method such as addActionListener.

A listener might be a component, an ordinary object, a special Mom object to mother a set of components or an anonymous object created from an anonymous class to simply provide a hook to some other routine.

A listener might be created by extending one of the adapter shortcut classes. The adapter classes give you some dummy classes to start with in defining a listener where you only want to handle a few types of Event.

A component may even register itself as a listener for Events originating it itself. This is the preferred method for application programmers since there is less possibility of mucking up standard Event processing.

A listener can field Events from many different sources. Similarly a source may notify many different listeners. Alternatively you could have a separate listener object for every source, or anything in between.

Components like JButtons implement interfaces like ItemSelectable. The provide methods like addItemListener so that classes that implement the ItemListener interface can arrange to be notified of interesting events in the button, such as it being pressed by first hooking themselves up through JButton.addItemListener.

The JButton uses EventListenList to maintain the list of interested listeners. When something interesting happen its calls fireActionPerformed which calls each of the actionPerformed methods of the register listeners. Even though an event gets passed to the actionPerformed method, the listener mechanism does not necessarily mean the event spent any time in a queue. It could be created and passed immediately to the listeners when the interesting event happened.

You could even use the listener mechanism in your own code, for both the notifier and listener end, for situations where it is hard to keep track of who should notify whom when some interesting thing happens. You don’t need to modify the callee’s code to add more interested parties. You don’t need an event queue.

You can also set up a listener to monitor all the events. You might use this to monitor keyboard or mouse activity for a timeout to shutdown after a period of inactivity.

Listener Actions

It had better be quick! The entire system is at a standstill, unable to process any more Events until your listener completes its action. If the action is going to take more than a few milliseconds you should either:

• Spin off a separate thread to do the work and immediately return from the Event handler. With Swing you must be careful since Swing components are not thread safe. You must only access them with the original thread-dispatching thread.
• Do a little of the work, and enqueue a synthetic Event to remind yourself to do a little more of the work later.
• Create a second thread to dispatch Events, popping them off the SystemEventQueue.

How Does consume() Work?

After all the listeners have been called, the Event is checked to see if it has been consumed. If so, then it is not passed onto the next stage. For e.g. KeyEvents for a TextArea, this means that it is not passed back to the peer, and so does not reach the underlying window/widget, and so does not appear.

consume() in KeyListeners is effectively broken in Swing 0.7 since it is ignored. It looks like the Event is drawn in JTextArea before being given to the listeners.

For TextFields, you can change the value of the keystroke in the Event in a KeyListener before passing it on, e.g. convert it to lower or upper case. However under Motif, converting to lower case is broken, and the entire technique is broken for Swing. You would have to trap processKeyEvent instead. In a TextField in the AWT, you get the Event before the character has been painted on the screen. Therefore if you do a getText or setText in your Event handler, very likely will thoroughly confuse the AWT. The AWT was not designed to do anything useful, just to look good on paper. To save your sanity, it is perhaps best to look on the AWT as an mystery/adventure game. Your task is to figure out by experiment what the methods do. Their names give you the barest of clues. You then McGuyver-like must cobble the odd bits together to create something practical.

How Do You Compose a Listener?

1. defines a new anonymous class that extends the WindowAdapter listener.
2. defines a method in that class to deal with window closing Events.
3. allocates an object of that class.
4. hooks that object up as a listener to the current frame component.
5. throws away the reference to the class. (The object won’t die since it is on the list of listeners.)

Cremation

Table of Event Classes and Methods

Instead of creating an ActionEvent with id ActionEvent.ACTION_PERFORMED, that is dispatched to processEvent, then passed on to processActionEvent, then passed on to an ActionListener (that registered its interest via addActionListener) via its actionPerformed method, there are many other possibilities you can generate from the following table:

Censoring or Remapping Keystrokes

In Swing you can use the Keymap and KeyStroke classes to control the actions of various keystrokes.

Activating

Styles Of Activating

1. compact

   You do it all in one very complicated line, where you define an anonymous class, create an instance of it and feed it to the addListener method. The puts everything in one place. The code is an unreadable forest of parentheses braces and semicolons. They limit you to one component per listener. They generate one extra inner class per use. They don’t have to deal with the problem of figuring out which component the incoming event to the listener is relevant too. There is only one possibility. Java beautifiers tend to over-indent this style. Inner classes get total and easy access to all the mother class’s fields. The examples that follow are all of this style.

2. anonymous class reference

   You create a reference to a anonymous inner class object then in a separate step, feed that to the addListener method. I prefer this to (1) because it is easier to proofread and SlickEdit beautifier renders it without excessive indentation. You have the option of reusing a Listener on several components. You can also collect all your listener logic in one place separate from the GUI logic which makes it easier to maintain. This is the style I most commonly use personally.

3. named inner class reference

   Like (2), but you name the inner classes. Perhaps a little easier for notices to understand.

4. named free standing classes

   like (3) but with ordinary classes that implement the Listener interfaces. They don’t have easy access to the parent class variable. You can use designs where the mother class itself implements the Listener interface, or where the Listener classes have additional functionality. The Listener classes can have parameters in their constructors, which anonymous inner classes cannot. This is the most flexible approach, but also requires the most typing.

5. Stomp Style

   These are mechanically generated. One master hookListeners method calls a separate method to hook up each component. Those methods in turn build an anonymous listener and link it to the widget. On activation they call one line of code, which is yet another method that actually does the work. It is verbose, but easy to proofread because the important stuff is separated from the bubblegum. Here is what you type:

Activating a Button

Activating a FocusListener

Activating a KeyListener

Activating a Choice or JCheckbox ItemListener

JMenuItems

TextListener.textValueChanged

Missing Events

• When you override a listener method of an Adapter, did you spell the name of the listener method correctly with exactly the right signature? If you did not, the compiler will give no error message and all the Events will continue to be delivered to the Adapter’s dummy listener method. Be especially careful when you are experimenting with a variety of places to tap in. You must change the type of the Event parameter.
• Are any Events arriving? Perhaps the Events arriving are slightly different from those expected. Put in some debug code to dump out whatever is arriving to any of the listener methods.
• Are you sure your component is supposed to be generating the events you expect? Often components don’t pass on low-level mouseMoved or mouseClicked events, but instead pass on higher level ItemStateChanged or actionPerformed events.
• Are you sure you remembered to hook up your component to your listener with theComponent.addXXXListener(theListener)? Did you use the right add method?
• You will never get any keystrokes out of a component that does not have focus.
• Don’t expect keystroke events to appear at a Panel. They will appear at the component in the Panel that has focus.
• Don’t expect keystrokes from a ListBox. You will get ItemStateChanged events instead.

Mouse Events

If you click the mouse, you will get three events which will show up at mousePressed, then mouseReleased then mouseClicked.

If you move the mouse onto your component you will first get an event at mouseEntered. If you move if off the component, you will get an event at mouseExited.

Every time you move the mouse even a tad, you will get an event at mouseMoved.

If you press a mouse button and drag you will get an event at mousePressed followed by multiple events at mouseDragged reporting the current drag location. When you let go of the button, you get an event at mouseReleased. You won’t get an event at mouseClicked

If you twirl the wheelmouse on a Component in a ScrollPane, you won’t see events at the Component’s mouseWheelmoved. Instead you will see events at mouseMoved, as if there were no ScrollPane and user had moved the mouse instead. Events are mouseMoved are about relative motion over the virtual panned Component in the ScrollPane.

Detecting Shift, Alt and Ctrl, Left and Right Mouse Buttons

You can detect the separate pressing of Shift, Alt or Ctrl at the keyPressed() listener, and the releasing at the keyReleased listener, by testing KeyEvent.getKeyCode() for a match with KeyEvent.VK_SHIFT, VK_CONTROL, VK_ALT and KeyEvent.VK_META.

With the advent of JDK 1.3, you can detect and set the state of the various CapsLock-like states with: public boolean getLockingKeyState(int keyCode) and public void setLockingKeyState(int keyCode, boolean on). Valid key codes are: VK_CAPS_LOCK, VK_NUM_LOCK, VK_SCROLL_LOCK, VK_KANA_LOCK.

Dealing with mouse clicks is similar. In your mouseClicked listener, MouseEvent.getModifiers() returns the state of all the modifier keys and mouse buttons when the event was fired. You can use this method to determine which mouse button was pressed (or newly released) when a mouse Event was fired. You mask the result with an ORed combination of InputEvent.ALT_MASK, BUTTON1_MASK, BUTTON2__MASK, BUTTON3_MASK, CTRL_MASK, META_MASK, and SHIFT_MASK. For example, the following expression is true if the right button was pressed:

getID() tells you the type of event, basically which listener was used. KeyCode() gets you a raw Keyboard code e.g. "A". keyChar() gets you the cooked character e.g. "a". See KeyListener in the Java glossary for more discussion.

I suggest downloading my little KeyPlay application. You can play with it, clicking the mouse and hitting keystrokes. A description of the Events generated is dumped to the console. With it, you can quickly learn about the ordering of Events, and the use of the fields. You will discover most JVMs work the same way, with the exception of Microsoft’s which is out in left field. Check out Sun’s java.awt. Robot class for generating simulated keystrokes and mouse moves.

Keystroke Events

Keystroke Names

Event vs. AWTEvent

Synthetic Events

1. Check out Sun’s java.awt.Robot class for generating simulated keystrokes and mouse moves.
2. The simplest is just to call a Listener method directly with a dummy Event object, filled in with just enough data to keep the method happy.
3. Create an Event and introduce it to the Component that will handle it at the processEvent method. with:
4. Create an Event and introduce it to the SystemEventQueue with:

   Toolkit.getDefaultToolkit().getSystemEventQueue().postEvent( Event e );

5. Generating MouseMoved Events has no effect on the screen mouse cursor. To make the underlying native GUI see your generated Events, use the Robot class to generate move clicks, moves etc.

   // synthetic native gui events
   import java.awt.event.InputEvent;
   import java.awt.event.KeyEvent;
   import java.awt.Robot;
   ...
   Robot r = new Robot();
   r.mouseMove( 100, 100 );
   r.keyPress( KeyEvent.VK_A );
   r.mousePress( InputEvent.BUTTON1_MASK );

Changes from JDK 1.0

Changes with JDK 1.3

The catch is MouseEvents you create this way don’t move the mouse cursor. To insert native events that will, see the Robot class. It can also be used to generate synthetic keystroke events. The Robot class helps you create self running demos.

Repaint

Credits

	recommend book⇒Tricks Of The Java Programing Gurus
		paperback
	ISBN10:	1-57521-102-5
	ISBN13:	978-1-57521-102-2
	publisher:	Sams
	published:	1996-07
	by:	Glenn L. Vanderburg
Chapter by Jan Newmarch
amazon.ca amazon.com chapters.indigo.ca powells.com amazon.fr barnesandnoble.com amazon.de amazon.co.uk

Summary