Add support for multiple public APIs (#331)

* Add support for multiple public APIs

Html5Qrcode:
 - pause()
 - resume()
 - getState()

Html5QrcodeScanner
 - pause()
 - resume()
 - getState()
 - getRunningTrackCapabilities()
 - applyVideoConstraints()

* Fix codacy reported issues

* Some PR fixes

* fix codacy error - Variable Assigned to Object Injection Sink

README.md

@@ -332,6 +332,17 @@ interface CameraDevice {
   label: string;
 }
 
+/** Different states of scanner */
+enum Html5QrcodeScannerState {
+  // Indicates the sanning is not running or user is using file based
+  // scanning.
+  NOT_STARTED = 0,
+  // Camera scan is running.
+  SCANNING,
+  // Camera scan is paused but camera is running.
+  PAUSED,
+}
+
 /**
  * Code formats supported by this library.
  */
@@ -508,13 +519,39 @@ class Html5Qrcode {
     configuration: Html5QrcodeCameraScanConfig | undefined,
     qrCodeSuccessCallback: QrcodeSuccessCallback | undefined,
     qrCodeErrorCallback: QrcodeErrorCallback | undefined,
-  ): Promise<null> {}ass
+  ): Promise<null> {}
+
+  /**
+   * Pauses the ongoing scan.
+   * 
+   * Note: this will not stop the viewfinder, but stop decoding camera stream.
+   * 
+   * @throws error if method is called when scanner is not in scanning state.
+   */
+  pause();
+
+  /**
+   * Resumes the paused scan.
+   * 
+   * Note: with this caller will start getting results in success and error
+   * callbacks.
+   * 
+   * @throws error if method is called when scanner is not in paused state.
+   */
+  resume();
 
   /**
    * Stops streaming QR Code video and scanning. 
    */
   stop(): Promise<void> {}
 
+  /**
+   * Gets state of the camera scan.
+   *
+   * @returns state of type {@enum ScannerState}.
+   */
+  getState(): Html5QrcodeScannerState;
+
   /**
    * Scans an Image File for QR Code.
    *
@@ -564,6 +601,36 @@ class Html5QrcodeScanner {
     qrCodeSuccessCallback: QrcodeSuccessCallback,
     qrCodeErrorCallback: QrcodeErrorCallback | undefined) {}
 
+  /**
+   * Pauses the ongoing scan.
+   * 
+   * Notes:
+   * -   Should only be called if camera scan is ongoing.
+   * -   This will not stop the viewfinder, but stop decoding camera stream.
+   * 
+   * @throws error if method is called when scanner is not in scanning state.
+   */
+  pause();
+
+  /**
+   * Resumes the paused scan.
+   * 
+   * Notes:
+   * -   Should only be called if camera scan is ongoing.
+   * -   With this caller will start getting results in success and error
+   * callbacks.
+   * 
+   * @throws error if method is called when scanner is not in paused state.
+   */
+  resume();
+
+  /**
+   * Gets state of the camera scan.
+   *
+   * @returns state of type {@enum Html5QrcodeScannerState}.
+   */
+  getState(): Html5QrcodeScannerState;
+
   /** Removes the QR Code scanner. */
   clear(): Promise<void>  {}
 }

changelog.md

@@ -1,9 +1,115 @@
+### Version 2.1.1
+-   Fixed dashboard section exceeding the parent HTML element width.
+-   Added support for following beta APIs which allows modifying running video
+    stream state, which camera stream is running.
+    ```js
+    /**
+     * Returns the capabilities of the running video track.
+     * 
+     * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+     *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+     *   {@code Html5QrcodeScannerState#PAUSED}.
+     *
+     * @beta This is an experimental API
+     * @returns the capabilities of a running video track.
+     * @throws error if the scanning is not in running state.
+     */
+    public getRunningTrackCapabilities(): MediaTrackCapabilities;
+
+    /**
+     * Apply a video constraints on running video track from camera.
+     *
+     * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+     *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+     *   {@code Html5QrcodeScannerState#PAUSED}.
+     *
+     * @beta This is an experimental API
+     * @param {MediaTrackConstraints} specifies a variety of video or camera
+     *  controls as defined in
+     *  https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+     * @returns a Promise which succeeds if the passed constraints are applied,
+     *  fails otherwise.
+     * @throws error if the scanning is not in running state.
+     */
+    public applyVideoConstraints(videoConstaints: MediaTrackConstraints)   
+    ```
+
+    **Important note**: Both these APIs are beta and not publicly documented.
+
+-   Support for pausing and resuming code scanning in camera scan mode. New APIs
+    are added to both `Html5QrcodeScanner` and `Html5Qrcode`. They should only be called when the scanner state is `Html5QrcodeScannerState#SCANNING` (== `2`) or
+    `Html5QrcodeScannerState#PAUSED` (== `3`).
+
+    APIs added:
+    ```js
+    /**
+     * Pauses the ongoing scan.
+     * 
+     * Note: this will not stop the viewfinder, but stop decoding camera stream.
+     * 
+     * @throws error if method is called when scanner is not in scanning state.
+     */
+    public pause();
+
+    /**
+     * Resumes the paused scan.
+     * 
+     * Note: with this caller will start getting results in success and error
+     * callbacks.
+     * 
+     * @throws error if method is called when scanner is not in paused state.
+     */
+    public resume();
+
+        /**
+     * Gets state of the camera scan.
+     *
+     * @returns state of type {@enum ScannerState}.
+     */
+    public getState(): Html5QrcodeScannerState;
+    ```
+
+    Example usage:
+
+    ```js
+    let html5QrcodeScanner = new Html5QrcodeScanner(
+        "reader", 
+        { 
+            fps: 10,
+            qrbox: {width: 250, height: 250},
+            rememberLastUsedCamera: true,
+            aspectRatio: 1.7777778
+        });
+
+    function onScanSuccess(decodedText, decodedResult) {
+        if (html5QrcodeScanner.getState() 
+            !== Html5QrcodeScannerState.NOT_STARTED) {
+            // Add this check to ensure success callback is not being called
+            // from file based scanner.
+
+            // Pause on scan result
+            html5QrcodeScanner.pause();
+        }
+
+
+        // Handle your business logic
+        // ...
+
+        // .. ok to resume now or elsewhere.
+        // just call html5QrcodeScanner.resume();
+        // Make sure to check if the state is !== NOT_STARTED
+    }
+	html5QrcodeScanner.render(onScanSuccess);
+    ```
+
+    Note: when camera scan is paused it adds a UI element indicating that state.
+
 ### Version 2.1.0
- - `[Fixed]` issues related to using with lodash - https://github.com/mebjas/html5-qrcode/issues/284
- - `[Fixed]` Unable to use with typescript definition - https://github.com/mebjas/html5-qrcode/issues/283
- - `[Fixed]` Not working with react - https://github.com/mebjas/html5-qrcode/issues/322
- - `[Fixed]` TypeError: Html5QrcodeScanner is not a constructor - https://github.com/mebjas/html5-qrcode/issues/270
- - `[Fixed]` TypeError: window._ is undefined - https://github.com/mebjas/html5-qrcode/issues/248
+-   `[Fixed]` issues related to using with lodash - https://github.com/mebjas/html5-qrcode/issues/284
+-   `[Fixed]` Unable to use with typescript definition - https://github.com/mebjas/html5-qrcode/issues/283
+-   `[Fixed]` Not working with react - https://github.com/mebjas/html5-qrcode/issues/322
+-   `[Fixed]` TypeError: Html5QrcodeScanner is not a constructor - https://github.com/mebjas/html5-qrcode/issues/270
+-   `[Fixed]` TypeError: window._ is undefined - https://github.com/mebjas/html5-qrcode/issues/248
 
 ### Version 2.0.13
 Added ability to set custom width and height to the scanner with `config.qrbox` argument.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "html5-qrcode",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "A cross platform HTML5 QR Code & bar code scanner",
   "main": "./cjs/index.js",
   "module": "./esm/index.js",

scripts/webpack_append_data.js

@@ -3,4 +3,5 @@ if (window && !Html5QrcodeScanner) {
     var Html5QrcodeScanner = window.__Html5QrcodeLibrary__.Html5QrcodeScanner;
     var Html5Qrcode = window.__Html5QrcodeLibrary__.Html5Qrcode;
     var Html5QrcodeSupportedFormats = window.__Html5QrcodeLibrary__.Html5QrcodeSupportedFormats
+    var Html5QrcodeScannerState = window.__Html5QrcodeLibrary__.Html5QrcodeScannerState;
 }

src/html5-qrcode-scanner.ts

@@ -48,6 +48,7 @@ import {
 import {
   CameraManager
 } from "./camera";
+import { Html5QrcodeScannerState } from "./state-manager";
 
 /**
  * Different states of QR Code Scanner.
@@ -195,6 +196,55 @@ export class Html5QrcodeScanner {
             toHtml5QrcodeFullConfig(this.config, this.verbose));
     }
 
+    //#region State related public APIs
+    /**
+     * Pauses the ongoing scan.
+     * 
+     * Notes:
+     * -   Should only be called if camera scan is ongoing.
+     * -   This will not stop the viewfinder, but stop decoding camera stream.
+     * 
+     * @throws error if method is called when scanner is not in scanning state.
+     */
+    public pause() {
+        if (!this.html5Qrcode) {
+            throw "Code scanner not initialized.";
+        }
+
+        this.html5Qrcode.pause();
+    }
+
+    /**
+     * Resumes the paused scan.
+     * 
+     * Notes:
+     * -   Should only be called if camera scan is ongoing.
+     * -   With this caller will start getting results in success and error
+     * callbacks.
+     * 
+     * @throws error if method is called when scanner is not in paused state.
+     */
+    public resume() {
+        if (!this.html5Qrcode) {
+            throw "Code scanner not initialized.";
+        }
+
+        this.html5Qrcode.resume();
+    }
+
+    /**
+     * Gets state of the camera scan.
+     *
+     * @returns state of type {@enum Html5QrcodeScannerState}.
+     */
+    public getState(): Html5QrcodeScannerState {
+        if (!this.html5Qrcode) {
+            throw "Code scanner not initialized.";
+        }
+
+        return this.html5Qrcode.getState();
+    }
+
     /**
      * Removes the QR Code scanner UI.
      * 
@@ -239,6 +289,52 @@ export class Html5QrcodeScanner {
 
         return Promise.resolve();
     }
+    //#endregion
+
+    //#region Beta APIs to modify running stream state.
+    /**
+     * Returns the capabilities of the running video track.
+     * 
+     * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+     *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+     *   {@code Html5QrcodeScannerState#PAUSED}.
+     *
+     * @beta This is an experimental API
+     * @returns the capabilities of a running video track.
+     * @throws error if the scanning is not in running state.
+     */
+    public getRunningTrackCapabilities(): MediaTrackCapabilities {
+        if (!this.html5Qrcode) {
+            throw "Code scanner not initialized.";
+        }
+
+        return this.html5Qrcode.getRunningTrackCapabilities();
+    }
+
+    /**
+     * Apply a video constraints on running video track from camera.
+     *
+     * Note: Should only be called if {@code Html5QrcodeScanner#getState()}
+     *   returns {@code Html5QrcodeScannerState#SCANNING} or 
+     *   {@code Html5QrcodeScannerState#PAUSED}.
+     *
+     * @beta This is an experimental API
+     * @param {MediaTrackConstraints} specifies a variety of video or camera
+     *  controls as defined in
+     *  https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints
+     * @returns a Promise which succeeds if the passed constraints are applied,
+     *  fails otherwise.
+     * @throws error if the scanning is not in running state.
+     */
+    public applyVideoConstraints(videoConstaints: MediaTrackConstraints)
+        : Promise<any> {
+        if (!this.html5Qrcode) {
+            throw "Code scanner not initialized.";
+        }
+
+        return this.html5Qrcode.applyVideoConstraints(videoConstaints);
+    }
+    //#endregion
 
     //#region Private methods
     private createConfig(config: Html5QrcodeScannerConfig | undefined)
@@ -321,7 +417,7 @@ export class Html5QrcodeScanner {
         const section = document.createElement("div");
         section.id = this.getDashboardSectionId();
         section.style.width = "100%";
-        section.style.padding = "10px";
+        section.style.padding = "10px 0px 10px 0px";
         section.style.textAlign = "left";
         dashboard.appendChild(section);
     }