The events fired by Java objects are divided into event interfaces. Each event is represented by an event method in an event interface. For example, objects of the java.awt.Button class can fire events in the ActionListener, ComponentListener, FocusListener, KeyListener, MouseListener and MouseMotionListener interfaces (all these interfaces are defined in the JDK package java.awt.event.) The KeyListener interface in turn contains the event methods keyPressed, keyReleased and keyTyped. To find out what events are fired by different Java classes, please consult their API documentation.
The eventName argument for the java::bind command is the full or abbreviated name of the event. The full event name is the name of an event interface, followed by the character ".", followed by the name of the event method. For example, java.awt.event.KeyListener.keyTyped. The abbreviated event name is just the name of the event method. For example, keyTyped. Abbreviated event names may be used only if the event method name appears in exactly one of the event interfaces of the object.
If the script argument is given, it specifies a callback script to to be executed when the given event is fired in the javaObj. If a callback script already exists for the given event in javaObj, it will be replaced by script. If script is the empty string, any previously installed callback scripts for the given event in javaObj will be removed.
If the script argument is not given, the java::bind command returns the current callback script, if any, for the given event in javaObj.
If the eventName and script arguments are both omitted, the java::bind command returns a Tcl list of the the full names of all the events of javaObj that are currently associated with callback scripts.
If propertyName is not given, java::event returns the value of the specified event paramater. If the specified event parameter is a Java object, then its object handle is returned. If propertyName is given, and the specified event parameter is a Java object, java::event returns the value of the given property of the event parameter. The second form is used mainly for convenience. For example, the following two statements are equivalent:
java::bind $b keyTyped { puts [java::prop [java::event] keyCode] } java::bind $b keyTyped { puts [java::event keyCode] }
Event handling may be nested if the Tcl event loop is re-entered during the execution of a callback script (e.g, when a callback script executes the update command.) In that case, java::event always returns the paramaters of the inner-most event whose callback script is currently being executed.
set button [java::new jawa.awt.Button] java::bind $button mouseClicked { puts "mouse is at ([java::event x],[java::event y])" }
The return value must be convertible to the declared return type of the event method. Otherwise, a Tcl background error is generated and an undefined value (usually 0, false or null) is returned to the Java object.
java::bind $b vetoableChange { if {[java::event propertyName] == "size"} { if {[java::event newValue] > 10} { java::throw [java::new java.beans.PropertyVetoException \ "value too large" [java::event]] } } }
The callback script can throw any unchecked exception object (e.g., instances of java.lang.Error or java.lang.RuntimeException.) The callback script can also throw any checked exception allowed by the signature of the event method.
If the callback script throws a checked exception which is not allowed for the event, a Tcl background error is generated. If the callback script is expected to return a value, an undefined value is returned to the Java object.
Copyright © 1998 by Sun Microsystems, Inc. Copyright © 1995-1997 Roger E. Critchlow Jr.