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, 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)

Copies the contents of another, similar object.

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

Source object to copy the contents from.
Overrides
Remarks

Call Assign to copy the properties from another object of the same type. The standard form of a call to Assign is

destination.Assign(source);

which tells the destination object to copy the contents of the source object to itself. In this method, all child objects are ignored. If you want to copy child objects, use the AssignAll method.

See Also

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)

Deserializes nested object properties.

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

Reader object.
Overrides
Remarks

Typically the object serializes all properties to the single xml item:

<TextObject Name="Text2" Left="18.9" Top="37.8" Width="283.5" Height="28.35"/>

Some objects like DataBand have child objects that serialized in subitems:

<DataBand Name="Data1" Top="163" Width="718.2" Height="18.9">
  <TextObject Name="Text3" Left="18.9" Top="37.8" Width="283.5" Height="28.35"/>
</DataBand>

To read such subitems, the DeserializeSubItems method is used. Base implementation reads the child objects. You may override it to read some specific subitems.

FinalizeComponent()

Performs a finalization after the report is finished.

Declaration
public override void FinalizeComponent()
Overrides
Remarks

This method is used by the report engine, do not call it directly.

GetData()

Gets the data from a datasource that the object is connected to.

Declaration
public override void GetData()
Overrides
Remarks

This method is called by the report engine before processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should get the data from a datasource that the object is connected to.

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()

Gets all expressions contained in the object.

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

Array of expressions or null if object contains no expressions.
Overrides
Remarks

Do not call this method directly. You may override it if you are developing a new component for FastReport.

This method is called by FastReport each time before run a report. FastReport do this to collect all expressions and compile them. For example, GetExpressions method of the TextObject class parses the text and returns all expressions found in the text.

InitializeComponent()

Initializes the object before running a report.

Declaration
public override void InitializeComponent()
Overrides
Remarks

This method is used by the report engine, do not call it directly.

OnAfterData(EventArgs)

This method fires the AfterData event and the script code connected to the AfterDataEvent.

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

Event data.
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()

Restores the object's state after printing it.

Declaration
public override void RestoreState()
Overrides
Remarks

This method is called by the report engine after processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should restore the object properties that were saved by the SaveState() method.

SaveState()

Saves the object's state before printing it.

Declaration
public override void SaveState()
Overrides
Remarks

This method is called by the report engine before processing the object.

Do not call it directly. You may override it if you are developing a new FastReport component. In this method you should save any object properties that may be changed during the object printing. The standard implementation saves the object's bounds, visibility, bookmark and hyperlink.

Serialize(FRWriter)

Serializes the object.

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

Writer object.
Overrides
Remarks

Do not call this method directly. You should override it if you are developing a new component for FastReport.

This method is called when the object needs to save the state. It may happen when:

  • saving the report to the file or stream;
  • saving the report to the designer's undo buffer;
  • assigning the object to another object using the Assign(Base) or AssignAll methods;
  • saving the object to the designer's clipboard;
  • saving the object to the preview (when run a report).

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