Mediators

From Emitrom

Jump to: navigation, search

Back to Index


Mediators can be used to intercept the events in the Viewport of a LienzoPanel, e.g. for zooming, panning or rubberbanding purposes.

Mediators must implement the IMediator interface and are stored in a Mediators object that maintains a list (or stack) of these mediators.

Hand-point.png Mediators were introduced in Lienzo version 1.1

Hand-point.png Viewport Javadoc Hand-point.png Mediators Javadoc Hand-point.png IMediator Javadoc

Contents

Mediators

The mediators for a Viewport can be accessed via the ViewPort.getMediators() method. The returned Mediators object maintains a list (or stack) of IMediators.

To insert a new mediator into the start of the list (at position 0), use the Mediators.push() or Viewport.pushMediator() methods. To remove the first one, use the Mediators.pop() method. The Mediators.add() and Mediators.remove() methods can be used for more finer grained control.

The mediators are processed in the order of the (internal) list. When an event occurs in the Viewport, it first invokes the handleEvent method of each mediator, until one of them returns true (indicating that it accepted and processed the event.) See Events for the possible events that can be handled by a mediator.

If there are no mediators, or none of them return true, the toolkit will determine if any primitives need to be dragged (see Dragging) or whether they have event handlers installed (see Events.)

IMediator

The Lienzo toolkit provides several built-in mediators (see below), but you can create your own by implementing the IMediator interface. You can also extend AbstractMediator, which provides some common behavior, such as event filters and access to the Viewport.

Hand-point.png IMediator Javadoc Hand-point.png AbstractMediator Javadoc

Zooming

Lienzo provides several built-in mediators for zoom support:

Mediator Description Javadocs
MouseBoxZoomMediator Zooms in when the user drags a rectangular area

MouseBoxZoomMediator

MouseWheelZoomMediator Zooms in or out when the mouse wheel is moved

MouseWheelZoomMediator

MouseSwipeZoomMediator Zooms in or out when the user drags a point (in the viewport) to the left or right

MouseSwipeZoomMediator

When using these Mediators, make sure to set reasonable values for the minScale and maxScale attributes. The default values allow you to zoom in/out indefinitely which may cause problems when you try to zoom back the other way.

Each zoom mediator modifies the Viewport Transform. See ViewportTransformChangedHandler for how to receive notifications when this Transform changes.

Panning

Panning refers to the horizontal and/or vertical scrolling of one or more Layers that are wider than the Viewport, similar to dragging the mouse in Google Maps.

Lienzo provides the following built-in mediators for pan support:

Mediator Description Javadocs
MousePanMediator Scrolls the Layers in the Viewport when the mouse is dragged

MousePanMediator

Each pan mediator modifies the Viewport Transform. See ViewportTransformChangedHandler for how to receive notifications when this Transform changes.

Event Filters

Some of the built-in mediators provide an easy way to filter events, e.g. they will only react to events when a certain mouse button or modifier key is pressed.

Multiple event filters can be combined with EventFilter.and(), EventFilter.or() and EventFilter.not() operations. To write a custom event filter, simply implement the IEventFilter interface.

The following event filters are provided by the EventFilter class:

Filter Event Type Description
ANY any event accepts all events
BUTTON_LEFT mouse event whether the left mouse button is pressed
BUTTON_MIDDLE mouse event whether the middle mouse button is pressed
BUTTON_RIGHT mouse event whether the right mouse button is pressed
CONTROL mouse event whether the Control key is pressed
SHIFT mouse event whether the Shift key is pressed
ALT mouse event whether the Alt key is pressed
META mouse event whether the Meta key is pressed

Hand-point.png EventFilter Javadoc Hand-point.png IEventFilter Javadoc

Example

The following mediator zooms in and out when the mouse wheel is moved and when both the Shift and Control keys are pressed:

viewport.pushMediator(new MouseWheelZoomMediator(EventFilter.SHIFT, EventFilter.CONTROL));

ViewportTransformChangedHandler

The zoom and pan mediators all modify the Viewport Transform. To receive notifications when that happens, register a ViewportTransformChangedHandler:

viewport.addViewportTransformChangedHandler(new ViewportTransformChangedHandler() 
{
    @Override
    public void onViewportTransformChanged(ViewportTransformChangedEvent event)
    {
        // insert code here...
    }
});

Hand-point.png ViewportTransformChangedHandler Javadoc Hand-point.png ViewportTransformChangedEvent Javadoc

Extending the Built-in Mediators

By default, the built-in zoom and pan mediators affect the Viewport Transform, which in turn changes how the "zoomable" Layers are drawn.

It is possible, however, to zoom or pan in non-zoomable Layers by extending a mediator:

final Layer layer = new Layer();
layer.setZoomable(false);
viewport.getScene().add(layer);
viewport.pushMediator(new MouseWheelZoomMediator() 
{
  @Override
  protected void redraw()
  {
     layer.draw();
  }

  @Override
  protected Transform getTransform()
  {
     return layer.getTransform();
  }

  @Override
  protected void setTransform(Transform transform)
  {
    layer.setTransform(transform);
  }
});
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox