Class PointerEvent

java.lang.Object
com.codename1.ui.events.PointerEvent
public final class PointerEvent extends Object

Immutable snapshot describing the rich detail of a pointer interaction that goes beyond the simple x/y coordinates carried by the legacy pointer callbacks.

A PointerEvent exposes which mouse button triggered the interaction, the kind of pointing device used (finger, mouse, stylus or eraser), the pressure applied, stylus tilt, the size of the contact area and the keyboard modifiers that were held down.

The snapshot is available in two ways:

  • From an ActionEvent fired by a pointer listener via ActionEvent#getPointerEvent().
  • By polling com.codename1.ui.Display#getCurrentPointerEvent() (or the matching com.codename1.ui.CN convenience method) while a pointer event is being dispatched.

Every value carries a safe default so code written against the rich API behaves predictably on devices and ports that do not supply the extra detail. On such ports the button defaults to BUTTON_PRIMARY, the pressure to 1.0, the type to TYPE_UNKNOWN and tilt/contact size to 0.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    BUTTON_BACK
    The back (fourth) mouse button.
    static final int
    BUTTON_FORWARD
    The forward (fifth) mouse button.
    static final int
    BUTTON_MIDDLE
    The middle mouse button (often the scroll wheel click).
    static final int
    BUTTON_NONE
    No button is associated with this event (for example a hover or a plain touch).
    static final int
    BUTTON_PRIMARY
    The primary (usually left) mouse button, or a plain touch/stylus contact.
    static final int
    BUTTON_SECONDARY
    The secondary (usually right) mouse button or stylus barrel button.
    static final int
    MASK_BACK
    Button mask bit for the back button.
    static final int
    MASK_FORWARD
    Button mask bit for the forward button.
    static final int
    MASK_MIDDLE
    Button mask bit for the middle button.
    static final int
    MASK_PRIMARY
    Button mask bit for the primary button.
    static final int
    MASK_SECONDARY
    Button mask bit for the secondary button.
    static final int
    MODIFIER_ALT
    Modifier mask bit indicating the alt/option key was held.
    static final int
    MODIFIER_CONTROL
    Modifier mask bit indicating the control key was held.
    static final int
    MODIFIER_META
    Modifier mask bit indicating the meta/command/windows key was held.
    static final int
    MODIFIER_SHIFT
    Modifier mask bit indicating the shift key was held.
    static final int
    TYPE_ERASER
    The interaction came from the eraser end of a stylus.
    static final int
    TYPE_MOUSE
    The interaction came from a mouse or trackpad.
    static final int
    TYPE_STYLUS
    The interaction came from a stylus or pen (Apple Pencil, S-Pen, Surface Pen and similar).
    static final int
    TYPE_TOUCH
    The interaction came from a finger on a touch screen.
    static final int
    TYPE_UNKNOWN
    The pointing device could not be determined.

  • Constructor Summary

    Constructors
    Constructor
    Description
    PointerEvent(int x, int y, int button, int buttonMask, int pointerType, float pressure, float tiltX, float tiltY, float contactSize, int modifiers, boolean hovering)
    Creates a new immutable pointer event snapshot.

  • Method Summary

    Modifier and Type
    Method
    Description
    int
    getButton()
    The button that triggered this event, one of the BUTTON_* constants.
    int
    getButtonMask()
    A bitmask of all buttons currently held down, built from the MASK_* constants.
    float
    getContactSize()
    The normalized size of the contact area between 0.0 and 1.0, or 0 when not reported.
    int
    getModifiers()
    A bitmask of the keyboard modifiers held during this event, built from the MODIFIER_* constants.
    int
    getPointerType()
    The kind of pointing device that produced this event, one of the TYPE_* constants.
    float
    getPressure()
    The normalized pressure applied by the pointer between 0.0 and 1.0.
    float
    getTiltX()
    The stylus tilt across the x axis in degrees, or 0 when not reported.
    float
    getTiltY()
    The stylus tilt across the y axis in degrees, or 0 when not reported.
    int
    getX()
    The x position of the pointer in display pixels.
    int
    getY()
    The y position of the pointer in display pixels.
    boolean
    isAltDown()
    True if the alt/option key was held during this event.
    boolean
    isControlDown()
    True if the control key was held during this event.
    boolean
    isEraser()
    True if this event came from the eraser end of a stylus.
    boolean
    isHovering()
    True if the pointer is hovering above the surface without making contact.
    boolean
    isMetaDown()
    True if the meta/command/windows key was held during this event.
    boolean
    isMiddleButton()
    True if the triggering button is the middle button.
    boolean
    isMouse()
    True if this event came from a mouse or trackpad.
    boolean
    isPrimaryButton()
    True if the triggering button is the primary (left) button.
    boolean
    isSecondaryButton()
    True if the triggering button is the secondary (right) button or stylus barrel button.
    boolean
    isShiftDown()
    True if the shift key was held during this event.
    boolean
    isStylus()
    True if this event came from a stylus or the eraser end of a stylus.
    boolean
    isTouch()
    True if this event came from a finger on a touch screen.
    String
    toString()
    Returns a string representation of the object.

    Methods inherited from class Object

    clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • TYPE_UNKNOWN

      public static final int TYPE_UNKNOWN
      The pointing device could not be determined.
      See Also:

    • TYPE_TOUCH

      public static final int TYPE_TOUCH
      The interaction came from a finger on a touch screen.
      See Also:

    • TYPE_MOUSE

      public static final int TYPE_MOUSE
      The interaction came from a mouse or trackpad.
      See Also:

    • TYPE_STYLUS

      public static final int TYPE_STYLUS
      The interaction came from a stylus or pen (Apple Pencil, S-Pen, Surface Pen and similar).
      See Also:

    • TYPE_ERASER

      public static final int TYPE_ERASER
      The interaction came from the eraser end of a stylus.
      See Also:

    • BUTTON_NONE

      public static final int BUTTON_NONE
      No button is associated with this event (for example a hover or a plain touch).
      See Also:

    • BUTTON_PRIMARY

      public static final int BUTTON_PRIMARY
      The primary (usually left) mouse button, or a plain touch/stylus contact.
      See Also:

    • BUTTON_SECONDARY

      public static final int BUTTON_SECONDARY
      The secondary (usually right) mouse button or stylus barrel button.
      See Also:

    • BUTTON_MIDDLE

      public static final int BUTTON_MIDDLE
      The middle mouse button (often the scroll wheel click).
      See Also:

    • BUTTON_BACK

      public static final int BUTTON_BACK
      The back (fourth) mouse button.
      See Also:

    • BUTTON_FORWARD

      public static final int BUTTON_FORWARD
      The forward (fifth) mouse button.
      See Also:

    • MASK_PRIMARY

      public static final int MASK_PRIMARY
      Button mask bit for the primary button.
      See Also:

    • MASK_SECONDARY

      public static final int MASK_SECONDARY
      Button mask bit for the secondary button.
      See Also:

    • MASK_MIDDLE

      public static final int MASK_MIDDLE
      Button mask bit for the middle button.
      See Also:

    • MASK_BACK

      public static final int MASK_BACK
      Button mask bit for the back button.
      See Also:

    • MASK_FORWARD

      public static final int MASK_FORWARD
      Button mask bit for the forward button.
      See Also:

    • MODIFIER_SHIFT

      public static final int MODIFIER_SHIFT
      Modifier mask bit indicating the shift key was held.
      See Also:

    • MODIFIER_CONTROL

      public static final int MODIFIER_CONTROL
      Modifier mask bit indicating the control key was held.
      See Also:

    • MODIFIER_ALT

      public static final int MODIFIER_ALT
      Modifier mask bit indicating the alt/option key was held.
      See Also:

    • MODIFIER_META

      public static final int MODIFIER_META
      Modifier mask bit indicating the meta/command/windows key was held.
      See Also:

  • Constructor Details

    • PointerEvent

      public PointerEvent(int x, int y, int button, int buttonMask, int pointerType, float pressure, float tiltX, float tiltY, float contactSize, int modifiers, boolean hovering)

      Creates a new immutable pointer event snapshot.

      Parameters

      • x: the x position of the pointer in display pixels

      • y: the y position of the pointer in display pixels

      • button: one of the BUTTON_* constants describing the triggering button

      • buttonMask: bitmask of the MASK_* constants describing all currently held buttons

      • pointerType: one of the TYPE_* constants describing the pointing device

      • pressure: normalized pressure between 0.0 and 1.0, defaulting to 1.0

      • tiltX: stylus tilt across the x axis in degrees, 0 when not available

      • tiltY: stylus tilt across the y axis in degrees, 0 when not available

      • contactSize: normalized size of the contact area between 0.0 and 1.0

      • modifiers: bitmask of the MODIFIER_* constants describing held keyboard modifiers

      • hovering: true if the pointer is hovering above the surface without contact

  • Method Details

    • getX

      public int getX()
      The x position of the pointer in display pixels.

    • getY

      public int getY()
      The y position of the pointer in display pixels.

    • getButton

      public int getButton()
      The button that triggered this event, one of the BUTTON_* constants. Defaults to BUTTON_PRIMARY for plain touch interactions and BUTTON_NONE for hover events.

    • getButtonMask

      public int getButtonMask()
      A bitmask of all buttons currently held down, built from the MASK_* constants.

    • getPointerType

      public int getPointerType()
      The kind of pointing device that produced this event, one of the TYPE_* constants.

    • getPressure

      public float getPressure()
      The normalized pressure applied by the pointer between 0.0 and 1.0. Ports that do not report pressure return 1.0 so that pressure aware code keeps working.

    • getTiltX

      public float getTiltX()
      The stylus tilt across the x axis in degrees, or 0 when not reported.

    • getTiltY

      public float getTiltY()
      The stylus tilt across the y axis in degrees, or 0 when not reported.

    • getContactSize

      public float getContactSize()
      The normalized size of the contact area between 0.0 and 1.0, or 0 when not reported.

    • getModifiers

      public int getModifiers()
      A bitmask of the keyboard modifiers held during this event, built from the MODIFIER_* constants.

    • isHovering

      public boolean isHovering()
      True if the pointer is hovering above the surface without making contact.

    • isTouch

      public boolean isTouch()
      True if this event came from a finger on a touch screen.

    • isMouse

      public boolean isMouse()
      True if this event came from a mouse or trackpad.

    • isStylus

      public boolean isStylus()
      True if this event came from a stylus or the eraser end of a stylus.

    • isEraser

      public boolean isEraser()
      True if this event came from the eraser end of a stylus.

    • isPrimaryButton

      public boolean isPrimaryButton()
      True if the triggering button is the primary (left) button.

    • isSecondaryButton

      public boolean isSecondaryButton()
      True if the triggering button is the secondary (right) button or stylus barrel button.

    • isMiddleButton

      public boolean isMiddleButton()
      True if the triggering button is the middle button.

    • isShiftDown

      public boolean isShiftDown()
      True if the shift key was held during this event.

    • isControlDown

      public boolean isControlDown()
      True if the control key was held during this event.

    • isAltDown

      public boolean isAltDown()
      True if the alt/option key was held during this event.

    • isMetaDown

      public boolean isMetaDown()
      True if the meta/command/windows key was held during this event.

    • toString

      public String toString()
      Description copied from class: Object
      Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
      Overrides:
      toString in class Object