  NAME
    java::bind - Handling JavaBean events.
  SYNOPSIS
    package require java ?1.1?
    java::bind javaObj
    java::bind javaObj eventName
    java::bind javaObj eventName script
    java::event ?-index num? ?propertyName?
  DESCRIPTION
  java::bind
  java::event
  DETERMINING THE EVENT PARAMETERS
  RETURNING VALUES FROM CALLBACK SCRIPTS
  EXCEPTIONS
  ERRORS IN CALLBACK SCRIPTS
  SEE ALSO
  KEYWORDS

### NAME

java::bind - Handling JavaBean events.

### SYNOPSIS

package require java ?1.1?
java::bind javaObj
java::bind javaObj eventName
java::bind javaObj eventName script
java::event ?-index num? ?propertyName?

### DESCRIPTION

This group of commands are used to handle events fired by Java objects.

### java::bind

The java::bind command is used to associate scripts with events fired by Java objects. The javaObj argument specifies a Java object. The eventName argument identifies an event fired by the object.

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.

### java::event

When a callback script is invoked due to the firing of a Java event, some event parameters may be passed to the script to give detailed description of the event. The java::event command is used to query the values of these parameters. The -index option specifies which event parameter to quety: num is equal to 0 for the first parameter, 1 for the second parameter, and so on. If the -index option is omitted, the first event paramater is queried by default. In most cases, there is exactly one event parameter passed to the callback script and the -index may thus be safely omitted.

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.

### DETERMINING THE EVENT PARAMETERS

An event callback script can query the event parameters using the java::event command. Usually, there is only one event parameter -- the event object, which stores various information about the event as its properties. For example, when the mouseClicked event occurs inside an AWT Button, the x and y properties of the event object contains the location of the mouse cursor. The following script prints out the location of the mouse cursor:

    set button [java::new jawa.awt.Button]
    java::bind $button mouseClicked {
        puts "mouse is at ([java::event x],[java::event y])"
    }

### RETURNING VALUES FROM CALLBACK SCRIPTS

When a Java object fires an event, it may expect the callback script to return a value. In this case, the event method corresponding to the event has a non-void return type. The callback script should use the return command to return the desired value.

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.

### EXCEPTIONS

When a Java object fires an event, it may expect the callback script to throw an exception to indicate certain conditions. This can be done using the java::throw command. For example: the vetoableChange event requires the callback script to throw a java.beans.PropertyVetoException if the script deems the new value of a property unaccecptable, as in the following code fragment:

    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.

### ERRORS IN CALLBACK SCRIPTS

If the callback script causes a Tcl error, 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.

### SEE ALSO

java, java::load

### KEYWORDS

java, tcl, beans

    Copyright © 1998 by Sun Microsystems, Inc.
    Copyright © 1995-1997 Roger E. Critchlow Jr.