Mouse Handling

The first thing that you must do when dealing with the mouse, is to build some way of getting that input into your application. With the standard 2D AWT that is pretty easy - for any component, just add a MouseListener or MouseMotionListener and deal with the input. Since Canvas3D is just a component one could assume that we could do the same thing for the 3D world. Unfortunately (as discovered through trial and error by the author) this is not the best way to go about it and is the reason for the existence of the WakeupOnAWTEvent criteria.

When creating a handler for mouse input, there are two things that typically a mouse is used for: moving the user or object and picking an object. While related, there are certain extra aspects to picking that do not need to be considered with standard mouse input. Picking is covered in detail in the next section so for the moment we will concentrate on dealing with the low-level mouse handling.

General Mouse Behaviour

To start with, the first thing that we need to do is create a Behavior implementation so that we may interface the mouse input with the scene graph. We’ll call this class MouseBehaviour and start with the basic outline of:

public class MouseBehaviour
{
  public MouseBehaviour()
  {
  }

  public void initialize()
  {
  }

  public void processStimulus(Enumeration criteria)
  {
  }
}

public class MouseBehaviour
{
  private long eventMask;

  public MouseBehaviour(long mask)
  {
    eventMask = mask;
  }

Note

There are only two types of event masks that can be registered for mouse events - MOUSE_EVENT_MASK and MOUSE_MOTION_EVENT_MASK. These correspond to the two types of listeners you could normally attach to AWT/Swing components. In some projects, I prefer to not let the user provide the mask in the constructor, but only allow them to use two boolean flags to control what events need to be registered.

Deciding on how to structure the behaviour classes depends on how you want to use them. In this case, we want to create a base class and then derive it for individual application specific behaviours. To do this means that we need to pass the types of events that we want through into the constructor. For example, a pick based behaviour really only wants to be woken when a mouse is pressed or released on the object, but for navigation we may only want to know about drag events. There are a few ways of implementing this system, but my prefered approach is to have the base mouse class provide all the event distribution services and then let the derived classes override the methods that they are interested in. To process and send mouse events, then becomes the job of the processStimulus() method, which will be covered shortly. Right now, you need to know how to register the event. Registering for criteria, as you have previously seen, can only be done in initalize() or processStimulus(). To get your behaviour running the first time, you will need to register the initial condition in initialize()

  public void initialize()
  {
    WakeupOnAWTEvent critter = new WakeupOnAWTEvent(eventMask);

    wakeupOn(critter);
  }

After we have registered the conditions we also need to deal with the resulting stimulations by providing an implementation of the processStimulus() method. The parameter contains a list of the criteria that caused the behaviour to be executed. Although we should only ever get mouse events, we still take the precaution of checking all the values in the provided list. From this, when we come across an AWT condition we fetch the events and then need to do something with them. At this point we need to decide what to do with the mouse event. We could either process them and pass the result to somewhere, or just pass the raw event on. For this example, we are interested in maintaining the minimal code in the base class, so we just pass the raw event on to somewhere.

Somewhere is defined to be the derived class, as it should know what to do with the event. The easiest way to do this is provide an abstract method definition and call that with the AWT event to be processed. The resulting code looks like this:

protected abstract void processAWTEvent(AWTEvent evt);

public void processStimulus(Enumeration criteria)
{
  WakeupCondition cond;
  AWTEvent[] events;

  while(criteria.hasMoreElements())
  {
    cond = (WakeupCondition)criteria.nextElement();
    if(!(cond instanceof WakeupOnAWTEvent))
      continue;

    events = ((WakeupOnAWTEvent)cond).getAWTEvent();

    for(int i = 0; i < events.length; i++)
    {
      try
      {
        if(events[i] instanceof MouseEvent)
            processAWTEvent(events[i]);
      }
      catch(Exception e)
      {
        System.out.println("Error processing AWT event input");
        e.printStackTrace();
      }
    }
  }
}

Drag Mouse Behaviour

As usual with OO designs, there are all sorts of ways that we can skin the cat. In the end we elected to follow a set that traces the basic mouse event types. The drag class starts by deriving from the basic mouse behaviour and in the constructor all we pass is the mouse drag event (MouseEvent.MOUSE_DRAGGED). Following this, we just provide an implementation of the processAWTEvent method. For illustration, this will just issue a println telling you of the fact that an event was received.

public class MouseDragBehaviour extends MouseBehaviour
{
   public MouseDragBehaviour()
   {
     super(AWTEvent.MOUSE_MOTION_EVENT_MASK);
   }

   protected void processAWTEvent(AWTEvent evt)
   {
     System.out.println("got mouse drag event");
   }
}

Point3d origin = new Point3d(0, 0, 0);

Behavior bh = new MouseDragBehaviour();
BoundingSphere bounds =
        new BoundingSphere(origin, Double.POSITIVE_INFINITY);
bh.setSchedulingBounds(bounds);

universe.addWorldObject(bh);

Now if you added these changes and then ran the program you might have noticed some odd behaviour. The first time that you drag, you get a single printout of the message. Next time you drag, nothing happens. Behaviours are registered to act at the point that they are called. Effectively they are a one-shot application. If you want the behaviour to continually evaluate, you need to keep registering it for the next invocation of that criterion. To enable this to happen, a new method is added to the base class that re-registers the criteria that we created for the first run of the class. Then, every time that the processAwtEvent() method is called in the derived class, we call this method in the base class. Our modified base class now looks like this:

public abstract class MouseBehaviour extends Behavior
{
  ...

  public void initialize()
  {
    WakeupCondition critter = new WakeupOr(eventMask);
    resetEvents();
  }

  protected final void resetEvents()
  {
    wakeupOn(critters);
  }
  ...
}

Note

The AWT criterion seems to be quite different to the others. The undocumented behaviour is that it will continue to send you events without needing to re-register it every frame like you need to do with other wakeup conditions. This is undocumented, and based on the word of the Java3D developers at Sun, so take it with a grain of salt as it may not work in future versions. It has changed between previous versions too.

To complement this, the mouse drag behaviour modifies its processAwtEvent() method to read:

protected void processAWTEvent(AWTEvent evt)
{
   System.out.println("got mouse event");
   resetEvents();
}

Other Mouse Behaviours

For each of these custom behaviours you need to provide a class with the method implementations like we outlined above. Then from there you would create another set of derived classes to do particular things. Say you wanted a mouse behaviour that, when dragging, rotated an object about. For this you would need the new derived class to take a reference to a TransformGroup (just like the RotationInterpolator example of the previous chapter). From there, the sky’s the limit!