Skip to content

AMD based API which follows W3C Pointer Events specification and adds click/dbl click normalization.

License

Notifications You must be signed in to change notification settings

ibm-js/dpointer

Repository files navigation

#dpointer Build Status

This project proposes a unified and consistent javascript events API which aims to abstract touch/pointer/mouse events across various devices/OS.

This API is a shim of the W3C Pointer Events specification and adds features that are out of scope of the current specification.

  • Generates Pointer Events according to the current specification.
  • Use attribute touch-action to set touch action on HTML elements; generates touch-action CSS properties when supported by the browser.
  • Support Pointer Capture with mouse and touch events.
  • Normalize click (Tap) events, double click (double Tap) events, and event button/buttons/which values.
  • Supports immediate clicks (no ~300ms delay)

##Supported environments The API has been successfully tested on the following environments.

###Mobile

  • Android 4.1.2+ (Stock browser and Chrome)
  • BlackBerry 10+
  • iOS 6.1.3+
  • WindowsPhone 8.x

###Desktop

  • Chrome (mouse)
  • FireFox (mouse + touchscreen)
  • IE11 (mouse + touchscreen)
  • Edge (mouse)
  • Safari (mouse)

Dependencies

This project can be integrated into any AMD capable javascript application.

Installation

Bower release installation:

$ bower install dpointer

Manual master installation:

$ git clone git://github.com/ibm-js/dpointer.git

##Usage

  1. Require the module dpointer/events
  2. Set the attribute touch-action on elements you want to handle pointer events. Example: <div touch-action="none"> </div>
  3. Start listening to Pointer Events: pointerdown, pointerup, pointercancel, pointermove, pointerover, pointerout, pointerenter, pointerleave, gotpointercapture and lostpointercapture.

###Setting the Touch Action attribute

  • Programmatic: use dpointer/events function setTouchAction(targetElement, actionType)
  • Declarative: add the attribute touch-action='<actiontype>'

Where actionType can be none, pan-x, pan-y or auto.

###Samples/tests To run the tests/samples you need to set requirejs and domReady as a sibling of the dpointer module like this:

<root>/dpointer/events/events.js
<root>/requirejs/require.js
<root>/domReady/domReady.js

##Limitations

  • Pen properties (pressure/tiltx,y/height/width...) are not implemented. Properties are defined with default values. The API has not been tested with pens.
  • Avoid to rely on pointerType. In some cases (for instance, when a mouse is plugged on Android devices), the type may not be accurate (the mouse generates touch events and there is no way to know that they originate from a mouse.).

Status

  • No official release, work in progress.

Contributing

  • Use, tests and contributions are welcome: see contributing
  • This API was developed with Dojo 2.0 in mind, as a possible replacement of the current Dojo touch API. For more details see ticket #17192

Licensing

This project is distributed by the Dojo Foundation and licensed under the "New" BSD License. All contributions require a Dojo Foundation CLA.

Credits

  • Sebastien Pereira (IBM CCLA)

About

AMD based API which follows W3C Pointer Events specification and adds click/dbl click normalization.

Resources

License

Stars

Watchers

Forks

Packages

No packages published