public abstract class ALcdGXYTouchChainableController extends ALcdGXYChainableController implements ILcdAWTEventListener
Extension of ALcdGXYChainableController
for TLcdTouchEvent
instances. It provides support for tracking multiple TLcdTouchPoint
s 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
TLcdTouchEvent
s, the consumed state of the different TLcdTouchPoint
s 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:
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 behavior of this controller is illustrated below with an example of two chained
ALcdGXYTouchChainableController
s: the first controller will only start tracking when
it can track two TLcdTouchPoint
s, 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:
TLcdTouchPoint
s are represented by a number (their ID) and a String (their TLcdTouchPoint.getState()). The String for the state is:
down
== TLcdTouchPoint.State.DOWN
moved
== TLcdTouchPoint.State.MOVED
up
== TLcdTouchPoint.State.UP
TLcdTouchPoint.State.STATIONARY
handleAWTEvent
methodsList
with TLcdTouchPoint
s is represented by the IDs of
the TLcdTouchPoint
s between angular brackets.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).
Modifier | Constructor and Description |
---|---|
protected |
ALcdGXYTouchChainableController()
Default constructor.
|
Modifier and Type | Method and Description |
---|---|
List<Point> |
getCurrentLocations()
Returns the current locations of the touch points this controller is tracking.
|
int |
getMoveThreshold()
Returns the current threshold for move events.
|
List<Point> |
getOriginalLocations()
Returns the original locations of the touch points this controller is tracking.
|
List<Point> |
getPreviousLocations()
Returns the locations of the touch points this controller is tracking during the previous
event.
|
List<Long> |
getTouchPointIDs()
Returns a list containing the touch point IDs of the touch points used by this controller.
|
void |
handleAWTEvent(AWTEvent aEvent)
This is method is called when the target of the listener has a new AWTEvent available.
|
protected void |
handleEventImpl(TLcdTouchEvent aTouchEvent)
This method is called right before a
TLcdTouchEvent is forwarded to the next
controller in the chain. |
protected void |
paintImpl(Graphics aGraphics)
The specific implementation of
paint for this controller. |
void |
setMoveThreshold(int aMoveThreshold)
Sets the threshold for move events.
|
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.
|
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.
|
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.
|
addStatusListener, appendGXYController, getNextGXYController, paint, removeStatusListener, setNextGXYController, startInteraction, startInteractionImpl, terminateInteraction, terminateInteractionImpl
asGXYController, fireStatusEvent, getCursor, getGXYView, getIcon, getName, getShortDescription, isTraceOn, registerInstance, retrieveGXYViewXYWorldTransformation, setClassTraceOn, setCursor, setGXYView, setIcon, setName, setShortDescription, setTraceOn, viewRepaint
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
getCursor, getIcon, getLayered, getName, getShortDescription, viewRepaint
protected ALcdGXYTouchChainableController()
public void handleAWTEvent(AWTEvent aEvent)
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
TLcdTouchEvent
s, the consumed state of the different TLcdTouchPoint
s
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
TLcdTouchEvent
s.
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.
handleAWTEvent
in interface ILcdAWTEventListener
aEvent
- The event to be handled.touchPointMoved(java.util.List, com.luciad.input.touch.TLcdTouchPoint)
,
touchPointAvailable(java.util.List, com.luciad.input.touch.TLcdTouchPoint)
,
touchPointWithdrawn(java.util.List, com.luciad.input.touch.TLcdTouchPoint)
,
handleEventImpl(com.luciad.input.touch.TLcdTouchEvent)
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 TLcdTouchPoint
s 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.
aTrackedTouchPoints
- List
containing all TLcdTouchPoint
s
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 movedList
containing all TLcdTouchPoint
s 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
.handleAWTEvent(java.awt.AWTEvent)
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()
.
List
is empty when no points are currently tracked.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()
.
List
is empty when no points are currently tracked.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()
.
List
is empty when no points are currently tracked.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.
List
is empty
when no points are currently tracked.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 TLcdTouchPoint
s (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.
aTouchPoints
- A List
containing all available TLcdTouchPoint
instances. This list will include aTouchDown
. Note that some
of these TLcdTouchPoint
s 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
.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
.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 TLcdTouchPoint
s 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.
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
.List
containing all TLcdTouchPoint
s 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
.handleAWTEvent(java.awt.AWTEvent)
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.
setMoveThreshold(int)
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.
aMoveThreshold
- the threshold for move events. Must be positive.getMoveThreshold()
protected void paintImpl(Graphics aGraphics)
ALcdGXYChainableController
paint
for this controller.paintImpl
in class ALcdGXYChainableController
aGraphics
- the graphics to be used for painting.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.
aTouchEvent
- the TLcdTouchEvent
which will be forwarded to the next
controller. The consumed state of the TLcdTouchPoint
s is already updated.