Version 3.0 of the Android RedLaser SDK allows for custom overlays in the scan screen. It is not necessary to use the overlay provided in the sample application. The provided layouts may be modified or replaced with your own layout files. In addition, any UI components, such as text, buttons, or the view finder, may be replaced with your own assets. If you wish to change the view finder, it is recommended to replace it with a scalable 9-patch drawable to facilitate support for different screen sizes.The sample application contains three layouts for the scan screen overlay:
If the orientation of the scan screen is set to portrait, two different overlays must be used (preview_overlay_new_portrait.xml and preview_overlay_old_portrait.xml) if the application is to support phones with OS’s both older than and newer than Android 2.2. Preview_overlay_old_portrait.xml is for older than Android 2.2 and preview_overlay_new_portrait.xml is for 2.2 and later. There are APIs in Android 2.2 and later that are necessary to have a portrait camera overlay that are not available in older devices.
Because of that, RedLaser SDK includes some UI components that must be used for the older devices.On Android, the best way to consistently get a camera preview that is set to the correct orientation and aspect ratio across all devices is to set the activity orientation to landscape. However, because the most popular use cases of RedLaser require portrait orientation, this is not a viable solution since setting the orientation of the activity to landscape also sets the orientation of the preview overlay to landscape.
To work around this problem, RedLaser provides a set of UI components and a special layout, located in package com.ebay.redlaser.uicomponents.*. The components can be drawn with a 90 degree counter-clockwise rotation so they appear to be in portrait orientation while the activity is set to landscape orientation. A layout was also created to facilitate any layouts that use these rotated components. These components should only be used for API levels below 8 and if the activity orientation is set to landscape while the overlay orientation is desired to be landscape. The usage of RedLaser’s UI components is described below.
This attribute is an extension of the Android Button. The added capability of this button is that you can specify the orientation that the button is to be drawn in. For example, if you want the button to be drawn in portrait orientation, then you set the orientation attribute to “portrait” and the button will be drawn rotated 90 degrees clockwise. A limitation of the RotatedButton is that the size of the component must be specified in the xml. Android’s wrap-content, fill-parent, and match-parent cannot be used with RotatedButton. Aside from this limitation, any attribute available in Android’s Button is also available in RotatedButton. The following is the additional attribute of RotatedButton:
- orientation – This attribute is used to set the orientation of this RotatedButton. Possible values are “landscape” and “portrait”.
This attribute is an extension of the Android ImageView. The added capability of this view is that you can specify the orientation that the image is to be drawn in. For example, if you want the image to be drawn in portrait orientation, then you set the orientation attribute to “portrait” and the image will be drawn rotated 90 degrees clockwise. A limitation of the RotatedImageView is that the size of the component must be specified in the xml. Android’s wrap-content, fill-parent, and match-parent cannot be used with RotatedImageView. Aside from this limitation, any attribute available in Android’s ImageView is also available in RotatedImageView. The following is the additional attribute of RotatedImageView:
- orientation – This attribute is used to set the orientation of this RotatedImageView. Possible values are “landscape” and “portrait”.
This attribute is an extension of the Android TextView. The added capability of this view is that you can specify the orientation that the text view is to be drawn in. For example, if you want the text view to be drawn in portrait orientation, then you set the orientation attribute to “portrait” and the text view will be drawn rotated 90 degrees clockwise. A limitation of the RotatedTextView is that the size of the component must be specified in the xml. Android’s wrap-content, fill-parent, and match-parent cannot be used with RotatedTextView. The following is the additional attribute of RotatedTextView:
- orientation – This attribute is used to set the orientation of this RotatedTextView. Possible values are “landscape” and “portrait”.
An example of how to use these components can be seen in the layout file preview_overlay_old_portrait.xml. An explanation of the file is described below:
<?xml version="1.0" encoding="utf-8"?>
First, the namespace for RedLaser must be defined at the beginning of the xml. In the sample application, this is done on the line xmlns:rl “http://schemas.android.com/apk/libs/com.ebay.RLSample”. After the namespace has been set, the rest of the xml can be written just like any other android xml layout. Remember to include the entire package name of any RedLaser UI components and to use the corresponding namespace with any attributes you are setting. For example:
If you want the scan screen overlay to appear in landscape, then there is no need for a separate layout to be written for API levels below and above 8. Simply set the activity orientation to landscape and create the layout in xml using normal Android components.
Capturing Barcodes in Sections
The 3.0 SDK introduces a new method of scanning barcodes, where the user can scan a barcode in parts and the SDK will stitch the parts together to recognize the full barcode. This scan method is useful for capturing long barcodes on older devices, where the camera resolution isn’t high enough to resolve the entire barcode at once.
Currently, this new method only works for Code 39 barcodes, like those used for vehicle identification numbers [VINs].
The algorithm to stitch partial barcodes is always enabled in the SDK, however without app-level support in the overlay to guide the user, it is very unlikely a user will ever find it. This section is a discussion of how to design your overlay UI to guide a user through the process of scanning a barcode in parts. Note that all of the cues from the SDK relating to this feature can be safely ignored if you don’t want to support partial barcode scanning–you don’t have to do anything.
Many SDK clients aren’t using Code 39 in their apps, and even some of those that are may not need this feature. For developers that need Code 39 support in their app, adding this optional feature can lead to a better user experience, particularly for users with older devices trying to scan Code 39 codes in excess of ~15 characters in length.
The basic interaction for partial barcode scanning is that the SDK tells the overlay what it sees, and the overlay tells the user what to do to successfully complete the scan. The communication from the SDK to the overlay happens through the “Guidance” and “PartialBarcode” keys obtained from the onScanStatusUpdate() callback method.
Guidance == 1
After a couple of seconds where the SDK sees that the user is pointing the camera at something that looks like a barcode, if the SDK has not recognized the barcode yet it will start returning 1 in the “Guidance” key of the status update.
Note that at this point the SDK isn’t claiming to know for sure if it’s looking at a Code 39 barcode, or for that matter any kind of barcode; it is just looking at something vaguely barcode-like that the SDK can’t fully recognize.
When the Guidance key goes to 1, the overlay should advise the user to try scanning the barcode in parts by holding the phone close to the first part of the barcode, and then scanning across slowly. See the image below.
Once the user does this, the first part of the barcode may be scanned, at which time the Guidance key changes to 2.
Guidance == 2
When the guidance changes to 2, an additional key is available, “PartialBarcode”. This key contains the text of the barcode that has so far been decoded. In the example shown below, the partial barcode contains “JT5MAJ07” (the ellipsis is added by the overlay in this example).
As the user scans their device across the barcode, characters will be added to the partial barcode, as shown in the images above. When they reach the end of the barcode, the completed code is added to the set of found barcodes, and will be delivered as a newly found barcode in the next call to onScanStatusUpdate().
Once a barcode has been fully scanned, the Guidance key goes back to zero and the PartialBarcode key will no longer be sent to the overlay during that scan session.