The source code of all examples is included in the JGameGrid distribution.

Ex22: Mouse Events Using a GGMouseTouchListener

In many games the player interacts with actors using the mouse. By clicking on a actor's image the actor's reference must be known to handle the click event accordingly. When using a coarse game grid this is easily done by identifying the cell using the current mouse cursor coordinates. As explained in Ex06 (lesson 5) the clicked cell location is returned by toLocationInGrid() and an actor in this cell by getOneActorAt() or getActorsAt(). The mouse event callback used for this example resides in the class Switch:

public boolean mouseEvent(GGMouse mouse)
{
  Location location =
    gameGrid.toLocationInGrid(mouse.getX(), mouse.getY());
  if (location.equals(getLocation()))
    showNextSprite();
  bulb.show(getIdVisible());
  gameGrid.refresh();
  return false;
}

This concept fails when fine-grained game grids are used, because in this case the location of an actor corresponds to one or a few pixel that are hardly hit by the mouse. To get mouse events when the mouse "touches" the actor image a GGMouseTouchListener must be used. The well-known types of mouse events are supported (press, release, click, double-click, move, drag, enter, leave). For each sprite image a specific "mouse touch area" is used where the mouse events are active (e.g. enter and leave will be triggered when entering/leaving this area). As default the mouse touch area corresponds to the non-transparent pixels of the sprite image. With setMouseTouchRectangle() or setMouseTouchCircle() the touch area may be changed to a rectangle or circle located anywhere with respect to the sprite image. Evidently when the actor moves or rotates, the mouse touch area moves or rotates accordingly.

The notification method mouseTouched(), called when a touch event with an actor occurs, reports the actor's reference, a GGMouse reference and a Point reference that contains the coordinates of the mouse cursor with respect to the sprite image (zero at center of sprite). The actor reference can may used to call all actor's public methods directly. This simplifies and clarifies the code as seen in the revised version of the class Switch:

A MouseTouchListener is registered for every Switch instance. You can register as many MouseListeners and MouseTouchListeners as you like, but all MouseListeners should return false, to prevent that the mouse events are "swallowed". To limit the active area to the small part of the switch image, we use a rectangular touch area:

Execute the program locally using WebStart and check the mouse touch area.

The next example shows how simple it is to drag an actor in a pixel-based game grid. When pressing the mouse, the location of the hot spot displacement is saved. While dragging, the actor's new location is set by using the current cursor position and the saved displacement.

Execute the program locally using WebStart

The user must take some care to drag the image slowly because if the mouse is moved quickly outside the image, no touch event is fired anymore. To overcome this difficulty, the drag event should be generated by a MouseListener. The improved version no works perfectly.

Execute the program locally using WebStart.

For game grids with a coarse cell layout, the same approach let you drag the actor smoothly from cell to cell. Normally actors are centered in the middle of a cell, but by using setLocationOffset() or setPixelLocation() the displayed sprite image may be displaced. When lRelease is fired, the actor is "dropped" at its standard location in the middle of the cell that currently contains the center of the actor image.

The extra boolean parameter in addMouseTouchListener() ensures that if there are several actors laying on top of each other, only the actor on top gets the mouse events. Moreover in the GGMouse.lPress event, the current touchActor is set on top, so while dragging, its image appears always on top of other actors.

Execute the program locally using WebStart.