Mouse Events

Since version 2.0, JSGL offers API for handling mouse events. This allows you to add interactivity to your applications. Mouse events can be captured on:

• elements (graphics primitives such as line, circle, etc.),
• drawing panel (canvas, i.e. the jsgl.Panel) object.

Currently, following mouse events are supported:

• mouse move ā€“ the mouse pointer was moved in any direction across the element/panel,
• mouse down ā€“ a mouse button was pressed when the pointer was on the element/panel,
• mouse up ā€“ a mouse button was released when the pointer was on the element/panel,
• click ā€“ the element/panel has been clicked,
• double-click ā€“ the element/panel has was clicked twice,
• mouse over ā€“ the mouse pointer was moved from outside the element/panel onto it,
• mouse out ā€“ the mouse pointer was moved out of the element/panel.

The mouse events (represented by jsgl.MouseEvent class) come with:

• [x,y] coordinates,
• source element object on which the event has been triggered.

All the JSGL element (line, polygon, imageā€¦) classes inherit from jsgl.elements.AbstractElement class. Both the jsgl.Panel and the jsgl.elements.AbstractElement classes provide methods for:

• adding listener functions:
  • .addClickListener(listener: Function),
  • .addDoubleClickListener(listener: Function),
  • .addMouseDownListener(listener: Function),
  • .addMouseUpListener(listener: Function),
  • .addMouseMoveListener(listener: Function),
  • .addMouseOverListener(listener: Function),
  • .addMouseOutListener(listener: Function),
• removing listener functions.
  • .removeClickListener(listener: Function),
  • .removeDoubleClickListener(listener: Function),
  • .removeMouseDownListener(listener: Function),
  • .removeMouseUpListener(listener: Function),
  • .removeMouseMoveListener(listener: Function),
  • .removeMouseOverListener(listener: Function),
  • .removeMouseOutListener(listener: Function).

A listener function is an ordinary JavaScript function which takes jsgl.MouseEvent object as an argument. By example, you might like to echo the coordinates whenever something is clicked:

function clickHandler(eventArgs) {
  window.alert(eventArgs.getLocation());
}

Supposing you have and instance of jsgl.Panel object called myPanel, you may add the listener using its .addClickListener method:

myPanel.addClickListener(clickHandler);

Using the above code, a prompt with coordinates will be shown whenever the drawing canvas is clicked. This is especially useful when you want to capture events on the entire canvas, no matter whether elements are onto it or not.

Also, you can capture events at the level of JSGL elements:

myCircle.addClickListener(clickHandler);

This time, coordinates printed are measured in the parent coordinate space of myCircle, which may be:

• jsgl.Panel object (coordinates in the drawing canvas),
• jsgl.elements.GroupElement object (coordinates in the group, which may be translated to parent coordspaces).

With each clickable object (element/panel), for each type of event, there is a collection of handlers associated. An event handler is nothing but JavaScript function object. The handlers can be registered to and unregistered from listening to events dynamically.

We will illustrate this on simple mouse-over/out example, where a circle changes its appearance as mouse pointer enters/leaves it:

/* Instantiate & Init the circle */
var myCircle = myPanel.createCircle();
myCircle.setCenterLocationXY(100, 100);
myCircle.setRadius(50);
myCircle.getStroke().setColor('red');
myCircle.getFill().setColor('#3f3');
 
myPanel.addElement(myCircle);
 
/* The dim function to be called when the mouse pointer
   leaves the circle. */
var dim = function() {
      with(myCircle.getStroke()) {
        setWeight(3);
        setOpacity(0.5);
        setDashStyle(jsgl.DashStyles.SOLID);
      }
      myCircle.getFill().setOpacity(0.5);
    };
 
/* The highlight function to be called when the mouse pointer
   enters the circle. */
var highlight = function() {
      with(myCircle.getStroke()) {
        setWeight(5);
        setOpacity(1.0);
        setDashStyle(jsgl.DashStyles.DASH);
      }
      myCircle.getFill().setOpacity(1)
    };
 
/* Call dim() to init the correct styling. */
dim();
 
/* Register highlight function as mouse-over listener. */
myCircle.addMouseOverListener(highlight);
 
/* Register dim function as mouse-out listener. */
myCircle.addMouseOutListener(dim);

The above-code produces the following result:

jsgl.MouseEvent class