biofriction-wp-theme/node_modules/what-input/README.md

6.3 KiB

What Input?

A global utility for tracking the current input method (mouse, keyboard or touch).

What Input is now v4.3.0

What Input adds data attributes to the <html> tag based on the type of input being used. It also exposes a simple API that can be used for scripting interactions.

July 12, 2017

  • Updated: added passive to touchstart event.

July 3, 2017

  • Updated: custom events can now be registered and unregistered.

June 13, 2017

  • Updated: Typing in form inputs does not change input type, but tabbing between inputs does initiate a switch from mouse to keyboard.

June 12, 2017

  • Added: passive event listener for wheel event.
  • Added: ability to fire custom functions when 'intent' or 'input' changes.

Changes from v3

  • mousemove and pointermove events no longer affect the data-whatinput attribute.
  • A new data-whatintent attribute now works like v3. This change is intended to separate direct interaction from potential.
  • Key logging and the corresponding whatInput.keys() API option have been removed.
  • Event binding and attributes are now added to the <html> tag to eliminate the need to test for DOMContentLoaded.
  • The whatInput.set() API option has been removed.
  • A new set of whatinput-types-[type] classes are now added as inputs are detected. New classes are added but existing ones remain, creating the same output as what the whatInput.types() returns.

How it works

What Input uses event bubbling on the <html> tag to watch for mouse, keyboard and touch events (via mousedown, keydown and touchstart). It then sets or updates a data-whatinput attribute.

Where present, Pointer Events are supported, but note that pen inputs are remapped to touch.

What Input also exposes a tiny API that allows the developer to ask for or set the current input.

What Input does not make assumptions about the input environment before the page is directly interacted with. However, the mousemove and pointermove events are used to set a data-whatintent="mouse" attribute to indicate that a mouse is being used indirectly.

Interacting with Forms

Since interacting with a form requires use of the keyboard, What Input does not switch the input type while form <input>s and <textarea>s are being interacted with, preserving the last detected input type.

Installing

Download the file directly...

or install via Bower...

bower install what-input

or install via NPM...

npm install what-input

Usage

Include the script directly in your project.

<script src="dist/what-input.min.js"></script>

Or require with a script loader.

require('what-input');

// or

var whatInput = require('what-input');

// or

requirejs.config({
  paths: {
    whatInput: 'path/to/what-input'
  }
});

require(['whatInput'], function() {});

What Input will start doing its thing while you do yours.

Example Styling

/**
 * set a custom default :focus style
 */

/* default styling before what input executes */
:focus {

}

/* initial styling after what input has executed but before any interaction */
[data-whatinput="initial"] :focus {
  outline: 2px dotted black;
}

/* mouse */
[data-whatinput="mouse"] :focus {
  outline-color: red;
}

/* keyboard */
[data-whatinput="keyboard"] :focus {
  outline-color: green;
}

/* touch */
[data-whatinput="touch"] :focus {
  outline-color: blue;
}

Note: If you remove outlines with outline: none;, be sure to provide clear visual :focus styles so the user can see which element they are on at any time for greater accessibility. Visit W3C's WCAG 2.0 2.4.7 Guideline to learn more.

Scripting

Current Input

Ask What Input what the current input method is. This works best if asked after the events What Input is bound to (mousedown, keydown and touchstart).

whatInput.ask(); // returns `mouse`, `keyboard` or `touch`

myButton.addEventListener('click', function() {

  if (whatInput.ask() === 'mouse') {
    // do mousy things
  } else if (whatInput.ask() === 'keyboard') {
    // do keyboard things
  }

});

If it's necessary to know if mousemove is being used, use the 'loose' option. For example:


/*
  nothing has happened but the mouse has moved
*/

whatInput.ask(); // returns `initial` because the page has not been directly interacted with
whatInput.ask('loose'); // returns `mouse` because mouse movement was detected

/*
  the keyboard has been used, then the mouse was moved
*/

whatInput.ask(); // returns `keyboard` because the keyboard was the last direct page interaction
whatInput.ask('loose'); // returns `mouse` because mouse movement was the most recent action detected

Ask What Input to return an array of all the input types that have been used so far.

whatInput.types(); // ex. returns ['mouse', 'keyboard']

Set a custom array of keycodes that will be ignored when pressed.

whatInput.ignoreKeys([1, 2, 3])

Fire a function when the input or intent changes.

// create a function to be fired
var myFunction = function(type) {
  console.log(type)
};

// fire `myFunction` when the intent changes
whatInput.registerOnChange(myFunction, 'intent');

// fire `myFunction` when the input changes
whatInput.registerOnChange(myFunction, 'input');

// remove custom event
whatInput.unRegisterOnChange(myFunction);

Compatibility

What Input works in all modern browsers. For compatibility with IE8, polyfills are required for:

  • addEventListener
  • IndexOf

Add your own, or grab the bundle included here.

<!--[if lte IE 8]>
  <script src="lte-IE8.js"></script>
<![endif]-->

Demo

Check out the demo to see What Input in action.

http://ten1seven.github.io/what-input

Acknowledgments

Special thanks to Viget for their encouragement and commitment to open source projects. Visit code.viget.com to see more projects from Viget.

Thanks to mAAdhaTTah for the initial conversion to Webpack.

What Input is written and maintained by @ten1seven.

License

What Input is freely available under the MIT License.