diff --git a/docs/api/camera.md b/docs/api/camera.md index 0a55de9b..f7584bfd 100644 --- a/docs/api/camera.md +++ b/docs/api/camera.md @@ -1,11 +1,100 @@ # The camera scanner -**enioka Scan** can still be used to manage barcodes scanned using the Android camera. For that, it -exposes the `CameraBarcodeScanView` and a series of helper classes to handle compatibility with both -Camera 1 and Camera 2 hardware APIs. +**enioka Scan** can still be used to manage barcodes scanned using the Android camera, through +`com.enioka.scanner.sdk.camera`, (check +[library dependencies and compatibility matrix](dependencies.md)). For that, it exposes the +`CameraBarcodeScanView` and a series of helper classes to handle compatiblity with both Camera 1 +and Camera 2 hardware APIs. This page regroups all information needed to control this special scanner at a deeper level. +## The camera activity +The simplest way to use the camera scanner in an activity is simply to inherit from the +`CameraCompatActivity` class. This class implements the +[`ScannerClient` interface](scanner_service.md#the-scannerclient-interface). + +### `CameraCompatActivity` attributes + +:::{cpp:var} int layoutIdCamera = R.layout.activity_main_alt + +The layout used by the activity when using the camera as a scanner. May be replaced with your own. +::: + +:::{cpp:var} CameraBarcodeScanViewScanner cameraScanner; + +The instance of the camera scanner, can be used to access camera methods but should not be replaced. +`CameraBarcodeScanViewScanner` is a simple provider-less implementation of the +[`Scanner` interface](scanner.md#the-scanner-interface). + +Initialized by the [`initCamera()`](#scannercompatactivity-methods) method. +::: + +:::{cpp:var} int flashlightViewId = R.id.scanner_flashlight + +The ID of the optional ImageButton on which to press to toggle the flashlight/illumination. +::: + +:::{cpp:var} int cameraViewId = R.id.camera_scan_view + +The ID of the [`CameraBarcodeScanView`](camera.md#the-camerabarcodescanview-class) inside the +`layoutIdCamera` layout. +::: + +:::{cpp:var} int scannerModeToggleViewId = R.id.scanner_switch_zxing + +The ID of the optional ImageButton on which to press to toggle the zxing/zbar camera scan library. +::: + +:::{cpp:var} int scannerModeTogglePauseId = R.id.scanner_switch_pause + +The ID of the optional toggle button on which to press to pause/unpause the scanner. +::: + +:::{cpp:var} int keyboardOpenViewId = R.id.scanner_bt_keyboard + +The ID of the optional toggle button on which to display the manual input fragment. +::: + +:::{cpp:var} ManualInputFragment manualInputFragment; + +An optional fragment allowing to input a value with the soft keyboard (for cases when scanners do +not work). +::: + +:::{cpp:var} List autocompletionItems = new ArrayList<>() + +Auto completion items for manual input (with manualInputFragment). +::: + +:::{cpp:var} int threshold = 5 + +How many characters should be entered before auto-completion starts. +::: + +### `CaneraCompatActivity` methods + +:::{method} setAutocompletion(List autocompletion, int threshold) -> void + +**Inserts** the given autocompletion strings into the `autocompletionItems` and updates the +autocompletion threshold. + +:param List autocompletion: The autocompletion items to add. +:param int threshold: The new threshold. +::: + +:::{method} setAutocompletionItems(List items, int threshold) -> void + +**Replaces** `autocompletionItems` with the given list and updates the autocompletion threshold. + +:param List autocompletion: The autocompletion items to use. +:param int threshold: The new threshold. +::: + +:::{method} initCamera() -> void + +Switches the activity to camera mode. +::: + ## The `CameraBarcodeScanView` class This is the base Android `FrameLayout` used by the activity to display the camera. This view wraps diff --git a/docs/api/scanner_activity.md b/docs/api/scanner_activity.md index c9e134ae..78341637 100644 --- a/docs/api/scanner_activity.md +++ b/docs/api/scanner_activity.md @@ -34,12 +34,6 @@ If true, the activity will not switch to using the camera, even if no other scan If false, the activity will behave like a standard `AppCompatActivity`. ::: -:::{cpp:var} boolean goToCamera = false - -If true, the activity will directly switch to using the camera. This boolean is automatically set -to true if the scanner service finds no scanner after the first search. -::: - :::{cpp:var} boolean useBluetooth = true If true, the activity will check that the application has bluetooth permissions before starting the @@ -51,17 +45,6 @@ service. **This does not affect scanner search options**. The layout used by the activity when using regular scanner devices. May be replaced with your own. ::: -:::{cpp:var} int layoutIdCamera = R.layout.activity_main_alt - -The layout used by the activity when using the camera as a scanner. May be replaced with your own. -::: - -:::{cpp:var} int cameraViewId = R.id.camera_scan_view - -The ID of the [`CameraBarcodeScanView`](camera.md#the-camerabarcodescanview-class) inside the -`layoutIdCamera` layout. -::: - :::{cpp:var} int cameraToggleId = R.id.scanner_bt_camera The ID of the optional ImageButton on which to press to manually switch to camera mode. @@ -72,16 +55,6 @@ The ID of the optional ImageButton on which to press to manually switch to camer The ID of the optional ImageButton on which to press to toggle the flashlight/illumination. ::: -:::{cpp:var} int scannerModeToggleViewId = R.id.scanner_switch_zxing - -The ID of the optional ImageButton on which to press to toggle the zxing/zbar camera scan library. -::: - -:::{cpp:var} int scannerModeTogglePauseId = R.id.scanner_switch_pause - -The ID of the optional toggle button on which to press to pause/unpause the scanner. -::: - :::{cpp:var} int keyboardOpenViewId = R.id.scanner_bt_keyboard The ID of the optional toggle button on which to display the manual input fragment. @@ -111,15 +84,6 @@ replaced. Initialized by the `onStart()` and `onResume()` methods. ::: -:::{cpp:var} CameraBarcodeScanViewScanner cameraScanner; - -The instance of the camera scanner, can be used to access camera methods but should not be replaced. -`CameraBarcodeScanViewScanner` is a simple provider-less implementation of the -[`Scanner` interface](scanner.md#the-scanner-interface). - -Initialized by the [`initCamera()`](#scannercompatactivity-methods) method. -::: - ## `ScannerCompatActivity` methods :::{method} getServiceInitExtras() -> Bundle @@ -146,11 +110,6 @@ autocompletion threshold. :param int threshold: The new threshold. ::: -:::{method} initCamera() -> void - -Switches the activity to camera mode. After this method is called, `goToCamera` is set to true. -::: - :::{method} anyScannerSupportsIllumination() -> boolean Checks whether any available scanner supports Illumination. diff --git a/docs/dependencies.md b/docs/dependencies.md index 4780262a..b36e30e9 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -20,7 +20,12 @@ Each artefact can be imported to your project as `com.enioka.scanner:: ### `scanner` Core components of the library, **required** for it to work. It includes the scanner APIs, default -scanning activity and service, and camera-as-a-scanner functionality. +scanning activity and service. + +### `scanner-camera` + +Includes the `CAMERA_SCANNER` provider. It includes camera-as-a-scanner functionality and default +camera scanner activity. ### `provider-cs-athesi-e5l` @@ -152,7 +157,7 @@ devices. | Artefact | Provider name | Supported devices | Tested devices | Device type | External requirements | Device compatible if | |------------------------------------|----------------------------------|-----------------------------------------------------|------------------------------------|---------------|----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| -| `scanner` | `CAMERA_SCANNER` (no provider) | Any device with a camera | Smartphones, integrated devices... | Camera | | Device has a camera | +| `scanner-camera` | `CAMERA_SCANNER` (no provider) | Any device with a camera | Smartphones, integrated devices... | Camera | | Device has a camera | | `provider-cs-athesi-e5l` | `AthesiE5LProvider` | Athesi E5L | Athesi E5L | Integrated | | Device name is strictly `RD50TE` | | `provider-cs-athesi-spa43` | `AthesiHHTProvider` | Athesi SPA43 | Athesi SPA43 | Integrated | | Device name is strictly `SPA43LTE` | | `provider-cs-bluebird` | `BluebirdProvider` | Bluebird integrated scanners | Bluebird EF500 | Integrated | Bluebird service (should be preinstalled on device) | Intent `kr.co.bluebird.android.bbapi.action.BARCODE_OPEN` has a listener | diff --git a/docs/quickstart.md b/docs/quickstart.md index af521516..09f10fa4 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -19,9 +19,9 @@ dependencies { } ``` -To use the smartphone's camera as a scanner, this single dependency is enough. To use others devices, -dependencies are required, you can check the -[library dependencies and compatibility matrix](dependencies.md) for a detailed overview. +To use others devices or the smartphone's camera as a scanner, dependencies are required, +you can check the [library dependencies and compatibility matrix](dependencies.md) +for a detailed overview. ## Using the library @@ -114,14 +114,20 @@ help converting search parameters to and from those intent extras. ## Using the camera +:::{warning} + +* `com.enioka.scanner.sdk.camera` dependencies are required to use the camera scanner, check + [library dependencies and compatibility matrix](dependencies.md). +::: + When there is no laser scanner available, or when a button is clicked, the `ScannerCompatActivity` -activity will fallback to using the device camera (if any) to scan barcodes. This leverages two -different barcode scanning libraries, ZBar and ZXing in recent versions. It is compatible both with -very old Camera APIs as well as more recent Camera 2 APIs. It tries to set the best camera -parameters for barcode scanning, including dynamically setting the camera resolution according to -the processing speed of the device. As a result, it may take a few dozen seconds to reach the most -suitable settings on first startup - the resolution is then stored and reused on subsequent -initialisations. +activity will fallback to another activity that is using the device camera (if any) to scan +barcodes. This leverages two different barcode scanning libraries, ZBar and ZXing in recent +versions. It is compatible both with very old Camera APIs as well as more recent Camera 2 APIs. +It tries to set the best camera parameters for barcode scanning, including dynamically setting the +camera resolution according to the processing speed of the device. As a result, it may take a few +dozen seconds to reach the most suitable settings on first startup - the resolution is then stored +and reused on subsequent initialisations. The camera scanner can actually be used easily inside your own activities without any links with the rest of the library (no need to use the scanner service, etc) by just adding the