Charting in Reports for WinForms
This article describes Aggregate Charting, one of the cool new features introduced in ComponentOne Reports for WinForms in the 2009 v3 release.
ComponentOne Reports for WinForms has always supported chart fields using its extensible custom field architecture. The Chart field is implemented as a custom field in the C1.Win.C1Report.CustomFields.2.dll assembly, which is installed with the report designer application and is also included as a sample with full source code (CustomFields). In this article, you'll see how you can customize chart fields in reports using the C1ReportDesigner application. The C1ReportDesigner application is installed with both ComponentOne Reports for WinForms and ComponentOne Reports for WPF.
Charts in Flat Reports
Creating a simple chart is very easy. Here are the steps required:
- Open the C1ReportDesigner application and create or open a report definition file.
- Add a Chart field to the report, and then select it to show its properties in the designer's property window.
- Set the chart's DataX property to the name of the field whose values should be displayed in the X axis (chart categories).
- Set the chart's DataY property to the name of the field whose values should be displayed in the Y axis (chart values).
- Optionally set additional properties such as ChartType and DataColor.
For example, the chart below was created based on the NorthWind Products table. In this case, the following properties were set:
DataX = "ProductName"
DataY = "UnitPrice"
Note that for this chart type (Bar), the value axis (where the DataY field is displayed) is the horizontal one, and the category axis is the vertical one.
In this case, a filter was applied to the data in order to limit the number of values shown. Without the filter, the chart would contain too many values and the vertical axis would not be readable.
Other Useful Chart Properties
In addition to the DataX and DataY properties mentioned above, the Chart object provides a few other properties that are commonly used:
- ChartType: This property allows you to select the type of chart to display. There are six options: Bar (horizontal bars), Column (vertical columns), Scatter (X-Y values), Line, Area, and Pie.
- DataColor: This property selects the color used to draw the bars, columns, areas, scatter symbols, and pie slices. If the chart contains multiple series, then the Chart field automatically generates different shades of the selected color for each series. If you want to select specific colors for each series, use the Palette property instead, and set its value to a semi-colon separated list containing the colors to use (for example "Red;Green;Blue").
- FormatY, FormatX: These properties determine the format used to display the values along each axis. For example, setting FormatY to "c" causes the Chart field to format the values along the Y axis as currency values. This is analogous to the Format property in regular report fields.
- XMin, XMax, YMin, YMax: These properties allow you to specify ranges for each axis. Setting any of them to -1 cause the Chart to calculate the range automatically. For example, if you set the YMax property to 100, then any values higher than 100 will be truncated and won't appear on the chart.
These properties apply to all chart types. There are a few additional properties that only apply to Pie charts:
- ShowPercentages: Each pie slice has a legend that shows the X value for the slice. If the ShowPercentages property is set to true, the legend will also include a percentage value that indicates the size of the slice with respect to the pie. The percentage is formatted using the value specified by the FormatY property. For example, if you set FormatY to "p2", then the legends will include the X value and the percentage with two decimal points (for example "North Region (15.23%)").
- RadialLabels: This property specifies that instead of showing a legend on the right side of the chart, labels with connecting lines should be attached to each slice. This works well for pies with few slices (up to about ten).
The Chart field is actually a wrapper for a C1Chart control, which provides all the charting services and has an extremely rich object model of its own. If you want to customize the Chart field even further, you can use the ChartControl property to access the inner C1Chart object using scripts.
For example, the Chart field does not have a property to control the position of the legend. But the C1Chart control does, and you can access this property through the ChartControl property. For example, the script below causes the chart legend to be positioned below the chart instead of on the right:
' place legend below the chart
chartField.ChartControl.Legend.Compass = "South"
If you assign this script to the report's OnLoad property, the chart will look like the image below:
The other properties used to create this chart are as follows:
ChartType = Pie
FormatY = "p1"
ShowPercentage = truePalette = "Red;Gold;Orange;Beige;DarkGoldenrod;Goldenrod;"
Charts with Multiple Series
To create charts with multiple series, simply set the DataY property to a string that contains the names of each data field you want to chart, separated by semi-colons. For example, to create a chart showing product prices and discounts you would set the DataY property as shown below:
DataY = "UnitPrice;Discount"
If you want to specify the color used to display each series, set the Palette property to a list of colors separated by semi-colons. For example, the value displayed below would cause the chart to show the UnitPrice" series in red and the "Discount" series in blue:
Palette = "Red;Blue"
Series with Calculated Values
The DataY property is not restricted to field names. The strings that specify the series are actually treated as full expressions, and are calculated like any regular field in the report.
For example, to create a chart showing the actual price of each field you could set the DataY property to the value shown below:
DataY = "UnitPrice * (1 - Discount)"
Charts in Grouped Reports
Reports for WinForms allows you to create reports with multiple groups. For example, instead of listing all products in a single flat report, you could group products by category. Each group has a header and a footer section that allow you to display information about the group, including titles and subtotals, for example.
If you add a chart to a group header, the chart will display only the data for the current group. By contrast, adding a chart to the report header or footer would include all the data in the report.
To illustrate this, here is a diagram depicting a report definition as shown in the report designer and showing the effect of adding a Chart field to the report header and to a group header:
Continuing with the example mentioned above, if you added a chart to the group header and set the DataX property to "ProductName" and the DataY property to "UnitPrice", the final report would contain one chart for each category, and each chart would display the unit prices for the products in that category.
The images below show screenshots of the report described above with the group headers, the charts they contain, and a few detail records to illustrate:
Chart showing unit prices for products in the "Beverages" category
Chart showing unit prices for products in the "Condiments" category
DataX = "Product Name"
DataY = "Unit Price"
Because the chart automatically selects the data based on the scope of the section that contains it, creating charts in grouped reports is very easy.
The Chart field included with the 2009 v3 release of Reports for WinForms has a powerful new feature called "aggregated charting". This feature allows you to create charts that automatically aggregate data values (DataY) that have the same category (DataX) using an aggregate function of your choice (sum, average, standard deviation, and so on).
To illustrate this feature, consider an "Invoices" report that groups data by country, customer, and order ID. The general outline for the report is as follows:
Now imagine that you would like to add a chart to each Country header displaying the total value of all orders placed by each customer in the current country.
You would start by adding a Chart field to the "Country" header section and then setting the DataX and DataY properties as follows:
DataX = "CustomerName"
DataY = "ExtendedPrice"
This would not work. The data for each country usually includes several records for each customer, and the chart would create one data point for each record. The chart would not be able to guess that you really want to add the values for each customer into a single data point.
To address this scenario, we added an Aggregate property to the Chart field. This property tells the chart how to aggregate values that have the same category into a single point in the chart. The Aggregate property can be set to perform any of the common aggregation functions on the data: sum, average, count, maximum, minimum, standard deviation, and variance.
Continuing with our example, we can now simply set the chart's Aggregate property to "Sum". This will cause the chart to add all "ExtendedPrice" values for records that belong to the same customer into a single data point. The result is shown below:
Notice how each customer appears only once. The values shown on the chart correspond to the sum of the "ExtendedPrice" values for all fields with the same "Customer".
Because the chart appears in the "Country" header field, it is repeated for each country, showing all the customers in that country.
If you place the chart in the report header section, it will aggregate data over the entire report. For example, suppose you want to start the "Invoices" report with a chart that shows the total amount ordered by each salesperson. To accomplish this, you would add a Chart field to the report header section and would set the following properties:
DataX = "Salesperson"
DataY = "ExtendedPrice"
Aggregate = "Sum"
The image below shows the resulting chart:
Since the chart is placed in the report header section, the values displayed include all countries and all customers. If you moved the chart field from the report header to the "Country" group header, you would obtain a similar chart for each country, showing the total amounts sold by each salesperson in that country.
Aggregate charting is a powerful, yet simple and easy-to-use feature. We hope you enjoy it and use it to create spectacular reports!
ComponentOne Reports for WinForms is part of ComponentOne Studio for WinForms. If you have not already, download the latest trial version at http://www.componentone.com/SuperProducts/StudioWinForms/ so you can start creating your reports.