Class MatrixObject

Represents the matrix object that is used to print pivot table (also known as cross-tab).

Inheritance
System.Object
Base
ComponentBase
ReportComponentBase
BreakableComponent
TableBase
MatrixObject
Implements
Inherited Members
Namespace: FastReport.Matrix
Assembly: FastReport.Base.dll
Syntax
public class MatrixObject : TableBase, IDisposable, IFRSerializable, IParent
Remarks

The matrix consists of the following elements: columns, rows and data cells. Each element is represented by the descriptor. The MatrixHeaderDescriptor class is used for columns and rows; the MatrixCellDescriptor is used for data cells. The Data property holds three collections of descriptors - Columns, Rows and Cells.

To create the matrix in a code, you should perform the following actions:

  • create an instance of the MatrixObject and add it to the report;
  • create descriptors for columns, rows and cells and add it to the collections inside the Data property;
  • call the BuildTemplate() method to create the matrix template that will be used to create a result;
  • modify the matrix template (change captions, set the visual appearance).

To connect the matrix to a datasource, use the DataSource property. If this property is not set, the result matrix will be empty. In this case you may use the ManualBuild event handler to fill the matrix.

Examples

This example demonstrates how to create a matrix in a code.

// create an instance of MatrixObject
MatrixObject matrix = new MatrixObject();
matrix.Name = "Matrix1";
// add it to the report title band of the first report page
matrix.Parent = (report.Pages[0] as ReportPage).ReportTitle;

// create two column descriptors
MatrixHeaderDescriptor column = new MatrixHeaderDescriptor("[MatrixDemo.Year]");
matrix.Data.Columns.Add(column);
column = new MatrixHeaderDescriptor("[MatrixDemo.Month]");
matrix.Data.Columns.Add(column);

// create one row descriptor
MatrixHeaderDescriptor row = new MatrixHeaderDescriptor("[MatrixDemo.Name]");
matrix.Data.Rows.Add(row);

// create one data cell
MatrixCellDescriptor cell = new MatrixCellDescriptor("[MatrixDemo.Revenue]", MatrixAggregateFunction.Sum);
matrix.Data.Cells.Add(cell);

// connect matrix to a datasource
matrix.DataSource = Report.GetDataSource("MatrixDemo");

// create the matrix template
matrix.BuildTemplate();

// change the style
matrix.Style = "Green";

// change the column and row total's text to "Grand Total"
matrix.Data.Columns[0].TemplateTotalCell.Text = "Grand Total";
matrix.Data.Rows[0].TemplateTotalCell.Text = "Grand Total";

Constructors

MatrixObject()

Initializes a new instance of the MatrixObject class.

Declaration
public MatrixObject()

Properties

AfterTotalsEvent

Gets or sets a script method name that will be used to handle the AfterTotals event.

Declaration
public string AfterTotalsEvent { get; set; }
Property Value
Type Description
System.String
Remarks

See the AfterTotals event for more details.

AutoSize

Gets or sets a value that determines whether the matrix must calculate column/row sizes automatically.

Declaration
public bool AutoSize { get; set; }
Property Value
Type Description
System.Boolean

CellsSideBySide

Gets or sets a value that determines how to print multiple data cells.

Declaration
public bool CellsSideBySide { get; set; }
Property Value
Type Description
System.Boolean
Remarks

This property can be used if matrix has two or more data cells. Default property value is false - that means the data cells will be stacked.

ColumnIndex

Gets or sets the index of currently printing column.

Declaration
public int ColumnIndex { get; set; }
Property Value
Type Description
System.Int32
Remarks

This property may be used to print even columns with alternate color. To do this:

  • select the cell that you need to highlight;
  • click the "Highlight" button on the "Text" toolbar;
  • add a new highlight condition that uses the Matrix.ColumnIndex, for example: Matrix1.ColumnIndex % 2 == 1.

ColumnValues

Gets or sets array of values that describes the currently printing column.

Declaration
public object[] ColumnValues { get; set; }
Property Value
Type Description
System.Object[]
Remarks

Use this property when report is running. It can be used to highlight matrix elements depending on values of the currently printing column. To do this:

  • select the cell that you need to highlight;
  • click the "Highlight" button on the "Text" toolbar;
  • add a new highlight condition. Use the Matrix.ColumnValues to refer to the value you need to analyze. Note: these values are arrays of System.Object, so you need to cast it to actual type before making any comparisons. Example of highlight condition: (int)Matrix1.ColumnValues[0] == 2000.

Data

Gets the object that holds the collection of descriptors used to build a matrix.

Declaration
public MatrixData Data { get; }
Property Value
Type Description
MatrixData
Remarks

See the MatrixData class for more details.

DataSource

Gets or sets a data source.

Declaration
public DataSourceBase DataSource { get; set; }
Property Value
Type Description
DataSourceBase
Remarks

When you create the matrix in the designer by drag-drop data columns into it, this property will be set automatically. However you need to set it if you create the matrix in code.

Filter

Gets the row filter expression.

Declaration
public string Filter { get; set; }
Property Value
Type Description
System.String
Remarks

This property can contain any valid boolean expression. If the expression returns false, the corresponding data row will be skipped.

KeepCellsSideBySide

Gets or sets a value indicating that the side-by-side cells must be kept together on the same page.

Declaration
public bool KeepCellsSideBySide { get; set; }
Property Value
Type Description
System.Boolean

ManualBuildEvent

Gets or sets a script method name that will be used to handle the ManualBuild event.

Declaration
public string ManualBuildEvent { get; set; }
Property Value
Type Description
System.String
Remarks

See the ManualBuild event for more details.

MatrixEvenStylePriority

Gets or sets even style priority for matrix cells.

Declaration
public MatrixEvenStylePriority MatrixEvenStylePriority { get; set; }
Property Value
Type Description
MatrixEvenStylePriority

ModifyResultEvent

Gets or sets a script method name that will be used to handle the ModifyResult event.

Declaration
public string ModifyResultEvent { get; set; }
Property Value
Type Description
System.String
Remarks

See the ModifyResult event for more details.

PrintIfEmpty

Gets or sets a value indicating that empty matrix should be printed.

Declaration
public bool PrintIfEmpty { get; set; }
Property Value
Type Description
System.Boolean

RowIndex

Gets or sets the index of currently printing row.

Declaration
public int RowIndex { get; set; }
Property Value
Type Description
System.Int32
Remarks

This property may be used to print even rows with alternate color. To do this:

  • select the cell that you need to highlight;
  • click the "Highlight" button on the "Text" toolbar;
  • add a new highlight condition that uses the Matrix.RowIndex, for example: Matrix1.RowIndex % 2 == 1.

RowValues

Gets or sets array of values that describes the currently printing row.

Declaration
public object[] RowValues { get; set; }
Property Value
Type Description
System.Object[]
Remarks

Use this property when report is running. It can be used to highlight matrix elements depending on values of the currently printing row. To do this:

  • select the cell that you need to highlight;
  • click the "Highlight" button on the "Text" toolbar;
  • add a new highlight condition. Use the Matrix.RowValues to refer to the value you need to analyze. Note: these values are arrays of System.Object, so you need to cast it to actual type before making any comparisons. Example of highlight condition: (string)Matrix1.RowValues[0] == "Andrew Fuller".

ShowTitle

Gets or sets a value indicating whether to show a title row.

Declaration
public bool ShowTitle { get; set; }
Property Value
Type Description
System.Boolean

SplitRows

Gets or sets need split rows.

Declaration
public bool SplitRows { get; set; }
Property Value
Type Description
System.Boolean

Style

Gets or sets a matrix style.

Declaration
public string Style { get; set; }
Property Value
Type Description
System.String

Methods

AddValue(Object[], Object[], Object[])

Adds a value in the matrix.

Declaration
public void AddValue(object[] columnValues, object[] rowValues, object[] cellValues)
Parameters
Type Name Description
System.Object[] columnValues

Array of column values.
System.Object[] rowValues

Array of row values.
System.Object[] cellValues

Array of data values.
Remarks

This is a shortcut method to call the matrix Data.AddValue. See the AddValue(Object[], Object[], Object[]) method for more details.

Assign(Base)

Declaration
public override void Assign(Base source)
Parameters
Type Name Description
Base source
Overrides

BuildTemplate()

Creates or updates the matrix template.

Declaration
public void BuildTemplate()
Remarks

Call this method after you modify the matrix descriptors using the Data object's properties.

DeserializeSubItems(FRReader)

Declaration
protected override void DeserializeSubItems(FRReader reader)
Parameters
Type Name Description
FRReader reader
Overrides

FinalizeComponent()

Declaration
public override void FinalizeComponent()
Overrides

GetData()

Declaration
public override void GetData()
Overrides

GetDataAsync(CancellationToken)

Declaration
public override async Task GetDataAsync(CancellationToken cancellationToken)
Parameters
Type Name Description
System.Threading.CancellationToken cancellationToken
Returns
Type Description
System.Threading.Tasks.Task
Overrides

GetExpressions()

Declaration
public override string[] GetExpressions()
Returns
Type Description
System.String[]
Overrides

InitializeComponent()

Declaration
public override void InitializeComponent()
Overrides

OnAfterData(EventArgs)

Declaration
public override void OnAfterData(EventArgs e)
Parameters
Type Name Description
System.EventArgs e
Overrides

OnAfterTotals(EventArgs)

This method fires the AfterTotals event and the script code connected to the AfterTotalsEvent.

Declaration
public void OnAfterTotals(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

Event data.

OnManualBuild(EventArgs)

This method fires the ManualBuild event and the script code connected to the ManualBuildEvent.

Declaration
public void OnManualBuild(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

Event data.

OnModifyResult(EventArgs)

This method fires the ModifyResult event and the script code connected to the ModifyResultEvent.

Declaration
public void OnModifyResult(EventArgs e)
Parameters
Type Name Description
System.EventArgs e

Event data.

RestoreState()

Declaration
public override void RestoreState()
Overrides

SaveState()

Declaration
public override void SaveState()
Overrides

Serialize(FRWriter)

Declaration
public override void Serialize(FRWriter writer)
Parameters
Type Name Description
FRWriter writer
Overrides

Value(Int32)

Gets the value of the data cell with the specified index.

Declaration
public Variant Value(int index)
Parameters
Type Name Description
System.Int32 index

Zero-based index of the data cell.
Returns
Type Description
Variant

The cell's value.
Remarks

Use this method in the cell's expression if the cell has custom totals (the total function is set to "Custom"). The example:

Matrix1.Value(0) / Matrix1.Value(1)

will return the result of dividing the first data cell's value by the second one.

Events

AfterTotals

Allows to modify the prepared matrix elements such as cells, rows, columns.

Declaration
public event EventHandler AfterTotals
Event Type
Type Description
System.EventHandler

ManualBuild

Allows to fill the matrix in code.

Declaration
public event EventHandler ManualBuild
Event Type
Type Description
System.EventHandler
Remarks

In most cases the matrix is connected to a datasource via the DataSource property. When you run a report, the matrix is filled with datasource values automatically.

Using this event, you can put additional values to the matrix or even completely fill it with own values (if DataSource is set to null. To do this, call the Data.AddValue method. See the AddValue(Object[], Object[], Object[]) method for more details.

Examples

This example shows how to fill a matrix with own values.

// suppose we have a matrix with one column, row and data cell.
// provide 3 one-dimensional arrays with one element in each to the AddValue method
Matrix1.Data.AddValue(
  new object[] { 1996 },
  new object[] { "Andrew Fuller" }, 
  new object[] { 123.45f });
Matrix1.Data.AddValue(
  new object[] { 1997 },
  new object[] { "Andrew Fuller" }, 
  new object[] { 21.35f });
Matrix1.Data.AddValue(
  new object[] { 1997 },
  new object[] { "Nancy Davolio" }, 
  new object[] { 421.5f });

// this code will produce the following matrix:
//               |  1996  |  1997  |
// --------------+--------+--------+
// Andrew Fuller |  123.45|   21.35|
// --------------+--------+--------+
// Nancy Davolio |        |  421.50|
// --------------+--------+--------+

ModifyResult

Allows to modify the prepared matrix elements such as cells, rows, columns.

Declaration
public event EventHandler ModifyResult
Event Type
Type Description
System.EventHandler

Implements