Skip to content

Commit

Permalink
Update component docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Redth
Redth committed Dec 18, 2015
1 parent 9ab9223 commit ee457e9
Show file tree
Hide file tree
Showing 3 changed files with 160 additions and 241 deletions.
91 changes: 7 additions & 84 deletions Component-Forms/Details.md
View file
Original file line number Diff line number Diff line change
@@ -1,90 +1,13 @@
ZXing.Net.Mobile is a C#/.NET library based on the open source Barcode Library: ZXing (Zebra Crossing), using the ZXing.Net Port. It works with Xamarin.iOS, Xamarin.Android, and Windows Phone. The goal of ZXing.Net.Mobile is to make scanning barcodes as effortless and painless as possible in your own applications!
ZXing.Net.Mobile for Forms is a C#/.NET library based on the open source Barcode Library: ZXing (Zebra Crossing), using the ZXing.Net Port. It works with Xamarin.iOS, Xamarin.Android, Windows Phone Silverlight, and Windows Universal in Xamarin.Forms apps.

GitHub Project: https://github.com/Redth/ZXing.Net.Mobile
The goal of ZXing.Net.Mobile is to make scanning barcodes as effortless and painless as possible in your own applications!

### Usage
```csharp
buttonScan.Click += (sender, e) => {

//NOTE: On Android, you MUST pass a Context into the Constructor!
var scanner = new ZXing.Mobile.MobileBarcodeScanner();
var result = await scanner.Scan();

if (result != null)
Console.WriteLine("Scanned Barcode: " + result.Text);
};
```
## Features


###Features
- Xamarin.Forms Page and Views
- Custom Overlays in XAML or C#
- Xamarin.iOS
- Xamarin.Android
- Windows Phone
- Simple API - Scan in as little as 2 lines of code!
- Scanner as a View - UIView (iOS) / Fragment (Android) / Control (WP)


###Custom Overlays
By default, ZXing.Net.Mobile provides a very simple overlay for your barcode scanning interface. This overlay consists of a horizontal red line centered in the scanning 'window' and semi-transparent borders on the top and bottom of the non-scanning area. You also have the opportunity to customize the top and bottom text that appears in this overlay.

If you want to customize the overlay, you must create your own View for each platform. You can customize your overlay like this:

```csharp
var scanner = new ZXing.Mobile.MobileBarcodeScanner();
scanner.UseCustomOverlay = true;
scanner.CustomOverlay = myCustomOverlayInstance;
var result = await scanner.Scan();
//Handle result
```

Keep in mind that when using a Custom Overlay, you are responsible for the entire overlay (you cannot mix and match custom elements with the default overlay). The *ZxingScanner* instance has a *CustomOverlay* property, however on each platform this property is of a different type:

- Xamarin.iOS => **UIView**
- Xamarin.Android => **View**
- Windows Phone => **UIElement**

All of the platform samples have examples of custom overlays.

###Barcode Formats
By default, all barcode formats are monitored while scanning. You can change which formats to check for by passing a ZxingScanningOptions instance into the StartScanning method:

```csharp
var options = new ZXing.Mobile.MobileBarcodeScanningOptions();
options.PossibleFormats = new List<ZXing.BarcodeFormat>() {
ZXing.BarcodeFormat.Ean8, ZXing.BarcodeFormat.Ean13
};

var scanner = new ZXing.Mobile.MobileBarcodeScanner();
var result = await scanner.Scan(options);
//Handle result
```

###Using the ZXingScanner View / Fragment / Control
On each platform, the ZXing scanner has been implemented as a reusable component (view, fragment, or control), and it is possible to use the reusable component directly without using the MobileBarcodeScanner class at all. On each platform, the instance of the view/fragment/control contains the necessary properties and methods required to control your scanner. By default, the default overlay is automatically used, unless you set the CustomOverlay property as well as the UseCustomOverlay property on the instance of the view/fragment/control. You can use methods such as ToggleTorch() or StopScanning() on the view/fragment/control, however you are responsible for calling StartScanning(...) with a callback and an instance of MobileBarcodeScanningOptions when you are ready for the view's scanning to begin. You are also responsible for stopping scanning if you want to cancel at any point.

The view/fragment/control classes for each platform are:

- iOS: ZXingScannerView (UIView) - See ZXingScannerViewController.cs View Controller for an example of how to use this view
- Android: ZXingScannerFragment (Fragment) - See ZXingActivity.cs Activity for an example of how to use this fragment
- Windows Phone: ZXingScannerControl (UserControl) - See ScanPage.xaml Page for an example of how to use this Control


###Using Apple's AVCaptureSession (iOS7 Built in) Barcode Scanning
In iOS7, Apple added some API's to allow for scanning of barcodes in an AVCaptureSession. The latest version of ZXing.Net.Mobile gives you the option of using this instead of the ZXing scanning engine. You can use the `AVCaptureScannerView` or the `AVCaptureScannerViewController` classes directly just the same as you would use their ZXing* equivalents. Or, in your `MobileBarcodeScanner`, there is now an overload to use the AV Capture Engine:

```csharp
//Scan(MobileBarcodeScanningOptions options, bool useAVCaptureEngine)
scanner.Scan(options, true);
```
In the MobileBarcodeScanner, even if you specify to use the AVCaptureSession scanning, it will gracefully degrade to using ZXing if the device doesn't support this (eg: if it's not iOS7 or newer), or if you specify a barcode format in your scanning options which the AVCaptureSession does not support for detection. The AVCaptureSession can only decode the following barcodes:

- Aztec
- Code 128
- Code 39
- Code 93
- EAN13
- EAN8
- PDF417
- QR
- UPC-E

- Windows Phone (Silverlight)
- Windows Universal (UAP 10)
222 changes: 147 additions & 75 deletions Component-Forms/GettingStarted.md
View file
Original file line number Diff line number Diff line change
@@ -1,106 +1,178 @@
# Getting Started #
# Getting Started

You can use ZXing.Net.Mobile for Forms in your iOS, Android, Windows Phone (Silverlight) and Windows Universal Forms projects.
ZXing.Net.Mobile for Forms is meant to be used in your Xamarin.Forms apps. It comes with Forms controls and pages for scanning and displaying barcodes.

### Usage
The simplest example of using ZXing.Net.Mobile looks something like this:
If you are looking for barcode scanning functionality in your non-Forms Xamarin / Windows apps, check out the original [ZXing.Net.Mobile Component](https://components.xamarin.com/view/zxing.net.mobile).

```csharp
buttonScan.Click += (sender, e) => {

//NOTE: On Android you MUST pass a Context into the Constructor!
var scanner = new ZXing.Mobile.MobileBarcodeScanner();
var result = await scanner.Scan();
# Usage

if (result != null)
Console.WriteLine("Scanned Barcode: " + result.Text);
The easiest way to use scanner is to create an instance of the `ZXingScannerPage`:

```csharp
var scanPage = new ZXingScannerPage ();

scanPage.OnScanResult += (result) => {
// Stop scanning
scanPage.IsScanning = false;

// Pop the page and show the result
Device.BeginInvokeOnMainThread (() => {
Navigation.PopAsync ();
DisplayAlert("Scanned Barcode", result.Text, "OK");
});
};

// Navigate to our scanner page
await Navigation.PushAsync (scanPage);
```

### Android Versions
The component should work on Android 2.2 or higher. In Xamarin.Android there are 3 places in the project settings relating to Android version. YOU ***MUST*** set the Project Options -> Build -> General -> Target Framework to ***2.3*** or higher. If you still want to use 2.2, you can set the Project Options -> Build -> Android Application -> Minimum Android version to 2.2, but be sure to set the Target Android version in this section to 2.3 or higher.
If you need more customization, you can also use the `ZXingScannerView` in your own custom page:

```csharp
using Xamarin.Forms;
using ZXing.Net.Mobile.Forms;

namespace FormsSample
{
public class CustomScanPage : ContentPage
{
ZXingScannerView zxing;
ZXingDefaultOverlay overlay;

public CustomScanPage () : base ()
{
zxing = new ZXingScannerView
{
HorizontalOptions = LayoutOptions.FillAndExpand,
VerticalOptions = LayoutOptions.FillAndExpand
};
zxing.OnScanResult += (result) =>
Device.BeginInvokeOnMainThread (async () => {

// Stop analysis until we navigate away so we don't keep reading barcodes
zxing.IsAnalyzing = false;

// Show an alert
await DisplayAlert ("Scanned Barcode", result.Text, "OK");

// Navigate away
await Navigation.PopAsync ();
});

overlay = new ZXingDefaultOverlay
{
TopText = "Hold your phone up to the barcode",
BottomText = "Scanning will happen automatically",
ShowFlashButton = zxing.HasTorch,
};
overlay.FlashButtonClicked += (sender, e) => {
zxing.IsTorchOn = !zxing.IsTorchOn;
};
var grid = new Grid
{
VerticalOptions = LayoutOptions.FillAndExpand,
HorizontalOptions = LayoutOptions.FillAndExpand,
};
grid.Children.Add(zxing);
grid.Children.Add(overlay);

// The root page of your application
Content = grid;
}

protected override void OnAppearing()
{
base.OnAppearing();

zxing.IsScanning = true;
}

protected override void OnDisappearing()
{
zxing.IsScanning = false;

base.OnDisappearing();
}
}
}
```

You must also add a reference to the Component `Android Support Library v4` https://components.xamarin.com/view/xamandroidsupportv4-18 from the Component Store.

###Custom Overlays
By default, ZXing.Net.Mobile provides a very simple overlay for your barcode scanning interface. This overlay consists of a horizontal red line centered in the scanning 'window' and semi-transparent borders on the top and bottom of the non-scanning area. You also have the opportunity to customize the top and bottom text that appears in this overlay.
##Custom Overlays

If you want to customize the overlay, you must create your own View for each platform. You can customize your overlay like this:
It's very simple to use a custom overlay. If you are using the `ZXingScannerPage` you can pass in any `View` for the `customOverlay` parameter in the constructor.

```csharp
var scanner = new ZXing.Mobile.MobileBarcodeScanner();
scanner.UseCustomOverlay = true;
scanner.CustomOverlay = myCustomOverlayInstance;
var result = await scanner.Scan();
//Handle result
// Create our custom overlay
var customOverlay = new StackLayout {
HorizontalOptions = LayoutOptions.FillAndExpand,
VerticalOptions = LayoutOptions.FillAndExpand
};
var torch = new Button {
Text = "Toggle Torch"
};
torch.Clicked += delegate {
scanPage.ToggleTorch ();
};
customOverlay.Children.Add (torch);

// Pass in the custom overlay
scanPage = new ZXingScannerPage (customOverlay: customOverlay);
scanPage.OnScanResult += (result) => {
scanPage.IsScanning = false;

Device.BeginInvokeOnMainThread(() =>
{
Navigation.PopAsync();
DisplayAlert("Scanned Barcode", result.Text, "OK");
});
};
await Navigation.PushAsync (scanPage);
```

Keep in mind that when using a Custom Overlay, you are responsible for the entire overlay (you cannot mix and match custom elements with the default overlay). The *ZxingScanner* instance has a *CustomOverlay* property, however on each platform this property is of a different type:
If you are using `ZXingScannerView` on your own page, of course you are responsible for adding your own overlay.

- Xamarin.iOS => **UIView**
- Xamarin.Android => **View**
- Windows Phone => **UIElement**

All of the platform samples have examples of custom overlays.
## Barcode Formats

###Barcode Formats
By default, all barcode formats are monitored while scanning. You can change which formats to check for by passing a ZxingScanningOptions instance into the StartScanning method:
By default, all barcode formats are monitored while scanning. You can change which formats to check for by passing a `MobileBarcodeScanningOptions` instance into the `ZXingScannerPage`'s constructor.

```csharp
var options = new ZXing.Mobile.MobileBarcodeScanningOptions();
options.PossibleFormats = new List<ZXing.BarcodeFormat>() {
ZXing.BarcodeFormat.Ean8, ZXing.BarcodeFormat.Ean13
ZXing.BarcodeFormat.Ean8, ZXing.BarcodeFormat.Ean13
};

var scanner = new ZXing.Mobile.MobileBarcodeScanner();
var result = await scanner.Scan(options);
//Handle result
```
var scanPage = new ZXingScannerPage (options);

###Using the ZXingScanner View / Fragment / Control
On each platform, the ZXing scanner has been implemented as a reusable component (view, fragment, or control), and it is possible to use the reusable component directly without using the MobileBarcodeScanner class at all. On each platform, the instance of the view/fragment/control contains the necessary properties and methods required to control your scanner. By default, the default overlay is automatically used, unless you set the CustomOverlay property as well as the UseCustomOverlay property on the instance of the view/fragment/control. You can use methods such as ToggleTorch() or StopScanning() on the view/fragment/control, however you are responsible for calling StartScanning(...) with a callback and an instance of MobileBarcodeScanningOptions when you are ready for the view's scanning to begin. You are also responsible for stopping scanning if you want to cancel at any point.
// ...
```

The view/fragment/control classes for each platform are:
You can also set the `Options` property if you are using the `ZXingScannerView` control directly.

- iOS: ZXingScannerView (UIView) - See ZXingScannerViewController.cs View Controller for an example of how to use this view
- iOS: AVCaptureScannerView (UIView) - This is API equivalent to ZXingScannerView, but uses Apple's AVCaptureSession Metadata engine to scan the barcodes instead of ZXing.Net. See AVCaptureScannerViewController.cs View Controller for an example of how to use this view
- Android: ZXingScannerFragment (Fragment) - See ZXingActivity.cs Activity for an example of how to use this fragment
- Windows Phone: ZXingScannerControl (UserControl) - See ScanPage.xaml Page for an example of how to use this Control

## Displaying / Generating Barcodes

###Using Apple's AVCaptureSession (iOS7 Built in) Barcode Scanning
In iOS7, Apple added some API's to allow for scanning of barcodes in an AVCaptureSession. The latest version of ZXing.Net.Mobile gives you the option of using this instead of the ZXing scanning engine. You can use the `AVCaptureScannerView` or the `AVCaptureScannerViewController` classes directly just the same as you would use their ZXing* equivalents. Or, in your `MobileBarcodeScanner`, there is now an overload to use the AV Capture Engine:
There is also a `ZXingBarcodeImageView` control available that can be used within any Xamarin.Forms page:

```csharp
//Scan(MobileBarcodeScanningOptions options, bool useAVCaptureEngine)
scanner.Scan(options, true);
public class BarcodePage : ContentPage
{
ZXingBarcodeImageView barcode;

public BarcodePage ()
{
barcode = new ZXingBarcodeImageView {
HorizontalOptions = LayoutOptions.FillAndExpand,
VerticalOptions = LayoutOptions.FillAndExpand,
};
barcode.BarcodeFormat = ZXing.BarcodeFormat.QR_CODE;
barcode.BarcodeOptions.Width = 300;
barcode.BarcodeOptions.Height = 300;
barcode.BarcodeOptions.Margin = 10;
barcode.BarcodeValue = "ZXing.Net.Mobile";

Content = barcode;
}
}
```
In the MobileBarcodeScanner, even if you specify to use the AVCaptureSession scanning, it will gracefully degrade to using ZXing if the device doesn't support this (eg: if it's not iOS7 or newer), or if you specify a barcode format in your scanning options which the AVCaptureSession does not support for detection. The AVCaptureSession can only decode the following barcodes:

- Aztec
- Code 128
- Code 39
- Code 93
- EAN13
- EAN8
- PDF417
- QR
- UPC-E

###License
Apache ZXing.Net.Mobile Copyright 2012 The Apache Software Foundation
This product includes software developed at The Apache Software Foundation (http://www.apache.org/).

### ZXing.Net
ZXing.Net is released under the Apache 2.0 license.
ZXing.Net can be found here: http://zxingnet.codeplex.com/
A copy of the Apache 2.0 license can be found here: http://www.apache.org/licenses/LICENSE-2.0

### ZXing
ZXing is released under the Apache 2.0 license.
ZXing can be found here: https://github.com/zxing/zxing
A copy of the Apache 2.0 license can be found here: http://www.apache.org/licenses/LICENSE-2.0

### System.Drawing
The System.Drawing classes included are from the mono source code which is property of Novell.
Copyright notice is intact in source code files.
Loading

0 comments on commit ee457e9

Please sign in to comment.