From 91757f194174d1dc3a175c90ea91cf9c2fd4fc92 Mon Sep 17 00:00:00 2001 From: Jason Dreyzehner Date: Mon, 18 Jan 2016 19:03:34 -0500 Subject: [PATCH] add definitions, tests, and jsdocs for cordova-plugin-qrscanner --- .../cordova-plugin-qrscanner-tests.ts | 43 ++++ .../cordova-plugin-qrscanner.d.ts | 191 ++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 cordova-plugin-qrscanner/cordova-plugin-qrscanner-tests.ts create mode 100644 cordova-plugin-qrscanner/cordova-plugin-qrscanner.d.ts diff --git a/cordova-plugin-qrscanner/cordova-plugin-qrscanner-tests.ts b/cordova-plugin-qrscanner/cordova-plugin-qrscanner-tests.ts new file mode 100644 index 000000000..63deacc98 --- /dev/null +++ b/cordova-plugin-qrscanner/cordova-plugin-qrscanner-tests.ts @@ -0,0 +1,43 @@ +/// + +var QRScanner: QRScanner = window.QRScanner; +QRScanner.prepare() +QRScanner.prepare((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.scan((err, results) => { var error: Error = err; var contents: String = results; }) +QRScanner.cancelScan() +QRScanner.cancelScan((status) => {var obj: QRScannerStatus = status; }) +QRScanner.show() +QRScanner.show((status) => {var obj: QRScannerStatus = status; }) +QRScanner.hide() +QRScanner.hide((status) => {var obj: QRScannerStatus = status; }) +QRScanner.enableLight() +QRScanner.enableLight((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.disableLight() +QRScanner.disableLight((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.useCamera(1) +QRScanner.useCamera(1, (err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.useFrontCamera() +QRScanner.useFrontCamera((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.useBackCamera() +QRScanner.useBackCamera((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.pausePreview() +QRScanner.pausePreview((status) => {var obj: QRScannerStatus = status; }) +QRScanner.resumePreview() +QRScanner.resumePreview((status) => {var obj: QRScannerStatus = status; }) +QRScanner.openSettings() +QRScanner.openSettings((err, status) => { var error: Error = err; var obj: QRScannerStatus = status; }) +QRScanner.destroy() +QRScanner.destroy((status) => {var obj: QRScannerStatus = status; }) + +QRScanner.getStatus((status) => { + var obj: QRScannerStatus = status; + var bool: Boolean = status.authorized; + bool = status.prepared; + bool = status.scanning; + bool = status.previewing; + bool = status.webviewBackgroundIsTransparent; + bool = status.lightEnabled; + bool = status.canOpenSettings; + bool = status.canEnableLight; + var num: Number = status.currentCamera; +}) diff --git a/cordova-plugin-qrscanner/cordova-plugin-qrscanner.d.ts b/cordova-plugin-qrscanner/cordova-plugin-qrscanner.d.ts new file mode 100644 index 000000000..31f141188 --- /dev/null +++ b/cordova-plugin-qrscanner/cordova-plugin-qrscanner.d.ts @@ -0,0 +1,191 @@ +// Type definitions for cordova-plugin-qrscanner +// Project: https://github.com/bitpay/cordova-plugin-qrscanner +// Definitions by: Jason Dreyzehner +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped + +/** +* Global object QRScanner. +*/ +interface Window { + QRScanner: QRScanner; +} + +/** +* The QRScanner object provides functions to initialize, control, utilize, and +* deallocate a native QR code scanner and video preview behind the Cordova webview. +*/ +interface QRScanner { + + /** + * Request permission to access the camera (if not already granted), prepare + * the video preview, and configure everything needed by QRScanner. This will + * only be visible if `QRScanner.show()` has already made the webview transparent. + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + prepare: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Sets QRScanner to "watch" for valid QR codes. Once a valid code is + * detected, it's contents are passed to the callback, and scanning is + * toggled off. If `QRScanner.prepare()` has not been called, + * `QRScanner.scan()` performs that setup as well. The video preview does + * not need to be visible for scanning to function. + * @param {function} callback Callback that gets an error or the results string. + */ + scan: (callback: (error: Error, result: String) => any) => void; + + /** + * Cancels the current scan. The current scan() callback will not return. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + cancelScan: (callback?: (status: QRScannerStatus) => any) => void; + + /** + * Configures the native webview to have a transparent background, then sets + * the background of the `` and parent elements to transparent, + * allowing the webview to re-render with the transparent background. + * To see the video preview, your application background must be transparent + * in the areas through which it should show. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + show: (callback?: (status: QRScannerStatus) => any) => void; + + /** + * Configures the native webview to be opaque with a white background, + * covering the video preview. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + hide: (callback?: (status: QRScannerStatus) => any) => void; + + + /** + * Enable the device's light (for scanning in low-light environments). + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + enableLight: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Disable the device's light. + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + disableLight: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Switch video capture to the `index` camera. Camera `0` is the back camera, + * camera `1` is front camera. + * @param {number} index A number representing the index of the camera to use. + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + useCamera: (index: Number, callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Switch video capture to the device's front camera. + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + useFrontCamera: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Switch video capture to the device's back camera. + * @param {function} [callback] Callback that gets an error or the QRScannerStatus object. + */ + useBackCamera: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Pauses the video preview on the current frame (as if a snapshot was taken). + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + pausePreview: (callback?: (status: QRScannerStatus) => any) => void; + + /** + * Resumes the video preview. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + resumePreview: (callback?: (status: QRScannerStatus) => any) => void; + + /** + * Open the app-specific permission settings in the user's device settings. + * Here the user can enable/disable camera (and other) access for your app. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + openSettings: (callback?: (error: Error, status: QRScannerStatus) => any) => void; + + /** + * Retrieve the status of QRScanner and provide it to the callback function. + * @param {function} callback Callback that gets the QRScannerStatus object. + */ + getStatus: (callback: (status: QRScannerStatus) => any) => void; + + /** + * Stops scanning, video capture, and the preview, and deallocates as much as + * possible. (E.g. to improve performance/battery life when the scanner is + * not likely to be used for a while.) + * Basically reverts the plugin to it's startup-state. + * @param {function} [callback] Callback that gets the QRScannerStatus object. + */ + destroy: (callback?: (status: QRScannerStatus) => any) => void; +} + + +/** +* An object representing the current status of QRScanner. +*/ +interface QRScannerStatus { + + /** + * On iOS, camera access is granted to an app by the user (by clicking "Allow" + * at the dialog). The `authorized` property is a boolean value which is true + * only when the user has allowed camera access to your app + * (`AVAuthorizationStatus.Authorized`). The `NotDetermined`, `Restricted` + * (e.g.: parental controls), and `Denied` AVAuthorizationStatus states all + * cause this value to be false. If the user has denied access to your app, + * consider asking nicely and offering a link via `QRScanner.openSettings()`. + */ + authorized: Boolean, + + /** + * A boolean value which is true if QRScanner is prepared to capture video and + * render it to the view. + */ + prepared: Boolean, + + /** + * A boolean value which is true if QRScanner is actively scanning for a QR code. + */ + scanning: Boolean, + + /** + * A boolean value which is true if QRScanner is displaying a live preview + * from the device's camera. Set to false when the preview is paused. + */ + previewing: Boolean, + + /** + * A boolean value which is true when the native webview background is transparent. + */ + webviewBackgroundIsTransparent: Boolean, + + /** + * A boolean value which is true if the light is enabled. + */ + lightEnabled: Boolean, + + /** + * A boolean value which is true only if the users' operating system is able + * to `QRScanner.openSettings()`. + */ + canOpenSettings: Boolean, + + /** + * A boolean value which is true only if the users' device can enable a light + * in the direction of the currentCamera. + */ + canEnableLight: Boolean, + + /** + * A number representing the index of the currentCamera. `0` is the back + * camera, `1` is the front. + */ + currentCamera: Number +} + +declare var QRScanner: QRScanner;