For an illustration of how to create a custom controller, see the sample lightspeed.customization.controller.

Implementing a chainable controller

Keep the following pointers in mind when you implement a chainable controller:

  • Take care when you implement handleAWTEventImpl. Events that are handled by one controller should not be passed on to other controllers. Therefore:

    • Make the method return null if the controller handles the event.

    • In the other case, if a controller does not use an event, make the method return the event so that the next controller gets a chance to handle it.

  • Some events are tightly coupled, and should be handled by the same controller. A typical example is a mouse-pressed event, followed by a couple of mouse-dragged events, and finally, a released event. To let one controller deal with this sequence of events, you can make a controller hold on to a pressed event, and only delegate to the next controller if it also receives a dragged event.

Creating a custom touch controller

To help you create touch controllers, LuciadLightspeed offers ALspTouchController, a base class that simplifies the process of writing your own touch controllers. This base class provides three abstract methods that allow you to indicate what points will be handled by the controller, and how to react to changes at those points:

  • touchPointAvailable: called each time a new touch point becomes available. It determines which touch points are handled by the controller.

  • touchPointMoved: called whenever one of the tracked touch points has moved. It allows you to stop tracking certain points.

  • touchPointWithDrawn: called each time a touch point is no longer available. Similar to the touchPointMoved method, it allows you to stop the tracking of certain points by this controller.

If your custom controller is tracking touch points, you have a number of utility methods at your disposal to retrieve the original, previous, and current locations of the tracked points. See the API reference documentation for more information about ALspTouchController.

Creating a tooltip controller

The creation of a custom tooltip controller is demonstrated in the lightspeed.customization.controller sample. This controller shows an information panel when the mouse cursor hovers over an object.

custom controller tooltip
Figure 1. The lightspeed.customization.controller sample

Program: Implementation of the custom tooltip controller shows how the tooltip controller is implemented in general, and the handleAWTEventImpl method in particular. On a mouse-moved or mouse-dragged event, the tooltip panel is either moved, unless the mouse cursor does not touch any object. In that case, the tooltip panel is removed. A mouse-exited event removes the tooltip as well. No events are consumed, because they may still be of use to other controllers. If a pan controller has been included in the chain, for example, it will still receive mouse-dragged events.

Program: Implementation of the custom tooltip controller (from samples/lightspeed/customization/controller/InformationPanelController) 
@Override
public AWTEvent handleAWTEventImpl(AWTEvent aAWTEvent) {
  // Handle mouse events only
  if (aAWTEvent instanceof MouseEvent) {
    MouseEvent event = (MouseEvent) aAWTEvent;

    if (event.getID() == MouseEvent.MOUSE_MOVED || event.getID() == MouseEvent.MOUSE_DRAGGED) {
      // move the information panel to the mouse cursor
      movePanel(event.getX(), event.getY());
    } else if (event.getID() == MouseEvent.MOUSE_EXITED) {
      // remove the information panel if the mouse is outside the view
      removePanel();
    }
  }

  // Do not consume events, in order to make it possible for other controllers to use them.
  return aAWTEvent;
}

Note that coordinates obtained from an input event, a MouseEvent for example, are expressed in so-called toolkit coordinates. If DPI scaling is enabled in the host operating system, toolkit coordinates are different from Lightspeed view coordinates. When you are using the API to transform points between, for instance, cursor positions and geographic coordinates, it is important to be aware of this distinction. ALspViewXYZWorldTransformation provides the toolkitPoint2ViewSFCT, toolkitPoint2WorldSFCT, viewPoint2ToolkitSFCT and worldPoint2ToolkitSFCT methods facilitate this. Support high-resolution displays on a Lightspeed map provides further information about DPI scaling.