Skip to content

Commit

Permalink
update: Documentation to support the camera SDK refactor
Browse files Browse the repository at this point in the history
  • Loading branch information
@VincentKobz
VincentKobz committed Apr 18, 2024
1 parent ff4e180 commit 356e027
Show file tree
Hide file tree
Showing 4 changed files with 115 additions and 56 deletions.
95 changes: 92 additions & 3 deletions docs/api/camera.md
View file
Original file line number Diff line number Diff line change
@@ -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<ManualInputItem> 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<String> autocompletion, int threshold) -> void

**Inserts** the given autocompletion strings into the `autocompletionItems` and updates the
autocompletion threshold.

:param List<String> autocompletion: The autocompletion items to add.
:param int threshold: The new threshold.
:::

:::{method} setAutocompletionItems(List<ManualInputItem> items, int threshold) -> void

**Replaces** `autocompletionItems` with the given list and updates the autocompletion threshold.

:param List<String> 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
Expand Down
41 changes: 0 additions & 41 deletions docs/api/scanner_activity.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand Down
9 changes: 7 additions & 2 deletions docs/dependencies.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,12 @@ Each artefact can be imported to your project as `com.enioka.scanner:<artefact>:
### `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`

Expand Down Expand Up @@ -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 |
Expand Down
26 changes: 16 additions & 10 deletions docs/quickstart.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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
Expand Down

0 comments on commit 356e027

Please sign in to comment.