Class AdvMatrixObject

Represents the matrix object that is used to print cross-table.

Inheritance
System.Object
Base
ComponentBase
ReportComponentBase
BreakableComponent
TableBase
AdvMatrixObject
Implements
Inherited Members
FastReport.Table.TableBase.BreakTo
FastReport.Table.TableBase.CanGrow
FastReport.Table.TableBase.CanShrink
FastReport.Table.TableBase.Height
FastReport.Table.TableBase.Hyperlink
FastReport.Table.TableBase.IsSelected
FastReport.Table.TableBase.Width
FastReport.Table.TableBase.HandleMouseHover(FastReport.Utils.FRMouseEventArgs)
FastReport.ReportComponentBase.Left
FastReport.ReportComponentBase.Top
FastReport.ReportComponentBase.AssignFormat(FastReport.ReportComponentBase)
FastReport.ReportComponentBase.CheckParent(System.Boolean)
FastReport.ReportComponentBase.DrawMarkers(FastReport.Utils.FRPaintEventArgs)
FastReport.ReportComponentBase.DrawMarkers(FastReport.Utils.FRPaintEventArgs, FastReport.MarkerStyle)
FastReport.ReportComponentBase.DrawIntersection(FastReport.Utils.FRPaintEventArgs)
FastReport.ReportComponentBase.GetPreferredSize()
FastReport.ReportComponentBase.MouseMove
FastReport.ReportComponentBase.MouseUp
FastReport.ReportComponentBase.MouseDown
FastReport.ReportComponentBase.MouseEnter
FastReport.ReportComponentBase.MouseLeave
FastReport.ReportComponentBase.AssignPreviewEvents(FastReport.Base)
FastReport.ReportComponentBase.OnMouseMove(System.Windows.Forms.MouseEventArgs)
FastReport.ReportComponentBase.OnMouseUp(System.Windows.Forms.MouseEventArgs)
FastReport.ReportComponentBase.OnMouseDown(System.Windows.Forms.MouseEventArgs)
FastReport.ReportComponentBase.OnMouseEnter(System.EventArgs)
FastReport.ReportComponentBase.OnMouseLeave(System.EventArgs)
FastReport.ReportComponentBase.OnMouseWheel(System.Windows.Forms.MouseEventArgs)
FastReport.ReportComponentBase.GetPreviewContextMenu()
FastReport.ComponentBase.CheckNegativeSize(FastReport.Utils.FRMouseEventArgs)
FastReport.ComponentBase.DrawDragAcceptFrame(FastReport.Utils.FRPaintEventArgs, System.Drawing.Color)
FastReport.ComponentBase.DrawSelection(FastReport.Utils.FRPaintEventArgs)
FastReport.ComponentBase.GetSmartTag()
FastReport.ComponentBase.HandleDoubleClick()
FastReport.ComponentBase.HandleMouseWheel(FastReport.Utils.FRMouseEventArgs)
FastReport.ComponentBase.PointInObject(System.Drawing.PointF)
FastReport.ComponentBase.DrawSelectionPoint(FastReport.Utils.FRPaintEventArgs, System.Drawing.Pen, System.Drawing.Brush, System.Single, System.Single)
FastReport.ComponentBase.GetSelectionPoints()
FastReport.ComponentBase.PointInSelectionPoint(System.Single, System.Single, System.Drawing.PointF)
FastReport.Base.IsParentSelected
FastReport.Base.Delete()
FastReport.Base.GetImageIndex()
Namespace: FastReport.AdvMatrix
Assembly: FastReport.dll
Syntax
public class AdvMatrixObject : 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 HeaderDescriptor class represents columns and rows; data cells use dynamically created descriptors. The Data property holds two root descriptors - Columns.Descriptor and Rows.Descriptor.

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

  • create an instance of the AdvMatrixObject and add it to the report;
  • create descriptors for columns and rows and add it to the root descriptor using the matrix.Data.Columns.Descriptor and matrix.Data.Rows.Descriptor respectively;
  • call the BuildTemplate() method to create the matrix template that will be used to create a result;
  • set the data cells content;
  • 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 AdvMatrixObject
AdvMatrixObject matrix = new AdvMatrixObject();
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 nested column descriptors and a total
HeaderDescriptor column = new HeaderDescriptor("[MatrixDemo.Year]");
matrix.Data.Columns.Descriptor.Add(column);
HeaderDescriptor nestedColumn = new HeaderDescriptor("[MatrixDemo.Month]");
column.Add(nestedColumn);
HeaderDescriptor columnTotal = new HeaderDescriptor();
columnTotal.DisplayText = "Total";
matrix.Data.Columns.Descriptor.Add(columnTotal);

// create one row descriptor and a total
HeaderDescriptor row = new HeaderDescriptor("[MatrixDemo.Name]");
matrix.Data.Rows.Descriptor.Add(row);
HeaderDescriptor rowTotal = new HeaderDescriptor();
rowTotal.DisplayText = "Total";
matrix.Data.Rows.Descriptor.Add(rowTotal);

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

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

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

// create data cells
string cellText = "[Sum([MatrixDemo.Revenue])]";
for (int i = matrix.Data.Rows.Size; i < matrix.ColumnCount; i++)
for (int j = matrix.Data.Columns.Size; j < matrix.RowCount; j++)
    matrix[i, j].Text = cellText;

Constructors

AdvMatrixObject()

Initializes a new instance of the AdvMatrixObject class.

Declaration
public AdvMatrixObject()

Properties

CanBreak

This property is not relevant to this class.

Declaration
[Browsable(false)]
public bool CanBreak { get; set; }
Property Value
Type Description
System.Boolean

ColumnCount

This property is not relevant to this class.

Declaration
[Browsable(false)]
public override int ColumnCount { get; set; }
Property Value
Type Description
System.Int32
Overrides

ColumnIndex

Gets or sets the index of currently printing column.

Declaration
[Browsable(false)]
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
[Browsable(false)]
public dynamic[] 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 array of dynamic, so you don't need to cast it to actual type before making any comparisons. Example of highlight condition: Matrix1.ColumnValues[0] == 2000.

Data

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

Declaration
[Browsable(false)]
public MatrixData Data { get; }
Property Value
Type Description
MatrixData
Remarks

See the MatrixData class for more details.

DataRowPriority

Gets or sets data row priority for matrix cells.

Declaration
public HeaderPriority DataRowPriority { get; set; }
Property Value
Type Description
HeaderPriority

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.

EvenStyle

This property is not relevant to this class.

Declaration
[Browsable(false)]
public string EvenStyle { get; set; }
Property Value
Type Description
System.String

EvenStylePriority

Gets or sets even style priority for matrix cells.

Declaration
public HeaderPriority EvenStylePriority { get; set; }
Property Value
Type Description
HeaderPriority

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.

FixedColumns

This property is not relevant to this class.

Declaration
[Browsable(false)]
public int FixedColumns { get; set; }
Property Value
Type Description
System.Int32

FixedRows

This property is not relevant to this class.

Declaration
[Browsable(false)]
public int FixedRows { get; set; }
Property Value
Type Description
System.Int32

GrowToBottom

This property is not relevant to this class.

Declaration
[Browsable(false)]
public bool GrowToBottom { get; set; }
Property Value
Type Description
System.Boolean

IsCompilationNeeded

Declaration
protected override bool IsCompilationNeeded { get; }
Property Value
Type Description
System.Boolean
Overrides

ItemCount

Gets or sets count of items in the currently printing header.

Declaration
[Browsable(false)]
public int ItemCount { get; set; }
Property Value
Type Description
System.Int32

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.

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

ResetDataOnRun

Gets or sets a value indicating that the matrix should reset its data on each report run.

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

Default value is false. In this case the matrix will use already prepared data when you refresh a report. If you set it to true the matrix data will be reset on each report refresh. This also resets all user interaction such as interactive sort and collapse state.

RowCount

This property is not relevant to this class.

Declaration
[Browsable(false)]
public override int RowCount { get; set; }
Property Value
Type Description
System.Int32
Overrides

RowIndex

Gets or sets the index of currently printing row.

Declaration
[Browsable(false)]
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.

RowNo

Gets or sets the data row index of currently printing header.

Declaration
[Browsable(false)]
public int RowNo { get; set; }
Property Value
Type Description
System.Int32
Remarks

Use this value if you want to display the header value with its data row number, e.g. "1. Andrew Fuller". To do this, set the header's DisplayExpression to something like this: Matrix1.RowNo + ". " + Value

RowValues

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

Declaration
[Browsable(false)]
public dynamic[] 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 dynamic, so you don't need to cast it to actual type before making any comparisons. Example of highlight condition: Matrix1.RowValues[0] == "Andrew Fuller".

Style

Gets or sets a matrix style.

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

Methods

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.

Draw(FRPaintEventArgs)

Declaration
public override void Draw(FRPaintEventArgs e)
Parameters
Type Name Description
FRPaintEventArgs e
Overrides

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.

GetContextMenu()

Gets the object's context menu.

Declaration
public override ContextMenuBase GetContextMenu()
Returns
Type Description
ContextMenuBase

Null reference if object does not have a menu.
Overrides
FastReport.Table.TableBase.GetContextMenu()
Remarks

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

You may use base menu classes such as ComponentBaseMenu, ReportComponentBaseMenu to create own context menus.

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.

HandleDragDrop(FRMouseEventArgs)

Handles the DragDrop event in the designer.

Declaration
public override void HandleDragDrop(FRMouseEventArgs e)
Parameters
Type Name Description
FRMouseEventArgs e

Current mouse state.
Overrides
FastReport.ComponentBase.HandleDragDrop(FastReport.Utils.FRMouseEventArgs)
Remarks

This method is called when the user drops an item from the Data Tree window into this object. This method should copy the information from the e.DraggedObject object and set the e.Handled flag to true to complete the drag operation.

HandleDragOver(FRMouseEventArgs)

Handles the DragOver event in the designer.

Declaration
public override void HandleDragOver(FRMouseEventArgs e)
Parameters
Type Name Description
FRMouseEventArgs e

Current mouse state.
Overrides
FastReport.ComponentBase.HandleDragOver(FastReport.Utils.FRMouseEventArgs)
Remarks

This method is called when the user drags an item from the Data Tree window. This method should check that the mouse (e.X, e.Y) is inside the object, then set the e.Handled flag to true if an item can be dragged into this object.

HandleKeyDown(Control, KeyEventArgs)

Handles KeyDown event in the designer.

Declaration
public override void HandleKeyDown(Control sender, KeyEventArgs e)
Parameters
Type Name Description
System.Windows.Forms.Control sender

The designer's workspace.
System.Windows.Forms.KeyEventArgs e

Keyboard event parameters.
Overrides
FastReport.Table.TableBase.HandleKeyDown(System.Windows.Forms.Control, System.Windows.Forms.KeyEventArgs)
Remarks

This method is called when the user presses any key in the designer. Typical implementation does nothing.

HandleMouseDown(FRMouseEventArgs)

Handles MouseDown event that occurs when the user clicks the mouse in the designer.

Declaration
public override void HandleMouseDown(FRMouseEventArgs e)
Parameters
Type Name Description
FRMouseEventArgs e

Current mouse state.
Overrides
FastReport.Table.TableBase.HandleMouseDown(FastReport.Utils.FRMouseEventArgs)
Remarks

This method is called when the user press the mouse button in the designer. The standard implementation does the following:

  • checks if the mouse pointer is inside the object;
  • add an object to the selected objects list of the designer;
  • sets the e.Handled flag to true.

HandleMouseMove(FRMouseEventArgs)

Handles MouseMove event that occurs when the user moves the mouse in the designer.

Declaration
public override void HandleMouseMove(FRMouseEventArgs e)
Parameters
Type Name Description
FRMouseEventArgs e

Current mouse state.
Overrides
FastReport.Table.TableBase.HandleMouseMove(FastReport.Utils.FRMouseEventArgs)
Remarks

This method is called when the user moves the mouse in the designer. The standard implementation does the following:

  • if mouse button is not pressed, check that mouse pointer is inside one of the selection points returned by the FastReport.ComponentBase.GetSelectionPoints() method and set the e.SizingPoint member to the corresponding sizing point;
  • if mouse button is pressed, and e.SizingPoint member is not SizingPoint.None, resize the object.

HandleMouseUp(FRMouseEventArgs)

Handles MouseUp event that occurs when the user releases the mouse button in the designer.

Declaration
public override void HandleMouseUp(FRMouseEventArgs e)
Parameters
Type Name Description
FRMouseEventArgs e

Current mouse state.
Overrides
FastReport.Table.TableBase.HandleMouseUp(FastReport.Utils.FRMouseEventArgs)
Remarks

This method is called when the user releases the mouse button in the designer. The standard implementation does the following:

  • if e.Mode is WorkspaceMode2.SelectionRect, checks if object is inside the selection rectangle and sets e.Handled flag if so;
  • checks that object is inside its parent (calls the FastReport.ComponentBase.CheckParent(System.Boolean) method).

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

OnAfterInsert(InsertFrom)

Called after the new object was inserted in the designer.

Declaration
public override void OnAfterInsert(InsertFrom source)
Parameters
Type Name Description
InsertFrom source

The insertion source.
Overrides
FastReport.Table.TableBase.OnAfterInsert(FastReport.InsertFrom)
Remarks

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

This method is called when new object is inserted, pasted from clipboard or dragged from "Dictionary" window. You may override this method if you need to perform some actions when object is inserted. Typical implementation invokes the object's editor if "Edit after insert" flag is set in the designer options.

OnBeforeInsert(Int32)

Called before inserting a new object in the designer.

Declaration
public override void OnBeforeInsert(int flags)
Parameters
Type Name Description
System.Int32 flags

Object's flags.
Overrides
FastReport.Table.TableBase.OnBeforeInsert(System.Int32)
Remarks

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

Some objects are registered in the designer several times with the same object type, but different flags. For example, the ShapeObject represents different shapes: rectangle, roundrect, ellipse and so on. All these shapes are registered in the designer using flags (the last parameter in this code): 

RegisteredObjects.Add(typeof(ShapeObject), "ReportPage,Shapes", 108, "Objects,Shapes,Rectangle", 0);
RegisteredObjects.Add(typeof(ShapeObject), "ReportPage,Shapes", 109, "Objects,Shapes,RoundRectangle", 1);
RegisteredObjects.Add(typeof(ShapeObject), "ReportPage,Shapes", 110, "Objects,Shapes,Ellipse", 2);

When we put the "Ellipse" object on a band, the designer creates the ShapeObject instance and calls its OnBeforeInsert method with flags value set to 2. In turn, the OnBeforeInsert method converts the int value of the flags to the shape kind:

public override void OnBeforeInsert(int flags)
{
FShape = (ShapeKind)flags;
}

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.

ResetData()

Resets the data from the previous report run.

Declaration
public override void ResetData()
Overrides

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.

SelectionChanged()

Called when the user selects another object in the designer.

Declaration
public override void SelectionChanged()
Overrides
FastReport.Base.SelectionChanged()
Remarks

This method is typically used by the in-place object's editor to check if selection was changed and close the editor.

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

SortColumnsByRow(Int32, SortOrder)

Sort columns based on values of row with specified index. For internal use only.

Declaration
public void SortColumnsByRow(int rowIndex, SortOrder sort)
Parameters
Type Name Description
System.Int32 rowIndex

Index of row.
SortOrder sort

The sort order.

SortRowsByColumn(Int32, SortOrder)

Sort rows based on values of column with specified index. For internal use only.

Declaration
public void SortRowsByColumn(int columnIndex, SortOrder sort)
Parameters
Type Name Description
System.Int32 columnIndex

Index of column.
SortOrder sort

The sort order.

ToggleColumnVisible(Int32, Boolean, Boolean)

Toggles visible state of the column with specified index. For internal use only.

Declaration
public void ToggleColumnVisible(int index, bool collapseAll = false, bool expandAll = false)
Parameters
Type Name Description
System.Int32 index

Index of column.
System.Boolean collapseAll

If true collapse all items.
System.Boolean expandAll

If true expand all items.

ToggleRowVisible(Int32, Boolean, Boolean)

Toggles visible state of the row with specified index. For internal use only.

Declaration
public void ToggleRowVisible(int index, bool collapseAll = false, bool expandAll = false)
Parameters
Type Name Description
System.Int32 index

Index of row.
System.Boolean collapseAll

If true collapse all items.
System.Boolean expandAll

If true expand all items.

Events

ManualBuild

Allows to fill the matrix in code.

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

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