From 3167806eabad6b0fbddb12d5066018085d3313ac Mon Sep 17 00:00:00 2001 From: "antoine.gonzalez" Date: Mon, 11 Dec 2023 12:34:27 +0100 Subject: [PATCH] Cleanup for first merge #130 --- README.md | 256 ++++------------------------------ docs/api/camera.md | 11 +- docs/api/index.md | 15 +- docs/api/lazerscanner.md | 14 +- docs/api/others.md | 6 - docs/api/scanner.md | 25 +--- docs/api/scanner_activity.md | 36 ++--- docs/api/scanner_callbacks.md | 20 ++- docs/api/scanner_provider.md | 34 ++--- docs/api/scanner_service.md | 58 ++++---- docs/conf.py | 1 - docs/dependencies.md | 8 +- docs/develop.md | 49 +++---- docs/guides/custom_layout.md | 49 +++++++ docs/guides/index.md | 11 +- docs/index.md | 11 +- docs/quickstart.md | 164 +++++++--------------- 17 files changed, 244 insertions(+), 524 deletions(-) create mode 100644 docs/guides/custom_layout.md diff --git a/README.md b/README.md index 2b13cab4..ae610947 100644 --- a/README.md +++ b/README.md @@ -1,245 +1,47 @@ # Enioka Haute Couture Android Barcode Scanning Library -[External documentation available](https://enioka-scan.readthedocs.io/en/130-documentation/), this README will be reworked once everything is correctly ported. - This library makes the integration of all barcode scanners easy in any Android application, avoiding vendor lock-in and lowering the cost of advanced scanner integration. -It is compatible with: -* Zebra EMDK devices (which comprise most of their integrated systems like the TC25, TC75, WT6000...) -* Zebra Bluetooth scanners -* Honeywell AIDC integrated devices (including CN* devices) -* Athesi SPA43 -* GeneralScan Bluetooth rings -* And a few others, check full compatibility table below. - -When there are no compatible hardware devices available, the library provides a camera reader based on ZBar (default) or ZXing. - -Through a common abstraction, it provides access to the following methods (provided the hardware supports them): -* press/release the scanner's trigger -* pause/resume scanning abilities -* disconnect/reconnect scanners -* enable/disable illumination from the scanner -* enable/disable colored LEDs -* set scanner enabled symbologies - -Finally, it provides a ready to use Service that handles scanner lifecycles, as well as a template Activity, and a sample demo -application, allowing to use scanners in a matter of minutes. - -# Compatibility matrix - -The different plugins do not all have the same capabilities. The following table sums up what is possible to do with this library on common device families. - -* "?" means the library does not support the function, but the underlying SDK or device may support it and the capability may be added later. -* "N/A" means this would make no sense on this device. -* "All 1D" symbologies means code 128, 39, I25, D25, EAN13. (some devices also provide QR code and other 2D symbologies) -* "Plugin AAR needed" means an additional aar must be used for this device. This is likely because it contains non-OSS code and cannot be distributed freely. -* "SDK needed" means the library will need the manufacturer SDK to work. This SDK likely could not be included for licence reasons, and must be provided by valid SDK license holder. -* "Provider name" is a name internal to the library which can be used to enable or disable a provider (by default all providers present are used which can slow initialisation). - -Manufacturer | Device family | Plugin AAR needed | SDK needed | Provider name | Connection | Notes | Basic scanning | Symbologies recognized | Symbologies detection | Symbology configuration | Illumination control | Disable trigger | LED control | Beep control | Trigger control ------------- | ---------------------- | ----------------- | ---------- | ------------------------------------------- | ---------- | ------------------------------ | -------------- | --------------------------- | --------------------- | ----------------------- | -------------------- | --------------- | ----------- | ------------ | --------------- -Zebra | Integrated: TC25... | Yes | No | EmdkProvider | Integrated | EMDK devices | Yes | All 1D | Yes | On startup | No | Yes | N/A | No? | ? -Zebra | BT ring RS6000,5100 | Yes | Yes | BtZebraProvider | BT SPP | | Yes | All 1D | Yes | On startup | No | Yes | Yes | Yes | ? -Zebra | BT ring RS6000,5100 | No | No | ZebraOssSppScannerProvider | BT SPP | Alternate pure OSS provider | Yes | All 1D | Yes | On startup | No | Yes | Yes | Yes | Yes -Bluebird | Integrated: EF500... | No | No | BluebirdProvider | Integrated | | Yes | Most, save D25 | Yes | ? | No | Yes | N/A | ? | ? -Athesi | Integrated: SPA43LTE | No | No | AthesiHHTProvider | Integrated | Device must be named SPA43LTE | Yes | All 1D | Yes | On startup | No | Yes | N/A | No? | Yes -Athesi | Integrated: SPA43LTE | No | No | AthesiE5LProvider | Integrated | Device must be named RD50TE | Yes | All 1D | No | No? | No | No | N/A | No? | Yes -Honeywell | Integrated: EDA50... | Yes | Yes | AIDCProvider | Integrated | AIDC devices (Intermec) | Yes | All 1D | Yes | On startup | No | ? | N/A | No? | ? -Honeywell | Integrated: EDA52 | No | No | HoneywellOssIntegratedScannerProvider | Integrated | Device must be named EDA52 | Yes | All 1D | Yes | No | No | ? | N/A | No? | Yes -Honeywell | BT Voyager 1602g | No | No | HoneywellOssSppScannerProvider | BT SPP | | Yes | All 1D | Yes | No | No | ? | N/A | No? | Yes -GeneralScan | BT ring R5000BT | No | No | GsSppScannerProvider | BT SPP | | Yes | All 1D | No | ? | No | No | No | No | ? -ProGlove | BT glove Mark II | No | No | ProgloveProvider | BT BLE | ProGlove app needed | Yes | All 1D | Yes | ? | No | No | Yes | No? | ? -Koamtac | BT KDC (180...) | Yes | No | Koamtac | BT BLE | Device must be named KDC* | Yes | All 1D | Yes | ? | No | Yes | Yes | Yes | ? -M3 | RingScanners | Yes | No | M3RingScannerProvider | BT SPP | M3 app needed | Yes | All 1D | No | No | No | Yes | No | No | ? -Camera | Devices with camera | No | No | | Integrated | Capabilities depend on device | Yes | All 1D | Yes | On startup | Yes (flash light) | Yes | N/A | Yes | N/A +It is compatible with a wide variety of scanning devices, integrated or external, from different +vendors such as Zebra, Honeywell, Athesi and more. -There also are traces of Postech BT ring scanner compatibility - their communication protocol is like the GeneralScan one, but the authors of the library lacked a test device to finish it, so it was disabled. -Note that many scanners not mentioned here are interpreted by the OS as a keyboard (HID devices), and as such are not supported in a specific way by the library. As for the camera, it is initialized in a different way than other scanners, we recommend taking a look at the template activity to understand its usage. +When there are no compatible hardware devices available, the library provides a camera reader based +on [ZBar](https://mvnrepository.com/artifact/me.dm7.barcodescanner/zbar) (default) or +[ZXing](https://mvnrepository.com/artifact/com.google.zxing/core). -# Adding the library to an Android application +Through a common abstraction, it provides access to the following methods (provided the hardware +supports them): +- press/release the scanner's trigger +- pause/resume scanning abilities +- disconnect/reconnect scanners +- enable/disable illumination from the scanner +- enable/disable colored LEDs +- set scanner enabled symbologies -For all devices which are not marked as "plugin AAR needed" in the above table, a single dependency is needed. It is available either here on Github or (better) or Maven Central: just use coordinates `com.enioka.scanner:scanner:x.y.z:aar` (do remember to specify `mavenCentral()` inside the Gradle build file `repositories` section), and update the version to latets version). +Finally, it provides a ready to use Service that handles scanner lifecycles, as well as a template +Activity, and a demo application, allowing you to use scanners in a matter of minutes. -That's all if you do not need an AAR plugin. If you also need a plugin AAR (provided by us) and a proprietary SDK (provided by the scanner manufacturer, at the root of your app: (all files *are inside the source tree or created by the project*) -* copy barcode_scanner_library_*.aar (the Zebra Bluetooth SDK) to aar_zebra -* copy DataCollection.jar (Honeywell SDK) to barcodelibs - -Inside aar_zebra: - -```groovy -configurations.maybeCreate("default") -artifacts.add("default", file('barcode_scanner_library_v2.0.8.0.aar')) -``` - -Inside settings.gradle, add 'aar_zebra" to the list of includes. - -Inside the application build.gradle, add: +In order to use **enioka Scan**, you need to add the corresponding dependency to your `build.gradle`. ```groovy -dependencies { - compile project(':aar_zebra') - - compile 'me.dm7.barcodescanner:zbar:1.8.3' - - compile 'com.android.support:appcompat-v7:28.0.0' - compile 'com.android.support.constraint:constraint-layout:1.0.2' -} -``` - -Inside the manifest of your application, nothing to do. - -# Using the library - -There are different ways to use the library, depending on where it has to be used. And in any ways, the library does not hide its low-level objects which are an always available fallback. -Most scanner capabilities are exposed through the [`Scanner`][scanner-api] API, though the default behavior of the [`ScannerServiceApi`][scanner-service-api] API ought to be enough for simply receiving scanned data. - -## In an Activity - -This is the most usual use of for the library. The library provides the class [`ScannerCompatActivity`][scanner-compat-activity] from which to inherit. The most simple activity ever possible to use a scanner is this: - -```java -import com.enioka.scanner.activities.ScannerCompatActivity; - -public class MyScanningActivity extends ScannerCompatActivity { -} -``` - -This creates an activity with a very simple layout which display status messages from the scanners as well as scanning results and a button to toggle illumination. Now, most activities of course want to use their own layouts. This is allowed by setting two fields (one for the camera layout, one for the laser layout) in the constructor of the activity: - -```java -@Override -protected void MyConstructor() { - super.onCreate(); - layoutIdLaser = R.layout.activity_parcel_scan_laser; - layoutIdCamera = R.layout.activity_parcel_scan_camera; +repositories { + mavenCentral() } -``` - -There are a few other fields to allow you to customize further the activity, which are all documented inside the class. These include options to rename the toggle illumination button ID, to disable camera or laser or both, or enable a fallback dialog with manual input and auto-completion. - -If the provided template does not suit your needs, but you still want to take advantage of the [`ScannerServiceApi`][scanner-service-api], simply make sure that your activity follows the steps described in the section below. - -if you use a custom layout, you need to use our Camera scanning view. The ID of this view should by default be `camera_scan_view` (which can be customized inside the constructor as for the other views). This view accepts a few parameters, which are displayed here with their default values: - -```xml - -``` - -Finally, note that inside the activity code there are a few hooks that can be overloaded - these are public or protected methods, with full javadoc. Of notice are:* -* `onData(List data)` -* `onStatusChanged(Scanner, ScannerStatusCallback.Status)` - -## Outside an activity - -The library exposes a service which can be bound as any other bound service: - -```java -ScannerServiceApi scannerService; -boolean serviceBound = false; - -ServiceConnection connection = new ServiceConnection() { - @Override - public void onServiceConnected(ComponentName className, - IBinder service) { - // We've bound to ScannerService, cast the IBinder and get the ScannerServiceApi instance - ScannerService.LocalBinder binder = (ScannerService.LocalBinder) service; - scannerService = binder.getService(); - serviceBound = true; - } - - @Override - public void onServiceDisconnected(ComponentName arg0) { - serviceBound = false; - scannerService = null; - } - }; - -// Bind to ScannerService service -// Make sure to bind the ScannerService class (or any implementation of the API), not the ScannerServiceApi interface -Intent intent = new Intent(this, ScannerService.class); -bindService(intent, connection, Context.BIND_AUTO_CREATE); -``` - -It is then possible to use the [`ScannerServiceApi`][scanner-service-api] object to access the different endpoints of the service. The most interesting one is `registerClient()` which hooks scanning callbacks and scanner/provider discovery notifications to a class implementing the [`ScannerClient`][scanner-client] interface such as a custom activity. - -Please remember to unbind the service when it is not needed anymore, as for any other service. This will often be in "onDestroy" hooks. Also, as this is a bound service, it is destroyed whenever it has no bound clients left. Many applications actually bind the service on startup onto the application context to be sure it is never destroyed and therefore is very quick to bind from anywhere, but this depends on the use-case and is not compulsory at all. - -If you want to bind the service inside your application class, a helper is provided to avoid boilerplate code that can be used as such: - -```java -public class App extends Application { - ScannerServiceBinderHelper serviceBinder; - - @Override - public void onCreate() { - super.onCreate(); - serviceBinder = ScannerServiceBinderHelper.bind(this); // a second overload exists with a configuration Bundle. - } - - @Override - public void onTerminate() { - super.onTerminate(); - serviceBinder.disconnect(); - } +dependencies { + implementation 'com.enioka.scanner:scanner:2.4.1:aar' } ``` -Finally, there are a few Intent extra properties which can be set to control the behaviour of the service such as filters used in the scanner search. -These can be found as static strings inside the [`ScannerServiceApi`][scanner-service-api] interface, and methods in the [`ScannerSearchOptions`][scanner-search-options] class help converting search parameters to and from those intent extras. - -## Using the camera - -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. - -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 `CameraBarcodeScanView` to your layouts, and then registering a callback on this view using `CameraBarcodeScanView.setResultHandler`. Other APIs are available to enable the torch or pause scanning. - -The provided Camera activity will display a target rectangle, which can be moved or tapped to change or refresh the autofocus area. - -# Developer quick start (modifying this library) - -## Developing for Android - -In order to start developing and testing the library: -* Have Android Studio installed and open the project with it -* Connect a compatible android device via USB, it should then show up in Android Studio's device manager -* Run the app with the android device selected - -In case the android device is not detected by Android Studio: -* Make sure the device is in developer mode and has USB Debugging enabled -* Make sure the USB cable supports data transfer (some cables only support charging) - -## Adding another SDK to the library - -A scanner SDK contains at least a [`Scanner`][scanner-api] implementation (interfacing between the code and the device) and a [`ScannerProvider`][scanner-provider-api] implementation (handling scanner creation and whether the SDK is compatible with the search). - -In order for a new scanner SDK to be found by the library, the [`ScannerProvider`][scanner-provider-api] implementation needs to be declared as a service in its `AndroidManifest.xml` with an intent-filter containing the action `com.enioka.scan.PROVIDE_SCANNER`. -The associated Java class does not need to extend Android's `Service` class (the `tools:ignore="Instantiatable"` attribute may be added to the service in the manifest), but it must provide a public default constructor as it will be instantiated using `Class.getName()`. - -See the [Mock SDK][mock-sdk] for an example of addon SDK. +More artefacts may be required depending on your devices, the full list and compatibility matrix are +available in the documentation. -# Release process +## Documentation -To publish the library to Maven Central and GitHub releases, a tag must be created and attached to the appropriate commit. -The tag will trigger a workflow that will automatically create a github release containing the AAR file, and publish the library to Maven Central. -If the release is created manually, the workflow will not run and the library will not be published correctly. Only the tag needs to be manually created. +You can learn more about **enioka Scan** by reading the [official documentation](https://enioka-scan.readthedocs.io/en/latest/). -[mock-sdk]: ./enioka_scan_mock -[scanner-api]: ./enioka_scan/src/main/java/com/enioka/scanner/api/Scanner.java -[scanner-client]: ./enioka_scan/src/main/java/com/enioka/scanner/service/ScannerClient.java -[scanner-compat-activity]: ./enioka_scan/src/main/java/com/enioka/scanner/activities/ScannerCompatActivity.java -[scanner-provider-api]: ./enioka_scan/src/main/java/com/enioka/scanner/api/ScannerProvider.java -[scanner-search-options]: ./enioka_scan/src/main/java/com/enioka/scanner/api/ScannerSearchOptions.java -[scanner-service-api]: ./enioka_scan/src/main/java/com/enioka/scanner/service/ScannerServiceApi.java \ No newline at end of file +Most notably: +- [The quick-start guide](https://enioka-scan.readthedocs.io/en/latest/quickstart.html) +- [Dependencies and compatible devices](https://enioka-scan.readthedocs.io/en/latest/dependencies.html) +- [The API reference](https://enioka-scan.readthedocs.io/en/latest/api/index.html) +- [How to develop for enioka Scan](https://enioka-scan.readthedocs.io/en/latest/develop.html) \ No newline at end of file diff --git a/docs/api/camera.md b/docs/api/camera.md index 94b737ce..0a55de9b 100644 --- a/docs/api/camera.md +++ b/docs/api/camera.md @@ -1,11 +1,5 @@ # The camera scanner -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - **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. @@ -19,7 +13,7 @@ the API-specific `CameraBarcodeScanViewBase` implementation and handles the API the device's properties. For most users, this is the class they will interact with if they need to interact with the Camera -hardware and not just the [`Scanner`](scanner) instance. +hardware and not just the [`Scanner` instance](scanner.md#the-scanner-interface). :::{method} setReaderMode(CameraReader readerMode) -> void @@ -44,8 +38,7 @@ Used by `CameraBarcodeScanViewScanner` to register itself with the view and corr barcodes read by the camera as any regular scanner reads. :param ResultHandler handler: the - [`ResultHandler`](scanner_callbacks.md#the-camerabarcodescanviewresulthandler-interface) - implementation + [`ResultHandler` implementation](scanner_callbacks.md#the-camerabarcodescanviewresulthandler-interface) ::: :::{method} setTorch(boolean value) -> void diff --git a/docs/api/index.md b/docs/api/index.md index 7d9ee7f6..55562f4f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -1,13 +1,13 @@ # API reference +% Notes: + % Due to the limitations of Sphinx and MyST, documentation formatting was 'hacked' a bit by using % python and cpp directives as Java is not natively supported and has no proper third-party option. -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: +% API guides for the BluetoothScanner API may be helpful for provider developers but is not a +% priority. A full bluetooth guide may be needed, as well as a detailed overview of the library's +% workflow from service startup to scanner availability. This section contains more in-depth info about important classes and interfaces of **enioka Scan**. @@ -29,7 +29,4 @@ others lazerscanner scanner_provider -::: - -% API guides for the BluetoothScanner API may be helpful for provider developpers but is not a -% priority. A full bluetooth guide may be needed. \ No newline at end of file +::: \ No newline at end of file diff --git a/docs/api/lazerscanner.md b/docs/api/lazerscanner.md index 98ce59af..b9a54f36 100644 --- a/docs/api/lazerscanner.md +++ b/docs/api/lazerscanner.md @@ -1,13 +1,8 @@ # The LazerScanner class -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - `LazerScanner` is the main scanner factory and the core of the library. It is in charge of finding -scanner providers and scanner devices. Most users will let the [`ScannerService`](scanner_service) +scanner providers and scanner devices. Most users will let the +[`ScannerService`](scanner_service.md#the-scannerserviceapi-interface) handle its own instance of `LazerScanner`, but should you need it, you can use its static methods directly. @@ -37,4 +32,9 @@ There is a specific callback when no scanner is available. :param ScannerConnectionHandler handler: The callback used whenever a scanner is found. Automatically wrapped by a `ScannerConnectionHandlerProxy`, for which a public overload exists. :param ScannerSearchOptions options: The options used to refine the search. +::: + +:::{seealso} + +* The [Callbacks](scanner_callbacks.md) documentation ::: \ No newline at end of file diff --git a/docs/api/others.md b/docs/api/others.md index 7a128cf2..43bd2d6b 100644 --- a/docs/api/others.md +++ b/docs/api/others.md @@ -1,11 +1,5 @@ # Other useful classes -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - The library contains a lot of other smaller classes you may need to interact with. This page will regroup most of them. diff --git a/docs/api/scanner.md b/docs/api/scanner.md index b0f512b2..3c4dd052 100644 --- a/docs/api/scanner.md +++ b/docs/api/scanner.md @@ -1,17 +1,5 @@ # The Scanner API -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - -:::{admonition} TODO -:class: attention - -* Correct links to specific methods of other API reference pages (e.g. `ScannerProvider.getKey()`) -::: - The `Scanner` interface is the central part of the library. It is the piece of code that gives the user control on the physical scanner devices. All devices have common methods relating to basic functionalities (reading a barcode) or lifecycle control. Some devices have access to extra features @@ -23,7 +11,7 @@ directly call the overloaded method with a proxy callback. :::{seealso} -[Callbacks](scanner_callbacks.md) documentation. +* The [Callbacks](scanner_callbacks.md) documentation. ::: ## The `Scanner` interface @@ -57,7 +45,7 @@ between the library and the physical devices and registers callbacks. :::{method} getProviderKey() -> String For logging and sorting purpose, this is the key of the SDK behind this scanner (same as -[`ScannerProvider.getKey()`](scanner_provider.md#getKey)) +[`ScannerProvider.getKey()`](scanner_provider.md#the-scannerprovider-interface)) ::: :::{method} setDataCallBack(ScannerDataCallbackProxy cb) -> void @@ -86,7 +74,7 @@ or absent. :::{method} resume(@Nullable ScannerCommandCallback cb) -> void -Reverse the effects of [`pause()`](#pause). The scanner is once again ready to scan after +Reverse the effects of `pause()`. The scanner is once again ready to scan after this call. The scanner's status callback should be called if needed. Idempotent. :param ScannerCommandCallback cb: The callback to call with the result of the operation. May be null @@ -171,7 +159,7 @@ or absent. :::{method} releaseScanTrigger(@Nullable ScannerCommandCallback cb) -> void -Ends the effect of [`pressScanTrigger()`](#pressScanTrigger). +Ends the effect of `pressScanTrigger()`. :param ScannerCommandCallback cb: The callback to call with the result of the operation. May be null or absent. @@ -196,7 +184,7 @@ or absent. :::{method} disableIllumination(@Nullable ScannerCommandCallback cb) -> void -Opposite of [`enableIllumination()`](#enableIllumination). +Opposite of `enableIllumination()`. :param ScannerCommandCallback cb: The callback to call with the result of the operation. May be null or absent. @@ -204,8 +192,7 @@ or absent. :::{method} toggleIllumination(@Nullable ScannerCommandCallback cb) -> void -See [`enableIllumination()`](#enableIllumination) and -[`disableIllumination()`](#disableIllumination). +See `enableIllumination()` and `disableIllumination()`. :param ScannerCommandCallback cb: The callback to call with the result of the operation. May be null or absent. diff --git a/docs/api/scanner_activity.md b/docs/api/scanner_activity.md index 7d78961e..c9e134ae 100644 --- a/docs/api/scanner_activity.md +++ b/docs/api/scanner_activity.md @@ -1,30 +1,26 @@ # The Scanner activity -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - The simplest way to start using **enioka Scan** in an activity is simply to inherit from the `ScannerCompatActivity` class. This class implements the -[`ScannerClient`](scanner_service.md#the-scannerclient-interface) interface and handles the scanner +[`ScannerClient` interface](scanner_service.md#the-scannerclient-interface) and handles the scanner service bindings and life cycle. It also exposes a default UI to print scan results, status messages and some buttons to manually control the scanner device from the app. Most of its methods are protected and can be overridden if needed. Mainly, methods from the -[`ScannerClient`](scanner_service.md#the-scannerclient-interface) interface should be replaced with +[`ScannerClient` interface](scanner_service.md#the-scannerclient-interface) should be replaced with your own to adapt the way scan results are handled by your application. -By default, the activity will use the [default search options](scanner_service.md#defaultOptions) to -initiate scanner search. There are two ways to change these options: override the -[`getServiceInitExtras()`](#getServiceInitExtras) method, and passing the search options as extras -to the intent starting the activity. In case both are used, the method is applied first, then intent -extras. +By default, the activity will use the +[default search options](scanner_service.md#the-scannersearchoptions-class) to initiate scanner +search. There are two ways to change these options: override the +[`getServiceInitExtras()` method](#scannercompatactivity-methods), and passing the search options as +extras to the intent starting the activity. In case both are used, the method is applied first, then +intent extras. This page will describe attributes and methods specific to this activity, disregarding overrides. For most users, it is recommended to only change the value of attributes or interface methods, as -overriding class methods may cause unexpected side-effects. +overriding class methods may cause unexpected side-effects. For example, using a custom layout only +requires changing the corresponding layout ID attributes. ## `ScannerCompatActivity` attributes @@ -95,8 +91,6 @@ The ID of the optional toggle button on which to display the manual input fragme An optional fragment allowing to input a value with the soft keyboard (for cases when scanners do not work). - -Initialized by the [`displayManualInputButton()`](#displayManualInputButton) method. ::: :::{cpp:var} List autocompletionItems = new ArrayList<>() @@ -114,16 +108,16 @@ How many characters should be entered before auto-completion starts. The instance of the bound scanner service, can be used to access service methods but should not be replaced. -Initialized by the [`onStart()`](#onStart) and [`onResume()`](#onResume) methods. +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`](scanner) -API. +`CameraBarcodeScanViewScanner` is a simple provider-less implementation of the +[`Scanner` interface](scanner.md#the-scanner-interface). -Initialized by the [`initCamera()`](#initCamera) method. +Initialized by the [`initCamera()`](#scannercompatactivity-methods) method. ::: ## `ScannerCompatActivity` methods @@ -169,5 +163,5 @@ Checks whether any available scanner has Illumination toggled on. :::{seealso} -[`ScannerClient`](scanner_service.md#the-scannerclient-interface) methods. +* The [`ScannerClient` interface](scanner_service.md#the-scannerclient-interface) documentation. ::: \ No newline at end of file diff --git a/docs/api/scanner_callbacks.md b/docs/api/scanner_callbacks.md index 1ad6e4b6..3947ac41 100644 --- a/docs/api/scanner_callbacks.md +++ b/docs/api/scanner_callbacks.md @@ -1,11 +1,5 @@ # API callbacks -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - Most **enioka Scan** actions use callbacks to communicate their result to your code. In the case of scanner-related callbacks, proxy classes exist to wrap callback implementations and ensure their methods are called on the UI thread. @@ -33,7 +27,8 @@ Called when the command's expected answer did not arrive in time (usually only w ## The `ScannerConnectionHandler` interface and `ScannerConnectionHandlerProxy` class -Callback used during the scanner search to retrieve created [`Scanner`](scanner) instances. +Callback used during the scanner search to retrieve created +[`Scanner` instances](scanner.md#the-scanner-interface). :::{method} scannerConnectionProgress(String providerKey, String scannerKey, String message) -> void @@ -46,8 +41,8 @@ A SDK-specific localized message signaling a change during the search for a scan :::{method} scannerCreated(String providerKey, String scannerKey, Scanner s) -> void -Called when a scanner was found and created. -Depending on [`ScannerSearchOptions.returnOnlyFirst`](scanner_service.md#returnOnlyFirst) may be +Called when a scanner was found and created. Depending on +[`ScannerSearchOptions.returnOnlyFirst`](scanner_service.md#the-scannersearchoptions-class) may be called multiple times. :param String providerKey: The identifier of the provider/SDK @@ -57,8 +52,8 @@ called multiple times. :::{method} noScannerAvailable() -> void -Called when there is no scanner available on the device. -[`endOfScannerSearch()`](#endOfScannerSearch) is always called after this. +Called when there is no scanner available on the device. `endOfScannerSearch()` is always called +after this. ::: :::{method} endOfScannerSearch() -> void @@ -195,7 +190,8 @@ manage the device it was tested for. Called if the provider can manage the device. -:param Scanner libraryScanner: The corresponding [`Scanner`](scanner) instance. +:param Scanner libraryScanner: The corresponding +[`Scanner` instance](scanner.md#the-scanner-interface). ::: :::{method} cannotManage() -> void diff --git a/docs/api/scanner_provider.md b/docs/api/scanner_provider.md index a9039c12..be91807f 100644 --- a/docs/api/scanner_provider.md +++ b/docs/api/scanner_provider.md @@ -1,11 +1,5 @@ # The ScannerProvider API -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - The Scanner Provider is the entrypoint of an SDK. Its purpose is to check if the SDK is able to interact with a device, and handle the [`Scanner`](scanner.md) creation. @@ -22,13 +16,13 @@ The core methods of a provider common between, all types of devices. This method will make the provider check whether it is compatible with any scanning device while matching requirements imposed by the search options. If it is able to connect to a device, the -provider will use the callback to notify its availability and return a [`Scanner`](scanner.md) -instance. +provider will use the callback to notify its availability and return a +[`Scanner` instance](scanner.md#the-scanner-interface). :param Context ctx: The application context. -:param ProviderCallback cb: The [`ProviderCallback`](scanner_callbacks.md#providerCallback) used - to notify the Scanner Service whether this SDK is available (as in, is able to connect to any - scanning device), and the current status of [`Scanner`](scanner.md) creation. +:param ProviderCallback cb: The `ProviderCallback` used to notify the Scanner Service whether this + SDK is available (as in, is able to connect to any scanning device), and the current status of + [`Scanner` instance](scanner.md#the-scanner-interface) creation. :param ScannerSearchOptions options: The search options the provider may use to further refine its compatibility checks. ::: @@ -40,8 +34,9 @@ instance. :::{seealso} -Check the documentation of the [`ProviderCallback`](scanner_callbacks.md#providerCallback) for -details on how the provider will communicate its status with the Scanner Service. +Check the documentation of the +[`ProviderCallback` interface](scanner_callbacks.md#the-scannerproviderprovidercallback-interface) +for details on how the provider will communicate its status with the Scanner Service. ::: ## The `IntentScannerProvider` abstract class @@ -54,8 +49,8 @@ A provider for an integrated scanner should extend this class and override the f :::{method} createNewScanner(Context ctx, ScannerSearchOptions options) -> Scanner -This method is called by `ScannerProvider.getScanner()` to create the [`Scanner`](scanner.md) -instance. +This method is called by `ScannerProvider.getScanner()` to create the +[`Scanner` instance](scanner.md#the-scanner-interface). :param Context ctx: The application context. :param ScannerSearchOptions options: The search options the provider used to confirm compatibility. @@ -121,15 +116,12 @@ Tests whether a scanner is compatible with the provider. Must complete in under :::{method} getInputHandler() -> ScannerDataParser -:returns: The [`ScannerDataParser`](others.md#scannerDataParser) which should be used to parse - bluetooth messages from compatible devices. +:returns: The parser which should be used to parse bluetooth messages from compatible devices. ::: :::{seealso} -Check the documentation of the [`ManagementCallback`](scanner_callbacks.md#managementCallback) +Check the documentation of the +[`ManagementCallback` interace](scanner_callbacks.md#the-btsppscannerprovidermanagementcallback-interface) for details on how the bluetooth provider will communicate its status with the Scanner Service. - -Check the documentation of the [`ScannerDataParser`](others.md#scannerDataParser) for -details bluetooth message parsers. ::: \ No newline at end of file diff --git a/docs/api/scanner_service.md b/docs/api/scanner_service.md index 54f399b6..68f9a4f2 100644 --- a/docs/api/scanner_service.md +++ b/docs/api/scanner_service.md @@ -1,11 +1,5 @@ # The ScannerService API -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - The `ScannerService` is responsible for handling the search of an available scanner device and SDK for the end user. Once any is found, it can be made available to the user in the form of a [`Scanner`](scanner) instance. @@ -19,30 +13,30 @@ and on the handling of found scanners. :::{method} registerClient(ScannerClient client) -> void -Registers a [`ScannerClient`](#scannerclient) implementation to the service. The service will call -this client's callbacks whenever applicable. +Registers a [`ScannerClient`](#the-scannerclient-interface) implementation to the service. The +service will call this client's callbacks whenever applicable. :param ScannerClient client: The client to register. ::: :::{method} unregisterClient(ScannerClient client) -> void -Unregisters a [`ScannerClient`](#scannerclient) implementation from the service. The service will no -no longer call this client's callbacks. +Unregisters a [`ScannerClient`](#the-scannerclient-interface) implementation from the service. The +service will no no longer call this client's callbacks. :param ScannerClient client: The client to unregister. ::: :::{method} restartScannerDiscovery() -> void -Disconnects all currently-connected [scanners](scanner) then starts the initialization process all -over again. +Disconnects all currently-connected [scanners](scanner.md#the-scanner-interface) then starts the +initialization process all over again. ::: :::{method} restartProviderDiscovery() -> void -Clears the cache of discovered [scanner providers](scanner_provider) and re-starts their discovery. -This is a costly operation. +Clears the cache of discovered [scanner providers](scanner_provider.md#the-scannerprovider-api) and +re-starts their discovery. This is a costly operation. ::: :::{method} getAvailableProviders() -> List @@ -54,7 +48,7 @@ options at runtime. :::{method} getConnectedScanners() -> List :returns: The list of keys of currently-connected scanners, allowing their direct manipulation -through the [`Scanner` API](scanner). +through the [`Scanner` API](scanner.md#the-scanner-interface). ::: :::{method} updateScannerSearchOptions(ScannerSearchOptions newOptions) -> void @@ -67,23 +61,23 @@ Updates the service's scanner search options. :::{method} pause() -> void :no-index: -Calls the [`Scanner.pause()`](scanner.md#pause) method for all connected scanners. +Calls the [`Scanner.pause()`](scanner.md#the-scanner-interface) method for all connected scanners. ::: :::{method} resume() -> void :no-index: -Calls the [`Scanner.resume()`](scanner.md#resume) method for all connected scanners. +Calls the [`Scanner.resume()`](scanner.md#the-scanner-interface) method for all connected scanners. ::: :::{method} disconnect() -> void :no-index: -Calls the [`Scanner.disconnect()`](scanner.md#disconnect) method for all connected scanners. +Calls the [`Scanner.disconnect()`](scanner.md#the-scanner-interface) method for all connected +scanners. -Should scanners be needed again, -[`ScannerServiceApi.restartScannerDiscovery()`](#restartScannerDiscovery) will need to be called -first. +Should scanners be needed again, `restartScannerDiscovery()` will need to be +called first. ::: ## The `ScannerClient` interface @@ -96,7 +90,7 @@ lifecycle and barcode reads. :::{seealso} This interface extends `ScannerStatusCallback` and needs to implement its method, see more in the -[callbacks documentation](scanner_callbacks.md#the-scannerstatuscallback-interface-and-proxy-class). +[callbacks documentation](scanner_callbacks.md#the-scannerstatuscallback-interface-and-scannerstatuscallbackproxy-class). ::: :::{method} onScannerInitEnded(int count) -> void @@ -153,7 +147,7 @@ Corresponds to the `ScannerServiceApi.EXTRA_SEARCH_WAIT_DISCONNECTED_BOOLEAN` ex :::{cpp:var} boolean returnOnlyFirst = true If true, will only connect to the first scanner available (or reporting it may become available if -[`waitDisconnected`](#waitDisconnected) is true). +`waitDisconnected` is true). If false, all available scanners will be used. @@ -214,24 +208,24 @@ Corresponds to the `ScannerServiceApi.EXTRA_SEARCH_ALLOW_PAIRING_FLOW_BOOLEAN` e Restricts the search to this list of providers. Ignored if null or empty. Mainly used to whitelist known expected devices, or to refine the scanner search using the results -of [`ScannerServiceApi.getAvailableProviders()`](#getAvailableProviders). +of [`ScannerServiceApi.getAvailableProviders()`](#the-scannerserviceapi-interface). Corresponds to the `ScannerServiceApi.EXTRA_SEARCH_ALLOWED_PROVIDERS_STRING_ARRAY` extra. ::: -:::{cpp:var}Set excludedProviderKeys = null +:::{cpp:var} Set excludedProviderKeys = null The providers inside this list will never be used. Ignored if null or empty. Mainly used to blacklist known unwanted devices, or to refine the scanner search using the results -of [`ScannerServiceApi.getAvailableProviders()`](#getAvailableProviders). +of [`ScannerServiceApi.getAvailableProviders()`](#the-scannerserviceapi-interface). Corresponds to the `ScannerServiceApi.EXTRA_SEARCH_EXCLUDED_PROVIDERS_STRING_ARRAY` extra. ::: -:::{cpp:var}Set symbologySelection = null +:::{cpp:var} Set symbologySelection = null -An array of [`BarcodeType`](others.md#barcodeType) to activate. Ignored if null or empty. +An array of [`BarcodeType`](others.md#the-barcodetype-enum) to activate. Ignored if null or empty. Corresponds to the `ScannerServiceApi.EXTRA_SYMBOLOGY_SELECTION` extra. ::: @@ -259,7 +253,7 @@ Updates an intent's extras based on the current option's attributes. ## The `ScannerServiceBinderHelper` class To make the process of binding your application to the Scanner Service easier, the -`ScannerServiceBinderHelper` class exposes a series of **static** methods you can use. +`ScannerServiceBinderHelper` class exposes a series of methods you can use. :::{method} defaultServiceConfiguration() -> Bundle @@ -275,7 +269,7 @@ Static method. Binds to the Scanner Service using the `defaultServiceConfigurati :param Application a: The application to which the service will be bound. :param Bundle extra: Intent extras passed to the service on bind. See - [`ScannerSearchOptions.toIntentExtras()`](#toIntentExtras). + [`ScannerSearchOptions.toIntentExtras()`](#the-scannersearchoptions-class). :returns: The `ScannerServiceBinderHelper` instance that bound to the service. ::: @@ -290,12 +284,12 @@ Static method. Binds to the Scanner Service using the `defaultServiceConfigurati :::{method} getScannerService() -> ScannerServiceApi -:returns: The `ScannerServiceApi` instance bound to this `ScannerServiceBinderHelper`. +:returns: The `ScannerServiceApi` instance bound to this `ScannerServiceBinderHelper` instance. :throws IllegalStateException: If no service is bound when called. ::: :::{method} disconnect() -> void :no-index: -Disconnects the currently-connected service from this `ScannerServiceBinderHelper`. +Disconnects the currently-connected service from this `ScannerServiceBinderHelper` instance. ::: \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 7775dab2..ca69c73c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,6 @@ suppress_warnings = [ 'myst.strikethrough', # We only generate HTML docs, ignore non-html warnings. - 'myst.xref_missing', # Re-enable for debugging and check individually, but anchor links are not correctly recognized and will generate false-positive warnings. ] project = 'enioka Scan' diff --git a/docs/dependencies.md b/docs/dependencies.md index 23749b89..4efbc6de 100644 --- a/docs/dependencies.md +++ b/docs/dependencies.md @@ -1,12 +1,6 @@ # Dependencies and compatible devices -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - -enioka Scan is split over multiple AAR dependencies, all available through the Maven Central +**enioka Scan** is split over multiple AAR dependencies, all available through the Maven Central repository, allowing you to only include the compatibility layers you need. The compatibility matrix at the end of this page explains more clearly what devices are supported by diff --git a/docs/develop.md b/docs/develop.md index 514c7f51..071428bf 100644 --- a/docs/develop.md +++ b/docs/develop.md @@ -1,24 +1,12 @@ # Development -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - -:::{admonition} TODO -:class: attention - -* Edit source links to redirect to the API reference or guides. -::: - -This page will summarize how to modify enioka Scan, whether it is to contribute to the project or -for personal use. +This page will summarize how to modify **enioka Scan**, whether it is to contribute to the project +or for your own needs. ## Developing for Android In order to start developing and testing the library: -- Have Android Studio installed and open the project with it +- Have [Android Studio](https://developer.android.com/studio) installed and open the project with it - Connect a compatible android device via USB, it should then show up in Android Studio's device manager - Run the demo app with the android device selected. The app includes the library and all available @@ -38,7 +26,12 @@ In order to build the documentation, run `sphinx-build -a ./docs `. To view the generated documentation, use the url `file:///index.html` in your web browser. -All documentation is written in markdown. +All documentation is written in markdown. Due to the lack of proper java support, the API reference +was "hacked" using default `method` directives for functions, and `cpp:var` or `cpp:enum` directives +for attributes and enums respectively. + +Note that anchor links to methods and members are not well supported, so in general it is better to +link to the parent class or interface rather than the method or attribute itself. :::{seealso} @@ -50,14 +43,16 @@ how to format documentation content. ## Adding another SDK / Scanner provider -A scanner SDK contains at least a [`Scanner`][scanner-api] implementation (interfacing between the -code and the device) and a [`ScannerProvider`][scanner-provider-api] implementation (handling +A scanner SDK contains at least a [`Scanner` implementation](api/scanner.md#the-scanner-api) +(interfacing between the code and the device) and a +[`ScannerProvider` implementation](api/scanner_provider.md#the-scannerprovider-api) (handling scanner creation and device compatibility checks). -In order for a new scanner SDK to be found by the library, the -[`ScannerProvider`][scanner-provider-api] implementation needs to be declared as a service in its -`AndroidManifest.xml` with an intent-filter containing the action `com.enioka.scan.PROVIDE_SCANNER` -for "regular" devices, and `com.enioka.scan.PROVIDE_SPP_SCANNER` for bluetooth devices. +In order for a new scanner SDK to be found by the library, the +[`ScannerProvider` implementation](api/scanner_provider.md#the-scannerprovider-api) implementation +needs to be declared as a service in its `AndroidManifest.xml`, with an intent-filter containing the +action `com.enioka.scan.PROVIDE_SCANNER` for "regular" devices, and +`com.enioka.scan.PROVIDE_SPP_SCANNER` for bluetooth devices. The associated Java class does not need to extend Android's `Service` class(the `tools:ignore="Instantiatable"` attribute may be added to the service in the manifest), @@ -65,7 +60,11 @@ but it must provide a public default constructor as it will be instantiated usin :::{seealso} -See the [Mock SDK][mock-sdk] for an example of addon SDK. +* The [`Scanner` interface](api/scanner.md) documentation +* The [`ScannerProvider` interface](api/scanner_provider.md) documentation +* The sources of various scanner providers on the + [GitHub repository](https://github.com/enioka-Haute-Couture/enioka_scan), mainly the + [Mock SDK](https://github.com/enioka-Haute-Couture/enioka_scan/tree/master/enioka_scan_mock) ::: ## Library tests @@ -89,7 +88,3 @@ artefact of the core library, and will upload all artefacts to Maven Central. The release tag ***must*** be pushed from the CLI, as a tag or release created from the GitHub web UI will fail to trigger the workflow. ::: - -[mock-sdk]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan_mock -[scanner-api]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/api/Scanner.java -[scanner-provider-api]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/api/ScannerProvider.java diff --git a/docs/guides/custom_layout.md b/docs/guides/custom_layout.md new file mode 100644 index 00000000..bc4a063e --- /dev/null +++ b/docs/guides/custom_layout.md @@ -0,0 +1,49 @@ +# Using a custom layout with the scanning activity + +In order to use a custom layout with the provided `ScannerCompatActivity`, two fields need to be +changed to point it. You can change these attributes in your activity's `onCreate()` lifecycle +step. + +```java +import com.enioka.scanner.activities.ScannerCompatActivity; + +public class MyScanningActivity extends ScannerCompatActivity { + + @Override + protected void onCreate(@Nullable Bundle savedInstanceState) { + super.onCreate(); + layoutIdLaser = R.layout.activity_parcel_scan_laser; + layoutIdCamera = R.layout.activity_parcel_scan_camera; + } +} +``` + +Here, `layoutIdLaser` is the layout used when handling laser scanner devices, and `layoutIdCamera` +is the layout used when using the device's camera as a scanner. + +To ensure activity is able to properly switch to the camera when needed, you should include the +following view block in the `.xml` file used by `layoutIdCamera`: + +```xml + +``` + +Should you choose a different ID for this view, remember to also change the value of `cameraViewId` +in the activity. + +:::{seealso} + +* The [scanner activity](../api/scanner_activity.md) documentation +* The [camera](../api/camera.md) documentation +::: \ No newline at end of file diff --git a/docs/guides/index.md b/docs/guides/index.md index 67dc1803..35deb2c8 100644 --- a/docs/guides/index.md +++ b/docs/guides/index.md @@ -1,9 +1,10 @@ # Guides -:::{admonition} WIP -:class: attention +This sections contains quick guides to reach specific desired outcomes without having to dig too +deep in the [API reference](../api/index.md). -This documentation is a work in progress. -::: +:::{toctree} +:maxdepth: 1 -This page is the index of the quick guides section. \ No newline at end of file +custom_layout +::: \ No newline at end of file diff --git a/docs/index.md b/docs/index.md index ce8ed489..47cd200b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,11 +1,5 @@ # enioka Haute Couture Android Barcode Scanning Library -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - This library makes the integration of all barcode scanners easy in any Android application, avoiding vendor lock-in and lowering the cost of advanced scanner integration. @@ -38,4 +32,9 @@ dependencies guides/index api/index develop +::: + +:::{seealso} + +* The [GitHub repository](https://github.com/enioka-Haute-Couture/enioka_scan) of the library ::: \ No newline at end of file diff --git a/docs/quickstart.md b/docs/quickstart.md index 69713b8a..b4baff60 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,22 +1,5 @@ # Quick Start -:::{admonition} WIP -:class: attention - -This documentation is a work in progress. -::: - -:::{admonition} TODO -:class: attention - -* Edit source links to redirect to the API reference or guides. -* Simplify the quickstart to only include the bare minimum necessary for the lib to function. - Further details should be put in a dedicated page in [guides](guides/index.md). -* Add an explanation of the scanner creation process, from the start of the service to the ability - to interact with the scanner. This will be important to direct users to the correct guides or API - reference pages, especially when it comes to bluetooth, which deserves its own category. -::: - This guide will show you the minimum required steps to include **enioka Scan** in your application. It assumes that you already have a configured Android Studio project. @@ -37,20 +20,22 @@ dependencies { ``` Depending on your scanning devices, this single dependency may be enough. For some devices, other -dependencies are required, you can check [Dependencies](dependencies.md) for a detailed overview. +dependencies are required, you can check the +[library dependencies and compatibility matrix](dependencies.md) for a detailed overview. ## Using the library There are different ways to use the library, depending on where it has to be used. And in any ways, the library does not hide its low-level objects which are an always available fallback. Most scanner -capabilities are exposed through the [`Scanner`][scanner-api] API, though the default behavior of -the [`ScannerServiceApi`][scanner-service-api] API ought to be enough for simply receiving scanned -data. +capabilities are exposed through the [`Scanner` API](api/scanner.md#the-scanner-interface), though +the default behavior of the +[`ScannerServiceApi` API](api/scanner_service.md#the-scannerserviceapi-interface) ought to be enough +for simply receiving scanned data. ### Using enioka Scan in an activity The simplest way to use **enioka Scan** is to extend the provided -[`ScannerCompatActivity`][scanner-compat-activity]: +[`ScannerCompatActivity` activity](api/scanner_activity.md): ```java import com.enioka.scanner.activities.ScannerCompatActivity; @@ -63,44 +48,7 @@ This creates an activity with a very simple layout, which displays status messag as well as scanning results and some utility buttons: triggers for the scanner, a toggle for illumination, and a beep trigger. -Now, most activities of course want to use their own layouts. This is allowed by setting two fields -(one for the camera layout, one for the laser layout) in the constructor of the activity: - -```java -@Override -protected void MyScanningActivity() { - super.onCreate(); - layoutIdLaser = R.layout.activity_parcel_scan_laser; - layoutIdCamera = R.layout.activity_parcel_scan_camera; -} -``` - -There are a few other fields to allow you to customize further the activity, which are all -documented inside the class. These include options to rename the toggle illumination button ID, to -disable camera or laser or both, or enable a fallback dialog with manual input and auto-completion. - -If the provided template does not suit your needs, but you still want to take advantage of the -[`ScannerServiceApi`][scanner-service-api], simply make sure that your activity follows the steps -described in the section below. - -if you use a custom layout, you need to use our Camera scanning view. The ID of this view should by -default be `camera_scan_view` (which can be customized inside the constructor as for the other -views). This view accepts a few parameters, which are displayed here with their default values: - -```xml - -``` +To use your own layouts with this activity, you can follow [this guide](guides/custom_layout.md). Finally, note that inside the activity code there are a few hooks that can be overloaded - these are public or protected methods, with full javadoc. Of notice are: @@ -108,50 +56,20 @@ public or protected methods, with full javadoc. Of notice are: * `onData(List data)` * `onStatusChanged(Scanner, ScannerStatusCallback.Status)` -### Using enioka Scan outside of an activity +:::{seealso} -The library exposes a service which can be bound as any other bound service: - -```java -ScannerServiceApi scannerService; -boolean serviceBound = false; - -ServiceConnection connection = new ServiceConnection() { - @Override - public void onServiceConnected(ComponentName className, - IBinder service) { - // We've bound to ScannerService, cast the IBinder and get the ScannerServiceApi instance - ScannerService.LocalBinder binder = (ScannerService.LocalBinder) service; - scannerService = binder.getService(); - serviceBound = true; - } - - @Override - public void onServiceDisconnected(ComponentName arg0) { - serviceBound = false; - scannerService = null; - } - }; - -// Bind to ScannerService service -// Make sure to bind the ScannerService class (or any implementation of the API), not the ScannerServiceApi interface -Intent intent = new Intent(this, ScannerService.class); -bindService(intent, connection, Context.BIND_AUTO_CREATE); -``` +* The [`ScannerCompatActivity` activity](api/scanner_activity.md) documentation +* The [`ScannerClient` interface](api/scanner_service.md#the-scannerclient-interface) documentation +::: -It is then possible to use the [`ScannerServiceApi`][scanner-service-api] object to access the -different endpoints of the service. The most interesting one is `registerClient()` which hooks -scanning callbacks and scanner/provider discovery notifications to a class implementing the -[`ScannerClient`][scanner-client] interface such as a custom activity. +### Using enioka Scan outside of an activity -Please remember to unbind the service when it is not needed anymore, as for any other service. This -will often be in "onDestroy" hooks. Also, as this is a bound service, it is destroyed whenever it -has no bound clients left. Many applications actually bind the service on startup onto the -application context to be sure it is never destroyed and therefore is very quick to bind from -anywhere, but this depends on the use-case and is not compulsory at all. +The library exposes a service which can be bound as any other bound service. `ScannerCompatActivity` +actually uses this service to handle scanner connexions, and you are free to use it directly in your +application. -If you want to bind the service inside your application class, a helper is provided to avoid -boilerplate code that can be used as such: +**enioka Scan** provides a helper class that reduces the boilerplate code required to bind the +service to your application class: ```java public class App extends Application { @@ -162,20 +80,37 @@ public class App extends Application { super.onCreate(); serviceBinder = ScannerServiceBinderHelper.bind(this); // a second overload exists with a configuration Bundle. } - - @Override - public void onTerminate() { - super.onTerminate(); - serviceBinder.disconnect(); + + // You may then call service methods directly + public void myMethod() { + serviceBinder.getScannerService().registerClient(/* ... */); } } ``` -Finally, there are a few Intent extra properties which can be set to control the behaviour of the -service such as filters used in the scanner search. -These can be found as static strings inside the [`ScannerServiceApi`][scanner-service-api] interface -, and methods in the [`ScannerSearchOptions`][scanner-search-options] class help converting search -parameters to and from those intent extras. +It is then possible to use the +[`ScannerServiceApi` instance](api/scanner_service.md#the-scannerserviceapi-interface) to access the +different endpoints of the service. The most interesting one is `registerClient()` which hooks +scanning callbacks and scanner/provider discovery notifications to a class implementing the +[`ScannerClient` interface](api/scanner_service.md#the-scannerclient-interface) such as a custom +activity. + +Please remember to unbind the service when it is not needed anymore, as for any other service. This +will often be in "onDestroy" hooks. Also, as this is a bound service, it is destroyed whenever it +has no bound clients left. Many applications actually bind the service on startup onto the +application context to be sure it is never destroyed and therefore is very quick to bind from +anywhere, but this depends on the use-case and is not compulsory at all. + +Finally, there are a few Intent Extra properties which can be set to control the behaviour of the +service such as filters used in the scanner search. These can be found as static strings inside +the [`ScannerServiceApi` interface](api/scanner_service.md#the-scannerserviceapi-interface), and +methods in the [`ScannerSearchOptions` class](api/scanner_service.md#the-scannersearchoptions-class) +help converting search parameters to and from those intent extras. + +:::{seealso} + +* The [Scanner Service API](api/scanner_service.md) documentation +::: ## Using the camera @@ -197,8 +132,7 @@ scanning. The provided Camera activity will display a target rectangle, which can be moved or tapped to change or refresh the autofocus area. -[scanner-api]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/api/Scanner.java -[scanner-client]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/service/ScannerClient.java -[scanner-compat-activity]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/activities/ScannerCompatActivity.java -[scanner-search-options]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/api/ScannerSearchOptions.java -[scanner-service-api]: https://github.com/enioka-Haute-Couture/enioka_scan/blob/master/enioka_scan/src/main/java/com/enioka/scanner/service/ScannerServiceApi.java +:::{seealso} + +* The [camera](api/camera.md) documentation +::: \ No newline at end of file