Package com.luciad.input.touch

Class TLcdTouchEvent

java.lang.Object
java.util.EventObject
java.awt.AWTEvent
com.luciad.input.TLcdAWTEvent
com.luciad.input.touch.TLcdTouchEvent
All Implemented Interfaces:
Serializable
public class TLcdTouchEvent extends TLcdAWTEvent

An extension of TLcdAWTEvent designed for input originating from a touch device. Where a TLcdTouchPoint describes changes in the state of a single touch point, this event describes changes in any of the currently tracked touch points of a touch device, and also contains the state of all unchanged touch points.

There exists a one-to-one mapping between changes in the touch points and these TLcdTouchEvent instances: every time the state or location of a touch point changes, an TLcdTouchEvent is generated. This means all TLcdTouchEvent instances contain exactly one TLcdTouchPoint with a State not equal to TLcdTouchPoint.State.STATIONARY. This specific TLcdTouchPoint can be retrieved with the getModifiedTouchPoint() method.

The associated component of the event is the component on which the first touch point occurred. Note that this does not mean that all touch points should be located within the bounds of that component. The event should be dispatched to this component.

It is possible that touch points of multiple users and/or touch input devices are available at the same time. However, an TLcdTouchEvent only describes the state of touch points related to a specific user and touch device.

All TLcdTouchEvent instances have a unique ID, similar to the TLcdTouchPoint instances. This ID is assigned when the first touch point is created and will remain the same until all touch points are removed. Once all touch points of a certain device and user are removed, the next created touch point will

  • generate a new TLcdTouchEvent with the same ID as the current event if and only if the new touch point increases the tap count of one of the previous removed touch points.
  • generate a new TLcdTouchEvent with an ID different from the one of the current event. The ID of the current event may be reused later on.

Note: the ID is only unique for a certain device and user combination. Other combinations may reuse the IDs.

Since:
10.0
See Also:

  • Field Details

    • TOUCH_EVENT_TYPE

      public static final int TOUCH_EVENT_TYPE
      The type of a TLcdTouchEvent.
      See Also:

    • UNKNOWN_TOUCH_DEVICE

      public static final long UNKNOWN_TOUCH_DEVICE

      Long specifying an unknown device. TLcdTouchEvent instances should use this value as getTouchDeviceID() device ID} when they are unable to identify the source device of the touch point.

      Note that all TLcdTouchEvent instances which use this value as device ID will be handled as if they originated from the same touch device.

      See Also:

    • UNKNOWN_TOUCH_DEVICE_USER

      public static final String UNKNOWN_TOUCH_DEVICE_USER

      String specifying an unknown user. TLcdTouchEvent instances should use this value as getUserID() user ID} when they are unable to identify the user of the event.

      Note that all TLcdTouchEvent instances originating from the same touch device which use this value as user ID will be handled as if they were caused by the same user.

      See Also:

  • Constructor Details

    • TLcdTouchEvent

      public TLcdTouchEvent(long aTouchEventID, Object aSource, List<TLcdTouchPoint> aTouchPointList, long aTouchDeviceID, String aUserID, long aTimeStamp)

      Create a new TLcdTouchEvent.

      Parameters:
      aTouchEventID - the unique ID of this event.
      aSource - the source component(an AWT Component or a JavaFX Node) that originated the event. Must not be null.
      aTouchPointList - the list of all touch points associated to this event. Must not be null and must not be empty. Exactly one instance must have a state different from TLcdTouchPoint.State.STATIONARY.
      aTouchDeviceID - the unique ID of the device which caused this event. In case the device cannot be identified, use UNKNOWN_TOUCH_DEVICE.
      aUserID - the unique ID of the user of the device which caused this event. In case the user of the device cannot be identified, use UNKNOWN_TOUCH_DEVICE_USER
      aTimeStamp - the time at which the event occurred. Expressed as the difference, measured in milliseconds, with midnight, January 1, 1970 UTC.
      Since:
      2020.0
      See Also:

  • Method Details

    • getID

      public int getID()

      The type of this events will always be TOUCH_EVENT_TYPE

      .
      Overrides:
      getID in class AWTEvent

    • getTouchPoints

      public List<TLcdTouchPoint> getTouchPoints()
      Returns an unmodifiable list of the associated TLcdTouchPoint instances.
      Returns:
      an unmodifiable list of the associated TLcdTouchPoint instances

    • getModifiedTouchPoint

      public TLcdTouchPoint getModifiedTouchPoint()
      Returns the TLcdTouchPoint instance which has been modified (the only TLcdTouchPoint with a state different from TLcdTouchPoint.State.STATIONARY).
      Returns:
      the TLcdTouchPoint instance which has been modified

    • getStationaryTouchPoints

      public List<TLcdTouchPoint> getStationaryTouchPoints()
      Returns a list containing all TLcdTouchPoint instances which describe a touch point that has remained stationary.
      Returns:
      a list containing all TLcdTouchPoint instances which describe a touch point that has remained stationary

    • getTouchDeviceID

      public long getTouchDeviceID()

      Returns the unique ID of the touch device which created the touch point described by this TLcdTouchEvent.

      All TLcdTouchEvent instances originating from the same input device should have the same device ID throughout the lifetime of the application.

      Returns:
      the unique ID of the touch device.
      See Also:

    • getUserID

      public String getUserID()

      Returns the unique ID of the user of the touch device who created the touch point described by this TLcdTouchEvent.

      All TLcdTouchEvent instances originating from the same user on a specific touch device should have the same user ID throughout the lifetime of the application. This ID must not be used by another user on the same device. It may be reused by a user on another device.

      Returns:
      the unique ID of the user of the touch device.
      See Also:

    • getTimeStamp

      public long getTimeStamp()

      Returns the time when the event occurred. Expressed as the difference, measured in milliseconds, with midnight, January 1, 1970 UTC.

      Returns:
      the time when the event occurred

    • getTouchEventID

      public long getTouchEventID()

      Returns the unique ID of this event.

      All TLcdTouchEvent instances have a unique ID, similar to the TLcdTouchPoint instances. This ID is assigned when the first touch point is created and will remain the same until all touch points are removed. Once all touch points of a certain device and user are removed, the next created touch point will

      • generate a new TLcdTouchEvent with the same ID as the current event only if the new touch point increases the tap count of one of the previous removed touch points.
      • generate a new TLcdTouchEvent with an ID different as the one of the current event. The ID of the current event may be reused later on.

      Note: the ID is only unique for a certain device and user combination. Other combinations may reuse the IDs.

      Returns:
      the unique ID of this event

    • toString

      public String toString()
      Overrides:
      toString in class AWTEvent

    • getTouchPoint

      public TLcdTouchPoint getTouchPoint(long aTouchPointID)
      Utility method to retrieve the TLcdTouchPoint with touch point ID aTouchPointID from this event.
      Parameters:
      aTouchPointID - the touch point ID
      Returns:
      the requested TLcdTouchPoint, or null when this event does not contain such TLcdTouchPoint
      See Also:

    • cloneAs

      public TLcdTouchEvent cloneAs(long aTouchEventID, Object aSource, List<TLcdTouchPoint> aTouchPointList, long aTouchDeviceID, String aUserID, long aTimeStamp)

      Create a new instance of this class based on the information passed as parameters to this method.

      This method should be overridden by extensions of this class if they want to include their info in the newly created event.

      Parameters:
      aTouchEventID - the ID for the new TLcdTouchEvent
      aSource - the source component for the new TLcdTouchEvent
      aTouchPointList - the List with TLcdTouchPoints for the new TLcdTouchEvent
      aTouchDeviceID - the device ID for the new TLcdTouchEvent
      aUserID - the user ID for the new TLcdTouchEvent
      aTimeStamp - the time stamp for the new TLcdTouchEvent
      Returns:
      a new TLcdTouchEvent
      Since:
      2020.0
      See Also:

    • createTouchEventID

      public static long createTouchEventID()

      Use this method to retrieve a new ID for touch events.

      This method allows to create TLcdTouchEvent instances through the whole application. Since subsequent TLcdTouchEvents describing a new input point sequence require a different touch event ID, a central access point for obtaining IDs is required. This method provides such an access point.

      This method should only be called when a new touch event ID is required. Subsequent TLcdTouchEvent instances describing changes in the same input sequence must re-use their ID, hence they must not call this method.

      Returns:
      an ID for a touch event
      See Also:

    • fromFXEvent

      public static TLcdTouchEvent fromFXEvent(TouchEvent aTouchEvent)
      Converts a native JavaFX TouchEvent into a TLcdTouchEvent.
      Parameters:
      aTouchEvent - the JavaFX touch event
      Returns:
      a TLcdTouchEvent which is created using the actual JavaFX touch event, or null when the event type is TouchEvent.TOUCH_STATIONARY
      Since:
      2020.0