Events in Java are handled by registered listener objects (often referred to as the Observer design pattern). The object interested in listening to a given event must implement the proper Java interface and then register to receive the events.

Any Java object can register to listen to any other object’s events, but it is often useful for a wrapper object to listen to its own GUI and notify events. It usually makes most sense for a client object to listen to IDL output events.

Note: Registering or unregistering listeners for events should happen in the initListeners method or AFTER the createObject method.

Nondrawable Java Objects

Nondrawable objects, which inherit from JIDLObject, can be notified of the following events:

The default behavior as provided by the JIDLObject superclass is that they are not wired to listen to any events.

Drawable Java Objects

Drawable objects, which inherit from JIDLCanvas, are wired by default to listen to the following events:

In addition, drawable objects can also listen to the following events, but they do not listen to them by default:

IDL Notification

As mentioned above, IDL objects that subclass itComponent can trigger a notification from the IDL object level by calling IDLitComponent::NotifyBridge. Both drawable (JIDLCanvas) and nondrawable (JIDLObject) wrapper objects handle IDL notifications.

To receive a notification, a class must implement the JIDLNotifyListener interface and register with the wrapper object by calling its addIDLNotifyListener method to register itself as a listener. The listener class can unregister itself by calling the removeIDLNotifyListener method.

The following is the definition of the JIDLNotifyListener interface:

public interface JIDLNotifyListener
{
  // obj: a reference to the wrapper object that triggered notify
  // s1  s2 are strings sent from IDLitComponent::NotifyBridge
  void OnIDLNotify(JIDLObjectI obj, String s1, String s2);
}

These methods are available to JIDLCanvas and JIDLObject:

public void addIDLNotifyListener(JIDLNotifyListener l);
public void removeIDLNotifyListener(JIDLNotifyListener l);

IDL Output

In general, IDL output can be listened to by any class that implements the JIDLOutputListener interface and registers itself as a listener by calling addIDLOutputListener. The listener class can unregister itself by calling removeIDLOutputListener. Both drawable (JIDLCanvas) and non-drawable (JIDLObject) wrapper objects handle IDL output.

The following is the definition of the JIDLOutputListener interface:

public interface JIDLOutputListener
{
  // obj: a reference to the wrapper object that triggered notify
  // s is the IDL output string
  void IDLoutput(JIDLObjectI obj, String s);
}

These methods are available to JIDLCanvas and JIDLObject:

public void addIDLOutputListener(JIDLOutputListener l);
public void removeIDLOutputListener(JIDLOutputListener l);

Handling Specific Events

This section describes how client applications can listen to and handle the following events: mouse, mouse motion, keyboard, and component.

Mouse Events

Mouse events include a mouse entering the canvas, the mouse exiting the canvas, a mouse press in the canvas, and a mouse release in the canvas. Drag and move events are handled as mouse motion events (see Mouse Motion Events).

In general, mouse events may be listened to by any class that implements the JIDLMouseListener interface and registers itself as a listener by calling the addIDLMouseListener method. The listener class can unregister itself by calling the removeIDLMouseListener method. Only drawable (JIDLCanvas) wrapper objects handle this event type.

The following is the definition of the JIDLMouseListener interface:

public interface JIDLMouseListener
{
  // obj is a reference to the wrapper object
  // e is a java.awt.event.MouseEvent
  void IDLmouseEntered (JIDLObjectI obj, MouseEvent e);
  void IDLmouseExited (JIDLObjectI obj, MouseEvent e);
  void IDLmousePressed (JIDLObjectI obj, MouseEvent e);
  void IDLmouseReleased(JIDLObjectI obj, MouseEvent e);
}

These methods are available to JIDLCanvas:

public void addIDLMouseListener(JIDLMouseListener l);
public void removeIDLMouseListener(JIDLMouseListener l);

The default behavior of drawable wrappers is that they automatically register to listen to themselves and provide default event handlers for each of these events. The following table describes the default behavior for each event type.

Event

Action

IDLmousePressed

Triggered when a mouse button is pressed inside the canvas. The default behavior passes the event to the IDL method OnMouseDown.

IDLmouseReleased

Triggered when a mouse button is released inside the canvas. The default behavior passes the event to the IDL method OnMouseUp.

IDLmouseEntered

Triggered when the mouse enters the canvas. Default implementation does nothing. The default behavior calls the IDL method OnEnter.

IDLmouseExited

Triggered when the mouse exits the canvas. Default implementation does nothing. The default behavior calls the IDL method OnExit.

Mouse Motion Events

Mouse motion events include a mouse being moved or dragged inside the canvas. In general, mouse motion can be listened to by any class that implements the JIDLMouseMotionListener interface and registers itself as a listener by calling the addIDLMouseMotionListener method. The listener class can unregister itself by calling the removeIDLMouseMotionListener method. Only drawable (JIDLCanvas) wrapper objects handle this event type.

The following is the definition of the JIDLMouseMotionListener interface:

public interface JIDLMouseMotionListener
{
  // obj is a reference to the wrapper object
  // e is a java.awt.event.MouseEvent
  void IDLmouseDragged(JIDLObjectI obj, MouseEvent e);
  void IDLmouseMoved(JIDLObjectI obj, MouseEvent e);
}

These methods are available to JIDLCanvas:

public void addIDLMouseMotionListener(JIDLMouseMotionListener l);
public void removeIDLMouseMotionListener(JIDLMouseMotionListener l);

The default behavior of drawable wrappers is that they automatically register to listen to themselves and provide default event handlers for each of these events. The following table describes the default behavior for each event type.

Event

Action
IDLmouseDragged

Triggered when the mouse is moved while its left button is pressed inside the canvas. The default behavior passes the event to the IDL method OnMouseMotion.
IDLmouseMoved

Triggered when the mouse is moved (while no button is pressed) inside the canvas. The default behavior passes the event to the IDL method OnMouseMotion.

Mouse Wheel Events

Mouse wheel events include the scroll wheel of the mouse being rolled inside the canvas. In general, mouse wheel motion can be listened to by any class that implements the JIDLMouseWheelListener interface and registers itself as a listener by calling the addIDLMouseWheelListener method. The listener class can unregister itself by calling the removeIDLMouseWheelListener method. Only drawable (JIDLCanvas) wrapper objects handle this event type.

The following is the definition of the JIDLMouseWheelListener interface:

public interface JIDLMouseWheelListener
{
  /**	A mouse wheel has moved inside the JIDLCanvas.
  * obj is a reference to the wrapper object
  * e is a java.awt.event.MouseWheelEvent
  */
  void IDLmouseWheelMoved(JIDLObjectI obj, MouseWheelEvent e);
}

These methods are available to JIDLCanvas:

public void addIDLMouseWheelListener(JIDLMouseWheelListener l);
public void removeIDLMouseWheelListener(JIDLMouseWheelListener l);

The default behavior of drawable wrappers is that they automatically register to listen to themselves and provide default event handlers for each of these events. The following table describes the default behavior for each event type.

Event

Action
IDLmouseWheelMoved

Triggered when the mouse wheel is rolled. The default behavior passes the event to the IDL method OnWheel.

Keyboard Events

Keyboard events include a key being pressed or released when the Canvas has focus. In general, keyboard events can be listened to by any class that implements the JIDLKeyListener interface and registers itself as a listener by calling the addIDLKeyListener method. The listener class can unregister itself by calling the removeIDLKeyListener method. Only drawable (JIDLCanvas) wrapper objects handle this event type.

The following is the definition of the JIDLKeyListener interface:

public interface JIDLKeyListener
{
  // obj is a reference to the wrapper object
  // e is a java.awt.event.KeyEvent
  // (x,y) is the location of the mouse in the Canvas
  void IDLkeyPressed (JIDLObjectI obj, KeyEvent e, int x, int y);
  void IDLkeyReleased(JIDLObjectI obj, KeyEvent e, int x, int y);
}

These methods are available to JIDLCanvas:

public void addIDLKeyListener(JIDLKeyListener l);
public void removeIDLKeyListener(JIDLKeyListener l);

The default behavior of drawable wrappers is that they automatically register to listen to themselves and provide default event handlers for each of these events. The following table describes the default behavior for each event type.

Event

Action
IDLkeyPressed

Triggered when a key is pressed when the canvas has focus. The default behavior passes the event to the IDL method OnKeyboard.
IDLkeyReleased

Triggered when a key is released when the canvas has focus. The default behavior passes the event to the IDL method OnKeyboard.

Component Events

Component events include the drawable canvas being resized and being exposed (uncovered or redrawn). Typically, these events are not handled by the client, but are handled behind the scenes by the Java Export Bridge, which resizes and repaints the canvas automatically. However, these events can be of interest to the client.

In general, component events can be listened to by any class that implements the JIDLComponentListener interface and registers itself as a listener by calling the addComponentListener method. The listener class can unregister itself by calling the removeComponentListener method. Only drawable (JIDLCanvas) wrapper objects handle this event type, and these methods are available only to JIDLCanvas objects.

The following is the definition of the JIDLComponentListener interface:

public interface JIDLComponentListener
{
  void IDLcomponentResized(JIDLObjectI obj, ComponentEvent e);
  void IDLcomponentExposed(JIDLObjectI obj);
}

These methods are available to JIDLCanvas:

public void addIDLComponentListener(JIDLComponentListener l);
public void removeIDLComponentListener(JIDLComponentListener l);

Specifically, drawable wrapper objects (those that inherit from JIDLCanvas) automatically register to listen to their own component events and provide default handlers for each of these events. The following table describes the methods and default implementations for the events.

Event

Action
IDLcomponentResized

Triggered when the canvas is resized. The default behavior calls the IDL method OnResize.
IDLcomponentExposed

Triggered when the canvas is exposed. The default behavior calls the IDL OnExpose method, which is expected to call the IDL object’s draw method.

Subclassing to Change Behavior

There are two ways to change the event-handling behavior of listener objects: subclassing the wrapper object and handling the events in the subclass, or allowing a client object to handle events. Typically, GUI events and notifications are handled through subclassing and IDL output through client objects.

When a client calls the (drawable or nondrawable) wrapper object’s createObject method, the wrapper object calls its initListeners method internally. This method, automatically generated by the Export Bridge Assistant, determines which events the wrapper object will listen to. As explained above, the wrapper object also has a set of methods generated to provide the default handling of these events.

To change what the object is listening to, subclass the generated wrapper object and override the initListeners method. The subclassed initListeners method can now register for whatever listeners in which it is interested.

For example, automatically generated drawable wrapper objects handle mouse, mouse motion, keyboard, and component events. Suppose you have a wrapper object called canvasWrapper, generated by the Assistant. You could subclass a wrapper object called myCanvasWrapper that would only handle mouse motion events. (The mouse motion events would still be handled in the default manner, but mouse, keyboard, and component listening would not be enabled.) This new wrapper object would look like this:

class myCanvasWrapper extends canvasWrapper
{
  public void initListeners()
  {
  addIDLMouseMotionListener(this);
  }
}

To change the behavior of the listener handlers, subclass the generated wrapper object and override the event handling method whose behavior you want change. To get the default behavior, pass the event to the superclass.

Consider the following example. Given the same generated canvasWrapper class, you could ignore mouse drags and, on a mouse press, print information to a console object before passing up to the IDL object to handle. This class would look like this:

class myCanvasWrapper2 extends canvasWrapper
{
  public void IDLmousePressed(JIDLObjectI o, MouseEvent e)
  {
  console.printMouseEvent(e);
  super.IDLmousePressed(o, e); // pass to IDL
  }
  public void IDLmouseDragged(JIDLObjectI o, MouseEvent e)
  {
  // do nothing
  }
}

Listening from Other Java Objects

Any Java object that implements the proper listener interface and registers itself with the wrapper object as a listener can also listen to events of interest. When more than one object is registered to listen to a given event, all listeners receive the event without a guarantee of order.

The steps are as follows:

  1. The class implements the proper listener interface.
  2. The class registers to listen to events.
  3. The class handles the event in the listener interface method (or methods).

As an example, use the same canvasWrapper in a class called myClient that listens to IDL output. First, implement the JIDLOutputListener interface. Next, use the constructor to have the client register itself as a listener of the wrapper’s IDL output. Finally, implement the IDLoutput to act on the output. The code is shown below:

import com.itt.javaidl.*;
class myClient implements JIDLOutputListener
{
  canvasWrapper m_wrapper;
  public myClient()
  {
  m_wrapper = new canvasWrapper();
  m_wrapper.createObject();
  m_wrapper.addIDLOutputListener(this);
  }
  public void IDLoutput(JIDLObjectI obj, String s)
  {
  // do something with the IDL output
  }
  ...
}