Note: Because the event model for JDK 1.0 is rapidly becoming obsolete, material on the JDK 1.0 event model will not be covered in classroom lectures or examinations in Professor Baldwin's CIS 2103K (Intermediate Java Programming) classes at Austin Community College.
When JDK 1.1 is released and hard information regarding those changes becomes available, this lesson will be supplemented with a new lesson describing events and event handling under JDK 1.1.
There may be some confusion in your mind about the earlier discussions of passing events up the container hierarchy. If so, we will try to clear up that confusion in this lesson.
In a previous lesson, we described how user actions involving GUI components get converted into messages by the operating system, and how those messages are sent to the Java runtime system.
We said that when this happens, the Java runtime system
In this lesson, we will describe how the postEvent() method comes into play and how it relates to handleEvent(). As an aside, we will also describe how it relates to the deliverEvent() method.
We explained that if handleEvent() returns false, the event is passed up to the next container in the container hierarchy.
In this lesson, we will write a program which constructs just such a container hierarchy and will be able to watch an event being passed up the line as the program executes.
We also explained that if handleEvent() returns true, the event will be stopped at that level and will not be passed up to the next container in the hierarchy.
The process of passing the event up the line continues until the handleEvent() method at some level returns true, or there are no more containers to pass it up to.
public boolean postEvent(Event evt) Posts an event to this component by calling its handleEvent method. If handleEvent returns false, the event is posted to this component's parent. If this component and all of its parents return false, the event is passed to this component's peer object's handleEvent method. Parameters: evt - the event Returns: true if this component, one of its parents, or this component's peer handled the event; false otherwise. See Also: deliverEvent.The above information introduced another new term: peer.
According to the Glossary in Exploring Java,
It is the postEvent() method that actually implements the processing of passing events up the hierarchy from one container to the next.
At each point along the way, postEvent() invokes handleEvent() which may return either true or false.
If true is returned at any level, the postEvent() method terminates the process. Otherwise, it passes the event up to the next postEvent() method in the container hierarchy which repeats the action.
Eventually, when postEvent() runs out of containers, the event is passed to another part of the system for default handling, if any.
In an earlier lesson when we were creating program-generated events, we said that we could deliver the program-generated event to the recipient using either deliverEvent() or postEvent(). Let's look at the reason that either method could be used.
The following description of deliverEvent() was extracted from the API Documentation.
public void deliverEvent(Event evt) Delivers an event to this component or one of its subcomponents. The deliverEvent method of Component calls the component's postEvent method on the event. Parameters: evt - the eventApparently based on the above, deliverEvent() simply calls postEvent() and passes the event along as a parameter. That is why you can use either. I haven't found anything indicating a downside to calling postEvent() directly from your program, but as usual there may be one lurking somewhere. Otherwise, there would be no need for the existence of deliverEvent() in the first place.
The following program is not intended to demonstrate effective interface design. However, it is intended to illustrate the process by container hierarchies can be established. This leads naturally to the study of events propagating up the container hierarchy.
I will not provide much in the way of a written discussion of this program other than the discussion in the comments at the beginning of the program, because there isn't much here that is new.
We will be using a new term: Panel. In Java, a Panel is a class in the java.awt package which can be used to instantiate container objects.
A Panel can't be seen. It is simply a place to put other components in some desired arrangement.
The Panel and its components, with their specific arrangement, can then be treated as a single object which can be placed along with other such objects into another container.
That is how the container hierarchy is built up.
Take a look at the following program. Although the program is fairly long, it is repetitious.
A description of the program is given in the comments at the beginning.
If you compile and run this program, you should see a column of objects containing three TextField objects and one Button object. The button is at the bottom, and the top-level TextField object is at the top.
If you click the Button object, you should see the text in each of the TextField objects change, with a one-second delay between the changes in the TextField objects, going from bottom to top. This simulates the Event object being propagated up the container hierarchy.
At this point, you shouldn't worry about the layout manager code which I needed to use. Suffice it to say that a layout manager is there to help you arrange components in a container.
There are several different styles of layout manager available. The one being used here is a border layout manager. This layout manager can be used to place up to five objects in a container: one in the center, and the other four in the North, South, East, and West positions.
What you do need to pay particular attention to is how the container and its components is instantiated into an object which simply becomes one of the components in the next higher-lever container.
This is the key to the GUI container hierarchy which we have been discussing for several lessons.
/*File Event04.java Copyright 1997, R.G.Baldwin
Illustrates the propagation of an event up through the
GUI object hierarchy, from container to container, to
container, etc.
A Frame is created at the top level which contains a TextField
and a Panel.
The Panel in the frame contains a TextField and another Panel.
That Panel contains a TextField and a Button. Thus, the Panel
containing the TextField and the Button are at the innermost
level of the hierarchy.
When the button is clicked, an ACTION_EVENT is generated on the
Button. The handleEvent() method of the innermost container is
used to put a message in the TextField. The handleEvent() method
returns false to cause the event to propagate up to the next
container in the hierarchy.
Because the method returns false, the system passes the event to
the handleEvent() method in the next container up the line. That
method puts a message in its TextField and returns false as well.
Again, because the handleEvent() method returns false, the event
is then passed up to the next level which is the top level container.
The handleEvent() method in the top-level container puts a message in
its TextField, invokes super.handleEvent(), and exits.
In summary, as the event propagates up through the hierarchy,
the handleEvent() method of the container at each level displays
a message and passes the event along. Thus, messages are generated
at all three levels as the event is propagated upward.
To make it easier to see what is happening, a one-second delay is
implemented in each event handler before the new text is actually
displayed.
Depending on the resolution of your screen, you may need to change
the size of the frame to make all three TextFields visible.
The following code is presented in an innermost to outermost order.
*/
import java.awt.*;
class ThirdLevel extends Panel{ //define class for innermost container
Button myButton;//reference variable for Button object
TextField myTextField;//reference field for TextField object
ThirdLevel(){//constructor
setLayout(new BorderLayout());
myButton = new Button("click here");//instantiate Button object
add("South",myButton);
myTextField = new TextField("TextField, Third Level");//TextField object
add("North",myTextField);
resize(preferredSize());
}//end constructor for ThirdLevel class
//Event handler for innermost container
public boolean handleEvent(Event evObj){//confirm Button action event
if( (evObj.id == Event.ACTION_EVENT) &&
(evObj.target == myButton) ){
try{Thread.currentThread().sleep(1000);
}catch(InterruptedException e){}//do-nothing exception handler
myTextField.setText("Third Level ACTION_EVENT");
}//end if
return false;//pass the event up to the next container
}//end handleEvent()
}//end class ThirdLevel
class SecondLevel extends Panel{//class for middle-level container, panel
ThirdLevel myThird;
TextField myTextField;
SecondLevel(){//constructor
setLayout(new BorderLayout() );
myThird = new ThirdLevel();//instantiate innermost container as an object
add("South",myThird);
myTextField = new TextField("TextField, Second Level");
add("North",myTextField);
resize(preferredSize());
}//end constructor for SecondLevel class
public boolean handleEvent(Event evObj){
//Confirm that the event is an action event that originated
//at the button in the innermost container.
if( (evObj.id == Event.ACTION_EVENT) &&
(evObj.target == myThird.myButton) ){
try{Thread.currentThread().sleep(1000);
}catch(InterruptedException e){}//do-nothing exception handler
myTextField.setText("Second Level ACTION_EVENT");
}//end if
return false;//pass the event on up the line
}//end handleEvent()
}//end class SecondLevel
//This is the class for the outermost container which is the controlling
// class for the application. Make it extend the Frame class to produce
// a window that can accept events.
public class Event04 extends Frame{
SecondLevel mySecond;
TextField myTextField;
Event04(){//constructor
setLayout(new BorderLayout(1,3));
mySecond = new SecondLevel();//Instantiate middle container as object
add("South",mySecond);
myTextField = new TextField("TextField, Top Level");
add("North",myTextField);
setTitle("Copyright 1997, R. G. Baldwin");
resize(300,110);
}//end constructor for Event04 class
public boolean handleEvent(Event evObj){
if(evObj.id == Event.WINDOW_DESTROY) System.exit(0);
//Test to determine if the event is an action event generated by
// the button in the innermost container. Note the use of two
// dot operators to reference that Button object.
if( (evObj.id == Event.ACTION_EVENT)&&
(evObj.target == mySecond.myThird.myButton) ){
try{Thread.currentThread().sleep(1000);
}catch(InterruptedException e){}//do-nothing exception handler
myTextField.setText("Top Level ACTION_EVENT");
}//end if
return super.handleEvent(evObj);
}//end handleEvent()
public static void main(String[] args){
Event04 obj = new Event04(); //instantiate an object
obj.show(); //and display it
}//end main
}//end class Event04
-end-These tutorials were developed by Richard Baldwin and are the copyrighted property of Richard Baldwin. You have permission to print one copy for your own use, but may not, without written permission from Richard Baldwin, redistribute the tutorial documents. The base material in these lessons is believed by the author to be in the public domain. If you use these lessons for any purpose, you are using them at your own risk, and this author assumes no responsibility or liability for any damages that you may incur.
Java, Sun, HotJava and various other related symbols and names are registered trademarks of Sun Microsystems, Inc. Macintosh is a registered trademark of Apple Computer, Inc. OS/2 is a registered trademark of International Business Machines Corporation. Microsoft, MS-DOS, Visual Basic, Windows, Windows NT, Internet Explorer and Visual J++ are registered trademarks of Microsoft Corporation. Netscape and JavaScript are trademarks of Netscape Communications Corporation. All other trademarks and service marks that may have been inadvertently used in these lessons without proper credit being given are the property of their respective owners. If you feel that your trademark or copyright has been compromised, please notify this author immediately, and an appropriate correction to the document will be issued.
© 1996, 1997, 1998, 1999 Richard G. Baldwin