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



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.)


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


Lienzo provides several built-in mediators for zoom support:

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


MouseWheelZoomMediator Zooms in or out when the mouse wheel is moved


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


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 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


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


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));


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

viewport.addViewportTransformChangedHandler(new ViewportTransformChangedHandler() 
    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();
viewport.pushMediator(new MouseWheelZoomMediator() 
  protected void redraw()

  protected Transform getTransform()
     return layer.getTransform();

  protected void setTransform(Transform transform)
Personal tools