Get Started
In this guide you will learn step-by-step how to add MatrixScan to your application.
The general steps are:
- Creating a new Data Capture Context instance
- Configuring the MatrixScan mode
- Using the built-in camera
- Visualizing the scan process
- Providing feedback
- Disabling barcode tracking
Create a Data Capture Context
The first step to add capture capabilities to your application is to create a new data capture context. The context expects a valid Scandit Data Capture SDK license key during construction.
DataCaptureContext context = DataCaptureContext.ForLicenseKey("-- ENTER YOUR SCANDIT LICENSE KEY HERE --");
Configure the Barcode Batch Mode
The main entry point for the Barcode Batch Mode is the BarcodeBatch object. It is configured through BarcodeBatchSettings and allows to register one or more listeners that will get informed whenever a new frame has been processed.
Most of the times, you will not need to implement a IBarcodeBatchListener, instead you will add a BarcodeBatchBasicOverlay and implement a IBarcodeBatchBasicOverlayListener.
For this tutorial, we will setup Barcode Batch for tracking QR codes.
BarcodeBatchSettings settings = BarcodeBatchSettings.Create();
settings.EnableSymbology(Symbology.Qr, true);
Next, create a BarcodeBatch instance with the data capture context and the settings initialized in the previous steps:
BarcodeBatch barcodeBatch = BarcodeBatch.Create(context, settings);
Use the Built-in Camera
The data capture context supports using different frame sources to perform recognition on. Most applications will use the built-in camera of the device, e.g. the world-facing camera of a device. The remainder of this tutorial will assume that you use the built-in camera.
In Android, the user must explicitly grant permission for each app to access cameras. Your app needs to declare the use of the Camera permission in the AndroidManifest.xml file and request it at runtime so the user can grant or deny the permission. To do that follow the guidelines from Permissions in Android to request the android.permission.CAMERA permission.
When using the built-in camera there are recommended settings for each capture mode. These should be used to achieve the best performance and user experience for the respective mode. The following couple of lines show how to get the recommended settings and create the camera from it:
camera = Camera.GetDefaultCamera();
camera?.ApplySettingsAsync(BarcodeBatch.RecommendedCameraSettings);
Because the frame source is configurable, the data capture context must be told which frame source to use. This is done with a call to DataCaptureContext.SetFrameSourceAsync():
context.SetFrameSourceAsync(camera);
The camera is off by default and must be turned on. This is done by calling IFrameSource.SwitchToDesiredStateAsync() with a value of FrameSourceState.On:
camera?.SwitchToDesiredStateAsync(FrameSourceState.On);
Use a Capture View to Visualize the Scan Process
When using the built-in camera as frame source, you will typically want to display the camera preview on the screen together with UI elements that guide the user through the capturing process. To do that, add a DataCaptureView to your view hierarchy:
DataCaptureView dataCaptureView = DataCaptureView.Create(this, dataCaptureContext);
SetContentView(dataCaptureView);
Alternatively you can use a DataCaptureView from XAML in your MAUI application. For example:
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:scandit="clr-namespace:Scandit.DataCapture.Core.UI.Maui;assembly=ScanditCaptureCoreMaui">
<ContentPage.Content>
<AbsoluteLayout>
<scandit:DataCaptureView x:Name="dataCaptureView" AbsoluteLayout.LayoutBounds="0,0,1,1"
AbsoluteLayout.LayoutFlags="All" DataCaptureContext="{Binding DataCaptureContext}">
</scandit:DataCaptureView>
</AbsoluteLayout>
</ContentPage.Content>
</ContentPage>
You can configure your view in the code behind class. For example:
public partial class MainPage : ContentPage
{
public MainPage()
{
InitializeComponent();
// Initialization of DataCaptureView happens on handler changed event.
dataCaptureView.HandlerChanged += DataCaptureViewHandlerChanged;
}
private void DataCaptureViewHandlerChanged(object? sender, EventArgs e)
{
// Your dataCaptureView configuration goes here, e.g. add overlay
}
}
For MAUI development add Scandit.DataCapture.Core.Maui NuGet package into your project.
To visualize the results of Barcode Batch, first you need to add the following overlay:
BarcodeBatchBasicOverlay overlay = BarcodeBatchBasicOverlay.Create(barcodeBatch, dataCaptureView);
Once the overlay has been added, you should implement the IBarcodeBatchBasicOverlayListener interface. The method IBarcodeBatchBasicOverlayListener.BrushForTrackedBarcode() is invoked every time a new tracked barcode appears and it can be used to set a brush that will be used to highlight that specific barcode in the overlay.
public Brush BrushForTrackedBarcode(BarcodeBatchBasicOverlay overlay, TrackedBarcode trackedBarcode)
{
// Return a custom Brush based on the tracked barcode.
}
If you would like to make the highlights tappable, you need to implement the IBarcodeBatchBasicOverlayListener.OnTrackedBarcodeTapped() method.
public void OnTrackedBarcodeTapped(BarcodeBatchBasicOverlay overlay, TrackedBarcode trackedBarcode)
{
// A tracked barcode was tapped.
}
Get Barcode Batch Feedback
Barcode Batch, unlike Barcode Capture, doesn’t emit feedback (sound or vibration) when a new barcode is recognized. However, you may implement a IBarcodeBatchListener to provide a similar experience. Below, we use the default Feedback, but you may configure it with your own sound or vibration if you want.
protected override void OnResume()
{
base.OnResume();
feedback = Feedback.DefaultFeedback;
}
protected override void OnPause()
{
base.OnPause();
feedback.Dispose();
}
Next, use this feedback in a IBarcodeBatchListener:
public class FeedbackListener : Java.Lang.Object, IBarcodeBatchListener
{
public void OnObservationStarted(BarcodeBatch barcodeBatch)
{
// Called when Barcode Batch is started.
// We don't use this callback in this guide.
}
public void OnObservationStopped(BarcodeBatch barcodeBatch)
{
// Called when Barcode Batch is stopped.
// We don't use this callback in this guide.
}
public void OnSessionUpdated(BarcodeBatch barcodeBatch, BarcodeBatchSession session, IFrameData frameData)
{
if (session.AddedTrackedBarcodes.Any())
{
this.feedback.Emit();
}
}
}
IBarcodeBatchListener.OnSessionUpdated() is invoked for every processed frame. The session parameter contains information about the currently tracked barcodes, in particular, the newly recognized ones. We check if there are any and if so, we emit the feedback.
As the last step, register the listener responsible for emitting the feedback with the BarcodeBatch instance.
barcodeBatch.AddListener(feedbackListener);
Disabling Barcode Batch
To disable barcode tracking set BarcodeBatch.Enabled to false. The effect is immediate: no more frames will be processed after the change. However, if a frame is currently being processed, this frame will be completely processed and deliver any results/callbacks to the registered listeners.
Note that disabling the capture mode does not stop the camera, the camera continues to stream frames until it is turned off or put it in standby calling SwitchToDesiredState with a value of StandBy.