psychojs/js/core/Keyboard.js

/**
 * Manager handling the keyboard events.
 *
 * @author Alain Pitiot
 * @version 3.2.0
 * @copyright (c) 2019 Ilixa Ltd. ({@link http://ilixa.com})
 * @license Distributed under the terms of the MIT License
 */

import {Clock, MonotonicClock} from "../util/Clock";
import {PsychObject} from "../util/PsychObject";
import {PsychoJS} from "./PsychoJS";
import {EventManager} from "./EventManager";


/**
 * @name module:core.KeyPress
 * @class
 *
 * @param {string} code - W3C Key Code
 * @param {number} tDown - time of key press (keydown event) relative to the global Monotonic Clock
 * @param {string | undefined} name - pyglet key name
 */
export class KeyPress {
	constructor(code, tDown, name) {
		this.code = code;
		this.tDown = tDown;
		this.name = (typeof name !== 'undefined') ? name : EventManager.w3c2pyglet(code);

		// duration of the keypress (time between keydown and keyup events) or undefined if there was no keyup
		this.duration = undefined;

		// time of keydown event relative to Keyboard clock:
		this.rt = undefined;
	}
}


/**
 * <p>This manager handles all keyboard events. It is a substitute for the keyboard component of EventManager. </p>
 *
 * @name module:core.Keyboard
 * @class
 * @param {Object} options
 * @param {PsychoJS} options.psychoJS - the PsychoJS instance
 * @param {number} [options.bufferSize= 10000] - the maximum size of the circular keyboard event buffer
 * @param {boolean} [options.waitForStart= false] - whether or not to wait for a call to module:core.Keyboard#start
 * before recording keyboard events
 * @param {Clock} [options.clock= undefined] - an optional clock
 * @param {boolean} options.autoLog - whether or not to log
 */
export class Keyboard extends PsychObject {

	constructor({
								psychoJS,
								bufferSize = 10000,
								waitForStart = false,
								clock,
								autoLog = false,
							} = {}) {

		super(psychoJS);

		if (typeof clock === 'undefined')
			clock = new Clock(); //this._psychoJS.monotonicClock;

		this._addAttributes(Keyboard, bufferSize, waitForStart, clock, autoLog);
		// start recording key events if need be:
		this._addAttribute('status', (waitForStart)?PsychoJS.Status.NOT_STARTED:PsychoJS.Status.STARTED);

		// setup circular buffer:
		this.clearEvents();

		// add key listeners:
		this._addKeyListeners();

	}


	/**
	 * Start recording keyboard events.
	 *
	 * @name module:core.Keyboard#start
	 * @function
	 * @public
	 *
	 */
	start() {
		this._status = PsychoJS.Status.STARTED;
	}


	/**
	 * Stop recording keyboard events.
	 *
	 * @name module:core.Keyboard#stop
	 * @function
	 * @public
	 *
	 */
	stop() {
		this._status = PsychoJS.Status.STOPPED;
	}


	/**
	 * @typedef Keyboard.KeyEvent
	 *
	 * @property {string} W3C key code
	 * @property {string} W3C key
	 * @property {string} pyglet key
	 * @property {module:core.Keyboard#KeyStatus} key status
	 * @property {number} timestamp (in seconds)
	 */
	/**
	 * Get the list of those keyboard events still in the buffer, i.e. those that have not been
	 * previously cleared by calls to getKeys with clear = true.
	 *
	 * @name module:core.Keyboard#getEvents
	 * @function
	 * @public
	 * @return {Keyboard.KeyEvent[]} the list of events still in the buffer
	 */
	getEvents() {
		if (this._bufferLength === 0)
			return [];

		
		// iterate over the buffer, from start to end, and discard the null event:
		let filteredEvents = [];
		const bufferWrap = (this._bufferLength === this._bufferSize);
		let i = bufferWrap ? this._bufferIndex : -1;
		do {
			i = (i + 1) % this._bufferSize;
			const keyEvent = this._circularBuffer[i];
			if (keyEvent)
				filteredEvents.push(keyEvent);
		} while (i !== this._bufferIndex);

		return filteredEvents;
	}


	/**
	 * Get the list of keys pressed or pushed by the participant.
	 *
	 * @name module:core.Keyboard#getKeys
	 * @function
	 * @public
	 * @param {Object} options
	 * @param {string[]} [options.keyList= []]] - the list of keys to consider. If keyList is empty, we consider all keys.
	 * Note that we use pyglet keys here, to make the PsychoJs code more homogeneous with PsychoPy.
	 * @param {boolean} [options.waitRelease= true] - whether or not to include those keys pressed but not released. If
	 * waitRelease = false, key presses without a corresponding key release will have an undefined duration.
	 * @param {boolean} [options.clear= false] - whether or not to keep in the buffer the key presses or pushes for a subsequent call to getKeys. If a keyList has been given and clear = true, we only remove from the buffer those keys in keyList
	 * @return {KeyPress[]} the list of keys that were pressed (keydown followed by keyup) or pushed
	 * (keydown with no subsequent keyup at the time getKeys is called).
	 */
	getKeys({
						keyList = [],
						waitRelease = true,
						clear = true
					} = {}) {

		// if nothing in the buffer, return immediately:
		if (this._bufferLength === 0)
			return [];

		let keyPresses = [];

		// iterate over the circular buffer, looking for keyup events:
		const bufferWrap = (this._bufferLength === this._bufferSize);
		let i = bufferWrap ? this._bufferIndex : -1;
		do {
			i = (i + 1) % this._bufferSize;

			const keyEvent = this._circularBuffer[i];
			if (keyEvent && keyEvent.status === Keyboard.KeyStatus.KEY_UP) {
				// check that the key is in the keyList:
				if (keyList.length === 0 || keyList.includes(keyEvent.pigletKey)) {
					// look for a corresponding, preceding keydown event:
					const precedingKeydownIndex = keyEvent.keydownIndex;
					if (typeof precedingKeydownIndex !== 'undefined') {
						const precedingKeydownEvent = this._circularBuffer[precedingKeydownIndex];
						if (precedingKeydownEvent) {
							// prepare KeyPress and add it to the array:
							const tDown = precedingKeydownEvent.timestamp;
							const keyPress = new KeyPress(keyEvent.code, tDown, keyEvent.pigletKey);
							keyPress.rt = tDown - this._clock.getLastResetTime();
							keyPress.duration = keyEvent.timestamp - precedingKeydownEvent.timestamp;
							keyPresses.push(keyPress);

							if (clear)
								this._circularBuffer[precedingKeydownIndex] = null;
						}
					}

					/* old approach: the circular buffer contains independent keydown and keyup events:
					let j = i - 1;
					do {
						if (j === -1 && bufferWrap)
							j = this._bufferSize - 1;

						const precedingKeyEvent = this._circularBuffer[j];

						if (precedingKeyEvent &&
							(precedingKeyEvent.key === keyEvent.key) &&
							(precedingKeyEvent.status === Keyboard.KeyStatus.KEY_DOWN)) {
							duration = keyEvent.timestamp - precedingKeyEvent.timestamp;

							if (clear)
							// rather than modify the circular buffer, which is computationally expensive,
							// we simply nullify the keyEvent:
								this._circularBuffer[j] = null;

							break;
						}

						j = j - 1;
					} while ((bufferWrap && j !== i) || (j > -1));*/

					if (clear)
						this._circularBuffer[i] = null;

				}
			}

		} while (i !== this._bufferIndex);


		// if waitRelease = false, we iterate again over the map of unmatched keydown events:
		if (!waitRelease) {
			for (const unmatchedKeyDownIndex of this._unmatchedKeydownMap.values()) {
				const keyEvent = this._circularBuffer[unmatchedKeyDownIndex];
				if (keyEvent) {
					// check that the key is in the keyList:
					if (keyList.length === 0 || keyList.includes(keyEvent.pigletKey)) {
						const tDown = keyEvent.timestamp;
						const keyPress = new KeyPress(keyEvent.code, tDown, keyEvent.pigletKey);
						keyPress.rt = tDown - this._clock.getLastResetTime();
						keyPresses.push(keyPress);

						if (clear) {
							this._unmatchedKeydownMap.delete(keyEvent.code);
							this._circularBuffer[unmatchedKeyDownIndex] = null;
						}
					}
				}
			}
			/* old approach: the circular buffer contains independent keydown and keyup events:
			let i = bufferWrap ? this._bufferIndex : -1;
			do {
				i = (i + 1) % this._bufferSize;

				const keyEvent = this._circularBuffer[i];
				if (keyEvent && keyEvent.status === Keyboard.KeyStatus.KEY_DOWN) {
					// check that the key is in the keyList:
					const pigletKey = EventManager.w3c2pyglet(keyEvent.code);
					if (keyList.length === 0 || keyList.includes(pigletKey)) {
						keyPresses.push(new KeyPress(keyEvent.code, keyEvent.timestamp, pigletKey));

						if (clear)
							// rather than modify the circular buffer, which is computationally expensive, we simply nullify
							// the keyEvent:
							this._circularBuffer[i] = null;
					}
				}

			} while (i !== this._bufferIndex);*/
		}


		// if clear = true and the keyList is empty, we clear all the events:
		if (clear && keyList.length === 0)
			this.clearEvents();


		return keyPresses;
	}


	clearEvents() {
		// circular buffer of key events (keydown and keyup):
		this._circularBuffer = new Array(this._bufferSize);
		this._bufferLength = 0;
		this._bufferIndex = -1;
		this._previousKeydownKey = undefined;

		// (code => circular buffer index) map of keydown events not yet matched to keyup events:
		this._unmatchedKeydownMap = new Map();
	}


	/**
	 * Add key listeners to the document.
	 *
	 * @name module:core.Keyboard#_addKeyListeners
	 * @function
	 * @private
	 */
	_addKeyListeners() {
		this._previousKeydownKey = undefined;
		const self = this;


		// add a keydown listener:
		document.addEventListener("keydown", (event) => {
			const timestamp = MonotonicClock.getReferenceTime(); // timestamp in seconds

			if (this._status !== PsychoJS.Status.STARTED)
				return;

			// since keydown events will repeat as long as the key is pressed, we need to track the last pressed key:
			if (event.key === self._previousKeydownKey)
				return;
			self._previousKeydownKey = event.key;

			let code = event.code;

			// take care of legacy Microsoft Edge:
			if (typeof code === 'undefined')
				code = EventManager.keycode2w3c(event.keyCode);

			let pigletKey = EventManager.w3c2pyglet(code);


			self._bufferIndex = (self._bufferIndex + 1) % self._bufferSize;
			self._bufferLength = Math.min(self._bufferLength + 1, self._bufferSize);
			self._circularBuffer[self._bufferIndex] = {
				code,
				key: event.key,
				pigletKey,
				status: Keyboard.KeyStatus.KEY_DOWN,
				timestamp
			};

			self._unmatchedKeydownMap.set(event.code, self._bufferIndex);

			self._psychoJS.logger.trace('keydown: ', event.key);
console.log(self._circularBuffer[self._bufferIndex]);
		});


		// add a keyup listener:
		document.addEventListener("keyup", (event) => {
			const timestamp = MonotonicClock.getReferenceTime(); // timestamp in seconds

			if (this._status !== PsychoJS.Status.STARTED)
				return;

			self._previousKeydownKey = undefined;

			let code = event.code;

			// take care of legacy Microsoft Edge:
			if (typeof code === 'undefined')
				code = EventManager.keycode2w3c(event.keyCode);

			let pigletKey = EventManager.w3c2pyglet(code);

			self._bufferIndex = (self._bufferIndex + 1) % self._bufferSize;
			self._bufferLength = Math.min(self._bufferLength + 1, self._bufferSize);
			self._circularBuffer[self._bufferIndex] = {
				code,
				key: event.key,
				pigletKey,
				status: Keyboard.KeyStatus.KEY_UP,
				timestamp
			};

			// get the corresponding keydown event
			// note: if more keys are down than there are slots in the circular buffer, there might
			// not be a corresponding keydown event
			const correspondingKeydownIndex = self._unmatchedKeydownMap.get(event.code);
			if (typeof correspondingKeydownIndex !== 'undefined') {
				self._circularBuffer[self._bufferIndex].keydownIndex = correspondingKeydownIndex;
				self._unmatchedKeydownMap.delete(event.code);
			}

			self._psychoJS.logger.trace('keyup: ', event.key);
console.log(self._circularBuffer[self._bufferIndex]);
		});

	}
}


/**
 * Keyboard KeyStatus.
 *
 * @name module:core.Keyboard#KeyStatus
 * @enum {Symbol}
 * @readonly
 * @public
 */
Keyboard.KeyStatus = {
	KEY_DOWN: Symbol.for('KEY_DOWN'),
	KEY_UP: Symbol.for('KEY_UP')
};