NEW option captureEvents

HISTORY.md

@@ -1,8 +1,13 @@
 # onScan.js - version history
 
+### 1.5
+
+- NEW method `onScan.isScanInProgressFor()` to test if a potential keyboard scan is in progress
+- NEW option `captureEvents` to make sure onScan gets events before any other listerer below in the DOM
+
 ### 1.4.3
 
-- NEW onScan.simulate() now accepts arrays of key codes or event properties
+- NEW `onScan.simulate()` now accepts arrays of key codes or event properties
 - FIX shiftKey detection was not working
 
 ### 1.4.2

README.md

@@ -100,6 +100,7 @@ The following options can be set when initializing onScan.js:
 | scanButtonLongPressTime | 500 | Time (ms) to hold the scan button before `onScanButtonLongPress` is triggered. Only works if `scanButtonKeyCode` is set. |
 | stopPropagation | false | Stop immediate propagation of events, that are processed successfully.<br><br><b>WARNING:</b> If `reactToKeyDown` is true, every keyboard event, that could potentially be part of a scancode will be stopped! |
 | preventDefault | false | Prevent default action of events, that are processed successfully.<br><br><b>WARNING:</b> If `reactToKeyDown` is true, the default of every keyboard event, that could potentially be part of a scancode will be prevented - in particular you won't be able to use the keyboard for typing!!! |
+| captureEvents | false | Set to `true` to force all relevant events to be dispatched to onScan _before_ being dispatched to any `EventTarget` beneath it in the DOM tree. Use this if you need to cancel certain events in onScan callbacks. Technically this option is used as the third parameter in `.addEventListener(type, listener [, useCapture])` calls. The exact behavior is documented [here](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener). |
 | singleScanQty    | 1    | This is the quantity of items which gets returned on a single successful scan. |
 | reactToKeydown | true | Look for scan input among `keydown` events (i.e. if the scanner works in keyboard-mode). |
 | reactToPaste | false | Look for scan input among `paste` events (i.e. if the scanner works in clipboard-mode). |

onscan.js

@@ -38,6 +38,7 @@
 				ignoreIfFocusOn:false, // do not handle scans if the currently focused element matches this selector or object
 				stopPropagation:false, // Stop immediate propagation on keypress event
 				preventDefault:false, // Prevent default action on keypress event
+				captureEvents:false, // Get the events before any listeners deeper in the DOM
 				reactToKeydown:true, // look for scan input in keyboard events
 				reactToPaste:false, // look for scan input in paste events
 				singleScanQty: 1, // Quantity of Items put out to onScan in a single scan
@@ -61,13 +62,13 @@
 
 			// initializing handlers (based on settings)
 			if (oOptions.reactToPaste === true){
-				oDomElement.addEventListener("paste", this._handlePaste);
+				oDomElement.addEventListener("paste", this._handlePaste, oOptions.captureEvents);
 			}
 			if (oOptions.scanButtonKeyCode !== false){
-				oDomElement.addEventListener("keyup", this._handleKeyUp);
+				oDomElement.addEventListener("keyup", this._handleKeyUp, oOptions.captureEvents);
 			}
 			if (oOptions.reactToKeydown === true || oOptions.scanButtonKeyCode !== false){	
-				oDomElement.addEventListener("keydown", this._handleKeyDown);
+				oDomElement.addEventListener("keydown", this._handleKeyDown, oOptions.captureEvents);
 			}
 			return this;
 		},

package.json

@@ -1,6 +1,6 @@
 {
   "name": "onscan.js",
-  "version": "1.4.3",
+  "version": "1.5",
   "description": "Framework agnostic onScan event fired when using hardware barcode scanners",
   "main": "onscan.js",
   "repository": {