edu.umd.cs.jazz.event
Class ZFilteredEventHandler

java.lang.Object
  |
  +--edu.umd.cs.jazz.event.ZFilteredEventHandler

All Implemented Interfaces:

ZEventHandler

Direct Known Subclasses:

ZDragSequenceEventHandler, ZoomToEventHandler, ZSelectionDeleteHandler, ZSelectionScaleHandler

public class ZFilteredEventHandler

extends java.lang.Object

implements ZEventHandler

ZFilteredEventHandler is an abstract implementation of ZEventHandler. This class provides flexible event filtering. This allows one to easily filter the events that this event handler will receive without modifying the event handler source code.

This class automatically handles the task of registering and unregistering with its filtered event sources. These sources (a key event source and mouse event source) are specified as arguments to this class's constructor or with setKeyEventSource and setMouseEventSource. The normal behavior when this class is set to active is to register as a KeyListener with the filtered key event souce if it is not null, and to register as a ZMouseListener and a ZMouseMotionListener with the filtered mouse event source if it is not null. This behavior can be customized by overriding these methods:

• protected boolean wantsKeyEvents()
• protected boolean wantsMouseEvents()
• protected boolean wantsMouseMotionEvents()

Filtering is supported by the ZMouseFilter class together with the following template methods that subclasses should override if they are interested in that event.

• protected void filteredKeyPressed(KeyEvent e)
• protected void filteredKeyReleased(KeyEvent e)
• protected void filteredKeyTyped(KeyEvent e)
• protected void filteredMouseClicked(ZMouseEvent e)
• protected void filteredMouseDragged(ZMouseEvent e)
• protected void filteredMouseEntered(ZMouseEvent e)
• protected void filteredMouseExited(ZMouseEvent e)
• protected void filteredMouseMoved(ZMouseEvent e)
• protected void filteredMousePressed(ZMouseEvent e)
• protected void filteredMouseReleased(ZMouseEvent e)

These methods will only be called if the the event filter assocaited with this event handler first accepts the incoming event.

Filters can be used in two ways. An external application can use them to modify the behavior of a existing event handler. For example an application can tell a ZPanEventHandler to only accept ZMouseEvents that have the shift modifier pressed, and this will cause the panning to occur only when the shift key is down.

      // Example of using a mouse filter externally.
      ...
      // Get a reference to the pan event handlers filter.
      ZMouseFilter panFilter = canvas.getPanEventHandler().getMouseFilter();

      // Set the filters andMask to contain button1 and shift. This means that
      // an event must have both button1 and shift in its modifiers to be accepted by
      // the filter. The panning action will now only occur when those modifiers are both set.
      panFilter.setAndMask(InputEvent.BUTTON1_MASK | InputEvent.SHIFT_MASK);
      ...
 

Filters can also be used internally by an event handlers implementation. For example a event handler can determine on a filtered mouse down event that it is not appropriate for it to act in the current context and can then set its filter to accept nothing but the next filtered mouse down event that it sees. This can get rid of testing code in other methods such as mouse moved and mouse released that determines if the event handler should really act in that context or not.

      // Example of using a mouse filter internally.
      protected void filteredMousePressed(ZMouseEvent e) {

          if (shouldStartHandlingEvents(e)) { // This may test for the type of node that the mouse
                                              // is over or any other contextual information.

              // Since the event handler wants to handle events for this context it
              // must tell its filter to accept all incoming events.
              getMouseFilter().acceptAllEventTypes();

          } else {

              // Since the event handler does not want to handle events for this context it
              // must tell its filter to reject all incoming events.
              getMouseFilter().rejectAllEventTypes();

              // But then it must tell its event handler to accept mouse pressed events so that
              // it will have a chance to handle the next filtered mouse down event that will bring a
              // new context with it.
              getMouseFilter().setIsAcceptingMousePressed(true);
          }
      }
 

Author:

Jesse Grosjean

See Also:

ZMouseFilter

fFilteredEventDispatcher

protected ZFilteredEventHandler.ZFilteredEventDispatcher fFilteredEventDispatcher

fMouseFilter

protected ZMouseFilter fMouseFilter

ZFilteredEventHandler

public ZFilteredEventHandler(ZSceneGraphObject aFilteredMouseEventSource)

Constructs a new ZFilteredEventHandler.

Parameters:

aFilteredMouseEventSource - the source for filtered ZMouseEvents and ZMouseMotionEvents. See the class comment to customize this behavior.

ZFilteredEventHandler

public ZFilteredEventHandler(ZSceneGraphObject aFilteredMouseEventSource,
                             ZCanvas aFilteredKeyEventSource)

Constructs a new ZFilteredEventHandler.

Parameters:

aFilteredMouseEventSource - the source for filtered ZMouseEvents and ZMouseMotionEvents. See the class comment to customize this behavior.

aFilteredKeyEventSource - the source for filtered KeyEvents. See the class comment to customize this behavior.

setMouseFilter

public void setMouseFilter(ZMouseFilter aMouseFilter)

Set the mouse filter that is used to filter events before they are delivered to this event handler's "filtered*" methods.

Parameters:

aMouseFilter - the new filter for this event handler to use.

getMouseFilter

public ZMouseFilter getMouseFilter()

Returns the filter currently in effect for this event handler. If no filter has been set then a new filter that accepts all events will be created and returned.

Returns:

the filter that is currently in effect.

wantsKeyEvents

protected boolean wantsKeyEvents()

Return true if the event handler should register with the key event source for KeyEvents. The default behavior is to return true if the key event source is not null, false otherwise. This method is called from within setActive to determine if this event handler should register with the key event source.

Returns:

true if this event handler wants to receive key events.

wantsMouseEvents

protected boolean wantsMouseEvents()

Return true if the event handler should register with the mouse event source for ZMouseEvents. The default behavior is to return true if the mouse event source is not null, false otherwise. This method is called from within setActive to determine if this event handler should register for mouse events from the mouse event source.

Returns:

true if this event handler wants to receive mouse events.

wantsMouseMotionEvents

protected boolean wantsMouseMotionEvents()

Return true if the event handler should register with the mouse event source for ZMouseMotionEvents. The default behavior is to return true if the mouse event source is not null, false otherwise. This method is called from within setActive to determine if this event handler should register for mouse motion events from the mouse event source.

Returns:

true if this event handler wants to receive mouse motion events.

getFilteredMouseEventSource

public ZSceneGraphObject getFilteredMouseEventSource()

Return the current source for mouse events.

Returns:

the source for mouse events.

setFilteredMouseEventSource

public void setFilteredMouseEventSource(ZSceneGraphObject aFilteredMouseEventSource)

Set the current source for mouse events.

getFilteredKeyEventSource

public ZCanvas getFilteredKeyEventSource()

Return the current source for filtered key events.

Returns:

the source for filtered key events.

setFilteredKeyEventSource

public void setFilteredKeyEventSource(ZCanvas aFilteredKeyEventSource)

Set the current source for key events.

isActive

public boolean isActive()

Determines if this event handler is active. An active event handler is registered with its event sources for events. An inactive event handler is not registered with its event sources and so will not receive events.

Specified by:

isActive in interface ZEventHandler

Returns:

true if active.

setActive

public void setActive(boolean active)

Specifies whether this event handler is active or not. An active event handler is registered with its event sources for events. An inactive event handler is not registered with its event sources and so will not receive events.

Specified by:

setActive in interface ZEventHandler

Parameters:

active - true to make this event handler active.

getCurrentFilteredMouseEvent

public ZMouseEvent getCurrentFilteredMouseEvent()

Return the current filtered mouse event.

Returns:

the current filtered mouse event.

getCurrentSelection

public java.util.Collection getCurrentSelection()

Utility method for use by subclasses that operate on the current selection. This implementation returns all selected nodes viewed from the top camera.

Returns:

the current selection as viewed from the top camera from the last event, or if no last event exists return the current selection starting at the root of the filtered key event souce. If that is also null return an empty collection.

getInteractionCamera

public ZCamera getInteractionCamera()

Return the camera that should be used for camera interactions for the current event. The default implementation returns the bottom camera from the current filtered mouse events scene graph path.

Returns:

the camera that should be used for camera interactions such as zooming or panning.

getTopCamera

public ZCamera getTopCamera()

Return the to camera for the current event.

Returns:

the camera top camera for the current event..

getFilteredEventDispatcher

public ZFilteredEventHandler.ZFilteredEventDispatcher getFilteredEventDispatcher()

Return the event dispatcher being used by this filtered event handler. If you need to send an event directly to this event handler but still want it filtered then you should use this.

filteredKeyPressed

protected void filteredKeyPressed(java.awt.event.KeyEvent e)

Invoked when a key is pressed on the key event souce and the event filter accepts the event.

Parameters:

e - the filtered key pressed event accepted by the event filter.

filteredKeyReleased

protected void filteredKeyReleased(java.awt.event.KeyEvent e)

Invoked when a key is released on the key event souce and the event filter accepts the event.

Parameters:

e - the filtered key released event accepted by the event filter.

filteredKeyTyped

protected void filteredKeyTyped(java.awt.event.KeyEvent e)

Invoked when a key is typed on the key event souce and the event filter accepts the event.

Parameters:

e - the filtered key typed event accepted by the event filter.

filteredMouseClicked

protected void filteredMouseClicked(ZMouseEvent e)

Invoked when the is clicked the mouse event souce and the current event filter accepts the event.

Parameters:

e - the filtered key typed event accepted by the event filter.

filteredMouseDragged

protected void filteredMouseDragged(ZMouseEvent e)

Invoked when a mouse button is pressed on the mouse event source and then dragged if the current event filter accepts the event.

Mouse drag events will continue to be delivered to the event source until the mouse button is released (regardless of whether the mouse position is within the bounds of the event source).

Parameters:

e - the filtered mouse dragged event.

filteredMouseEntered

protected void filteredMouseEntered(ZMouseEvent e)

Invoked when the mouse enters the mouse event souce and the current event filter accepts the event.

Parameters:

e - the filtered mouse entered event.

filteredMouseExited

protected void filteredMouseExited(ZMouseEvent e)

Invoked when the mouse exits the mouse event souce and the current event filter accepts the event.

Parameters:

e - the filtered mouse exited event.

filteredMouseMoved

protected void filteredMouseMoved(ZMouseEvent e)

Invoked when the mouse button is moved on the event source (with no buttons no down) and the current event filter accepts the event.

Parameters:

e - the filtered mouse moved event.

filteredMousePressed

protected void filteredMousePressed(ZMouseEvent e)

Invoked when the mouse button is pressed on the event source and the current event filter accepts the event.

Parameters:

e - the filtered mouse pressed event.

filteredMouseReleased

protected void filteredMouseReleased(ZMouseEvent e)

Invoked when the mouse button is released on the event source and the current event filter accepts the event.

Parameters:

e - the filtered mouse released event.