Package com.luciad.view.gxy.controller.touch

Class ALcdGXYTouchChainableController

java.lang.Object
com.luciad.view.gxy.controller.ALcdGXYController
com.luciad.view.gxy.controller.ALcdGXYChainableController
com.luciad.view.gxy.controller.touch.ALcdGXYTouchChainableController
All Implemented Interfaces:
ILcdAWTEventListener, ILcdStatusSource, ILcdGXYChainableController, ILcdGXYController, Serializable
Direct Known Subclasses:
ALcdGXYConfinedTouchChainableController
public abstract class ALcdGXYTouchChainableController extends ALcdGXYChainableController implements ILcdAWTEventListener

Extension of ALcdGXYChainableController for TLcdTouchEvent instances. It provides support for tracking multiple TLcdTouchPoints and allows to react when a point is created / moves (beyond a certain threshold) / is removed.

All incoming events are passed down the chain to the next controller. In case of TLcdTouchEvents, the consumed state of the different TLcdTouchPoints contained in the event will be updated according to the points this controller is handling.

Implementations of this class can track touch points by implementing touchPointAvailable, touchPointMoved, and touchPointWithdrawn as follows:

  • Every time a new touch point becomes available, the touchPointAvailable method is called. This method determines which points will be tracked by this controller. A touch point becomes available when:

    • a TLcdTouchPoint is created and not consumed by a previous controller in the chain.
    • the consumed state of a TLcdTouchPoint switches from true to false.

  • If one of the tracked points moves or is withdrawn, the touchPointMoved and touchPointWithdrawn methods are respectively called. At both occasions, it is possible to indicate certain points should no longer be tracked by this controller. A TLcdTouchPoint is withdrawn when:

    • the TLcdTouchPoint is removed.
    • the consumed state of a TLcdTouchPoint switches from false to true.

The behavior of this controller is illustrated below with an example of two chained ALcdGXYTouchChainableControllers: the first controller will only start tracking when it can track two TLcdTouchPoints, and stops tracking as soon as one of those points is withdrawn. It will never track more than two points at the same time. The second controller only tracks one point. Similar to the first controller, it will stop tracking as soon as the tracked point is withdrawn, and never track more than one point at the same time.

Note: in the sequence diagram, the following conventions are used:

As can be seen in the sequence diagram, the first controller does not track the first incoming point, since it will only start tracking when two points are available (step 2). The event is forwarded to the second controller, which accepts the point (step 4). As a result, the event forwarded by the second controller still describes the DOWN of point 0, but the point has been marked as consumed (step 5).

When the second point becomes available to the first controller, it indicates it will track them both (step 7). The event forwarded to the second controller includes both points, but both are marked as consumed (step 8). Since touch point 0 has been consumed, the touchPointWithdrawn method is called for the second controller, indicating the point with ID 0 is no longer available (step 9).

When a move event is passed to the controller, it will only call the touchPointMoved method when the controller is actually tracking the point, and only called with the points the controller is tracking. This is illustrated in step 17, where touch point 2 is not passed to the touchPointMoved method. When the event describing the move of point 2 arrives at the first controller (step 20), the event is forwarded to the second controller (step 21) without calling the touchPointMoved method since the point is not tracked by the first controller.

When touch point 1 is removed (step 24), the touchPointWithDrawn is called. The controller indicates in step 25 it will no longer track point 0 (since it can only handle two points), hence the event forwarded to the second controller indicates point 0 is no longer consumed (step 26). Since point 0 now becomes available, the touchPointAvailable is called with both points 0 and 2 (step 27).

Since:
10.0
See Also:

  • Constructor Details

    • ALcdGXYTouchChainableController

      protected ALcdGXYTouchChainableController()
      Default constructor.

  • Method Details

    • handleAWTEvent

      public void handleAWTEvent(AWTEvent aEvent)
      This is method is called when the target of the listener has a new AWTEvent available.

      When the event describes the creation of a touch point, the touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will be called, allowing to indicate which touch points to track. The touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will also be called if a TLcdTouchPoint was previously marked as consumed and is no longer consumed in aEvent.

      When the event describes the move of a touch point tracked by this controller, the touchPointMoved(java.util.List, com.luciad.input.touch.TLcdTouchPoint) will be called if the threshold is exceeded.

      When the event describes the removal of a touch point, the touchPointWithdrawn(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will be called. The touchPointWithdrawn(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will also be called when aEvent indicates one of the tracked points is consumed.

      All incoming events will be forwarded to the next controller. In case of TLcdTouchEvents, the consumed state of the different TLcdTouchPoints contained in the event will be adjusted according to the points this controller is handling. Right before any TLcdTouchEvent is forwarded to the next controller, the handleEventImpl method is called.

      Consult the class javadoc for an example of how this class handles TLcdTouchEvents.

      Typically this method should not be overridden. Override touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint), touchPointMoved(java.util.List, com.luciad.input.touch.TLcdTouchPoint) or touchPointWithdrawn(java.util.List, com.luciad.input.touch.TLcdTouchPoint) instead.

      If aEvent is not an instance of TLcdTouchEvent, it will simply be forwarded to the next controller without affecting this controller.

      Specified by:
      handleAWTEvent in interface ILcdAWTEventListener
      Parameters:
      aEvent - The event to be handled.
      See Also:

    • touchPointMoved

      protected abstract List<TLcdTouchPoint> touchPointMoved(List<TLcdTouchPoint> aTrackedTouchPoints, TLcdTouchPoint aTouchMoved)

      This method is called when one of the touch points, used by this controller, is moved beyond the threshold and allows to react accordingly.

      aTouchMoved is the TLcdTouchPoint which has moved, while aTrackedTouchPoints contains all TLcdTouchPoints this controller is currently tracking (including aTouchMoved). All of these points are non-consumed.

      This method allows to indicate that certain touch points should no longer be tracked by this controller. It does so by returning a List containing all TLcdTouchPoint instances which should be tracked by this controller. If a TLcdTouchPoint which is currently tracked is omitted from the List, that touch point will be made available to the rest of the chain as explained in the class javadoc.

      A possible use case is a touch-and-hold controller, which does not expect move events. The touch-and-hold controller can claim the touch point when it is created, but when the point starts moving it can decide it cannot handle it.

      Parameters:
      aTrackedTouchPoints - List containing all TLcdTouchPoints currently tracked by this controller. It is possible to modify this List and return it instead of creating a new List.
      aTouchMoved - the TLcdTouchPoint that has moved
      Returns:
      a List containing all TLcdTouchPoints this controller should keep tracking. All TLcdTouchPoint instances contained in this List must be contained in aTrackedTouchPoints. May be an empty List, but not null.
      See Also:

    • getOriginalLocations

      public List<Point> getOriginalLocations()

      Returns the original locations of the touch points this controller is tracking. These are the locations of the points when they were passed to the touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method). The locations are expressed in view AWT coordinates.

      The order of the points in the returned list matches the order of the lists returned in getPreviousLocations() and getCurrentLocations(). The same order is applied on getTouchPointIDs().

      Returns:
      the original locations of the touch points this controller is tracking. The List is empty when no points are currently tracked.

    • getPreviousLocations

      public List<Point> getPreviousLocations()

      Returns the locations of the touch points this controller is tracking during the previous event. The locations are expressed in view AWT coordinates.

      The order of the points in the returned list matches the order of the lists returned in getOriginalLocations() and getCurrentLocations(). If a point was not tracked during the previous event, its original location is used instead. The same order is applied on getTouchPointIDs().

      Returns:
      the previous locations of the touch points this controller is tracking. The List is empty when no points are currently tracked.

    • getCurrentLocations

      public List<Point> getCurrentLocations()

      Returns the current locations of the touch points this controller is tracking. Locations are expressed in view AWT coordinates.

      The order of the points in the returned list matches the order of the lists returned in getOriginalLocations() and getPreviousLocations(). The same order is applied on getTouchPointIDs().

      Returns:
      the current locations of the touch points this controller is tracking. The List is empty when no points are currently tracked.

    • getTouchPointIDs

      public List<Long> getTouchPointIDs()

      Returns a list containing the touch point IDs of the touch points used by this controller.

      The order of the IDs is the order in which the points were passed to the touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method.

      Returns:
      a list containing the touch point IDs of the touch points this controller is using. The List is empty when no points are currently tracked.

    • touchPointAvailable

      protected abstract List<TLcdTouchPoint> touchPointAvailable(List<TLcdTouchPoint> aTouchPoints, TLcdTouchPoint aTouchDown)

      This method is called every time a new touch point is created or becomes available and allows to react accordingly.

      aTouchDown is the TLcdTouchPoint which has been created, while aTouchPoints contains all available TLcdTouchPoints (including aTouchDown). All of these points are non-consumed.

      This method allows to indicate which points should be tracked by this controller by returning them in a List. If a TLcdTouchPoint which is currently tracked is omitted from the List, that touch point will be made available to the rest of the chain as explained in the class javadoc.

      Parameters:
      aTouchPoints - A List containing all available TLcdTouchPoint instances. This list will include aTouchDown. Note that some of these TLcdTouchPoints can already be tracked by this controller (see getTouchPointIDs()). It is possible to modify this List and return it instead of creating a new List.
      aTouchDown - The descriptor of the touch point which has been created or removed. The state of the descriptor will always be DOWN. Note that this descriptor is included in aTouchPoints.
      Returns:
      a List containing all TLcdTouchPoint instances which should be tracked by this controller. All TLcdTouchPoint instances contained in this List must be contained in aTouchPoints. May be an empty List, but not null.

    • touchPointWithdrawn

      protected abstract List<TLcdTouchPoint> touchPointWithdrawn(List<TLcdTouchPoint> aTouchPoints, TLcdTouchPoint aTouchUp)

      This methods is called every time a tracked touch point is removed or consumed and allows to react accordingly.

      aTouchUp is the TLcdTouchPoint which has been removed, while aTouchPoints contains all TLcdTouchPoints this controller is currently tracking (including aTouchUp). All of these points are non-consumed.

      This method allows to indicate that certain touch points should no longer be tracked by this controller. It does so by returning a List containing all TLcdTouchPoint instances which should be tracked by this controller. If a TLcdTouchPoint which is currently tracked is omitted from the List, that touch point will be made available to the rest of the chain as explained in the class javadoc.

      Parameters:
      aTouchPoints - A List containing all available TLcdTouchPoint instances, including aTouchUp. It is possible to modify this List and return it instead of creating a new List.
      aTouchUp - The touch point which has been removed. The state of the descriptor will always be UP. Note that this descriptor is included in aTouchPoints.
      Returns:
      a List containing all TLcdTouchPoints this controller should keep tracking. All TLcdTouchPoint instances contained in this List must be contained in aTouchPoints. May be an empty List, but not null.
      See Also:

    • getMoveThreshold

      public int getMoveThreshold()

      Returns the current threshold for move events.

      The touchPointMoved(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will only be called if the point moves further then the threshold in either the X or Y direction, and the same applies for the update of the previous and current locations.

      The default value for this property is 0, which means every move of a tracked touch point will be handled.

      Returns:
      the current threshold for move events
      See Also:

    • setMoveThreshold

      public void setMoveThreshold(int aMoveThreshold)

      Sets the threshold for move events.

      The touchPointMoved(java.util.List, com.luciad.input.touch.TLcdTouchPoint) method will only be called if the point moves further then the threshold in either the X or Y direction, and the same applies for the update of the previous and current locations.

      The new value of the threshold will not affect any events which arrived at the controller prior to the change in threshold.

      The default value for this property is 0, which means every move of a tracked touch point will be handled.

      Parameters:
      aMoveThreshold - the threshold for move events. Must be positive.
      See Also:

    • paintImpl

      protected void paintImpl(Graphics aGraphics)
      Description copied from class: ALcdGXYChainableController
      The specific implementation of paint for this controller.
      Overrides:
      paintImpl in class ALcdGXYChainableController
      Parameters:
      aGraphics - the graphics to be used for painting.

    • handleEventImpl

      protected void handleEventImpl(TLcdTouchEvent aTouchEvent)

      This method is called right before a TLcdTouchEvent is forwarded to the next controller in the chain. The default implementation of this method is empty.

      Parameters:
      aTouchEvent - the TLcdTouchEvent which will be forwarded to the next controller. The consumed state of the TLcdTouchPoints is already updated.