With ComponentOne Reports™ you can create your own custom fields and add them to the Report Designer application. This article walks through creating a custom report field using the new C1QRCode control to display 2D barcodes. C1QRCode supports the Quick Response code, one of the most popular 2D barcode formats out there. They are useful because they can be scanned and read by various devices and phones.

To create a custom report field, you have to do two things:

  1. Create a custom field class that derives from C1.C1Report.Field.
  2. Register your custom field assembly in the Report Designer’s settings file.

C1Report includes three pre-built custom fields: Chart, Gradient and SuperLabel (for rendering HTML text), and the source for these custom fields is included as a sample (called CustomFields). The rest of this article walks through creating a new custom field using C1QRCode. Follow these steps to learn how to add any custom field you want, or just download the sample and use the finished product.

Download Sample – C#

Step 1 – Creating a Custom Field Class

The first step is to create a custom field class that derives from C1.C1Report.Field. Create a new .NET 4.0 Class Library project named CustomQRCodeField (or whatever), and replace the default Class with the following code:

using System;
using System.Drawing;
using System.ComponentModel;

namespace CustomQRCodeField
{
    [Description("QRCode Field")]
    public class QRCode : C1.C1Report.Field
    {
        /// <summary>
        /// Initializes a new instance of the QRCode class.
        /// </summary>
        public QRCode()
        {
            //
        }
    }
}

Add Necessary References

Before continuing, you will need to add references to several assemblies: C1.C1Report.4.dll, C1.Win.C1BarCode.4, System.Drawing and System.Windows.Forms.

Initialize C1QRCode Control

Our custom field will render 2D barcodes using C1QRCode. Add a private instance of a C1QRCode and initialize it in the constructor.

private C1.Win.C1BarCode.C1QRCode _qrcode = null;
public QRCode()
{
    _qrcode = new C1.Win.C1BarCode.C1QRCode();
}

Override GetRenderContent

The key method which does the work of rendering our custom field is the C1.C1Report.Field.GetRenderContent method.  In this method we take the value of the field and render a barcode image as the output. There’s no return value on GetRenderContent because we will set the referenced Image parameter to our barcode image. Add the following code to the QRCode class.

/// <summary>
/// Renders 2D barcodes using the <b>C1QRCode</b> component.
/// </summary>
/// <param name="value">Field text.</param>
/// <param name="img">Field image.</param>
/// <param name="designTime">Whether we in design time or runtime.</param>
override protected void GetRenderContent(ref string value, ref Image img, bool designTime)
{
    if (this.Section == C1.C1Report.SectionTypeEnum.Detail)
    {
        // if field is in detail section of report, evaluate the data value
        _qrcode.Text = value;
    }
    else
    {
        // evaluate the text set in the designer
        _qrcode.Text = this.Text;
    }

    // set misc properties
    _qrcode.Encoding = this.Encoding;
    _qrcode.SymbolSize = this.SymbolSize;
    _qrcode.BackColor = this.BackColor;
    _qrcode.ForeColor = this.ForeColor;

    // set ref image
    img = _qrcode.Image;
}

This method is quite simple. We set the field’s value from the report to the Text property on our C1QRCode. Then at the end, we set the barcode Image to the referenced img parameter. The key thing to note here is the IF statement. When we use this custom field within the Detail section of our report, we want the barcode to render the field’s value. Otherwise, let’s say we want 1 barcode in the header of the report, the barcode should render the text we set in the Report Designer from the Text property. We’re also setting a few miscellaneous properties for our C1QRCode. These are properties of a C1QRCode which the user can customize from the Report Designer.

Defining Custom Properties

The custom QRCode field will be integrated into the Report Designer, which means it will have all the basic properties that all C1Report.Field objects have. But in many cases, a custom field will require special properties. For instance, with C1QRCode we may want to expose the Encoding property to users designing the report. The SymbolSize property is another useful one because it determines the size of the barcode symbols. To add custom properties, simply define them as public in the field class.

/// <summary>
/// Gets or sets the encoding type. Available types are Automatic, AlphaNumeric, Numeric and Byte.
/// </summary>
private C1.Win.C1BarCode.Encoding _encoding;
[Category("QRCode"), DefaultValue(C1.Win.C1BarCode.Encoding.Automatic)]
public C1.Win.C1BarCode.Encoding Encoding
{
    get { return _encoding; }
    set
    {
        _encoding = value;
        OnPropertyChanged();
    }
}

/// <summary>
/// Gets or sets the size, in pixels, of the symbols used to build the QR image. Must be between 2-10.
/// </summary>
private int _symbolSize;
[Category("QRCode"), DefaultValue(3)]
public int SymbolSize
{
    get { return _symbolSize; }
    set
    {
        if(value <= 10 && value >= 2)
            _symbolSize = value;
        OnPropertyChanged();
    }
}

Note that with SymbolSize we want to restrict values to be between 2 and 10 inclusively. Then, in the GetRenderContent method above we are setting these properties. We should also initialize them in the constructor. Here is the complete constructor for the QRCode class:

public QRCode()
{
    _qrcode = new C1.Win.C1BarCode.C1QRCode();

    //
    Encoding = C1.Win.C1BarCode.Encoding.Automatic;
    SymbolSize = 3;
    PictureAlign = C1.C1Report.PictureAlignEnum.CenterMiddle;
}

PictureAlign is a general property of all report fields. For C1QRCode, image alignment is best centered in the middle so we’ll make that the default value.

Adding a Toolbar/Ribbon Icon

We can add a 16 x 16 bitmap to represent our custom field in the Report Designer. To do this, simply add a bitmap file with the same name as the class to the project. For example, our QRCode project should have a QRCode.bmp file added as en embedded resource in the root directory.

Add Licensing

C1QRCode and C1Report require a Studio for WinForms key. Since there is no design-time in our class library the necessary license code won’t be added for you. Add a “Properties.4” directory to your solution and add a licenses.licx file. To this file, add these 2 necessary lines to license C1QRCode and C1Report:

C1.C1Report.C1Report, C1.C1Report.4
C1.Win.C1BarCode.C1QRCode, C1.Win.C1BarCode.4

Build and Register

The custom field is now complete. Build the project and then follow step 2 to register the custom field into C1ReportDesigner.

Step 2 – Registering your custom field assembly

What’s great about the C1ReportDesigner application is that you can add your own custom fields without having to modify the source of the application! (Of course, there are many other great things about it as well). The Designer supports adding custom fields by simply registering assemblies in the Settings file. This is how the Chart and Gradient fields are implemented.

<customfields>
  <item value="C1.Win.C1Report.CustomFields;C1.Win.C1Report.CustomFields.Chart" />
  <item value="C1.Win.C1Report.CustomFields;C1.Win.C1Report.CustomFields.Gradient" />
</customfields>

For example, to add the C1QRCode field to the Designer palette, follow these steps.

1. Copy the CustomQRCodeField.dll assembly to the working directory of the Report Designer application. For most users, it will be located here:

C:\Program Files (x86)\ComponentOne\Studio for WinForms\C1Report\Designer.4

Note: We ship both a .NET 2.0 and 4.0 version of the Designer Application, depending on which framework you’re working in. We also ship the designer under multiple platforms so you may look under Studio for WPF or ASP.NET.

2. Open the C1ReportDesigner.exe.settings file in Notepad and add an entry for the custom QRCode field like below. Each item entry defines a custom field by specifying the name of the assembly and the name of the class that defines the field. The first 3 fields are the pre-built custom fields, which you can remove if you don’t need them.

<settings>
  <customfields>
    <item value="C1.C1Report.CustomFields.4;C1.C1Report.CustomFields.Chart" />
    <item value="C1.C1Report.CustomFields.4;C1.C1Report.CustomFields.Gradient" />
    <item value="C1.C1Report.CustomFields.4;C1.C1Report.CustomFields.SuperLabel" />
    <item value="CustomQRCodeField;CustomQRCodeField.QRCode" />
  </customfields>
</settings>

3. Since our custom field depends on the C1.Win.C1BarCode.dll assembly, you will need to copy this to the Report Designer’s working directory too.

The custom field should now be registered and fully operational.

Note: If you don’t see the QRCode field in the Report Designer, then it may be because the application is using a system-wide settings file stored in your local app data. This is common for machines with UAC (User Account Control) turned on. So if you can’t seem to modify the settings file, look for a copy of the settings file and modify it here:

C:\Users\<UserName>\AppData\Roaming\C1Report

Using QRCode Field in the C1ReportDesigner

Launch the C1ReportDesigner application and, if done correctly, you should see your custom fields appended to the Fields group.

Create or open a report such as a simple Products report from the Northwind database. Select the QRCode field and then drag a box on the designer surface.

Set the QRCode field’s Text property to the desired value. If you are using this field within the Detail section of the report, you may want to select a field from your recordset as the Text, such as ProductName or UnitPrice. You should also set the Calculated property to True if the value should be calculated at runtime. And you will notice the custom properties for Encoding and SymbolSize appear in a special “QRCode” group in the property grid for report creators to customize.

Click the Preview button to see what the final report will look like.

Adding QRCode to the C1.Win.C1Report.CustomFields assembly

The steps above show how you to create a custom field completely from scratch. You can, however, add your custom fields to the C1.Win.C1Report.CustomFields assembly for more organized output. The source for this is found along with other C1Report samples. This sample also performs dynamic loading of assemblies (see the DynLoader.cs file) so static references to outside assemblies like C1Chart or C1BarCode are not necessary. This eliminates some version issues when you upgrade to a later version.

Tags: , , ,