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)

Base.Name

Base.Restrictions

Base.Flags

Base.Parent

Base.BaseName

Base.ClassName

Base.Report

Base.Page

Base.ChildObjects

Base.AllObjects

Base.ZOrder

Base.IsAncestor

Base.IsDesigning

Base.IsPrinting

Base.IsRunning

Base.OriginalComponent

Base.SetProp(Base, Base)

Base.FloatDiff(Single, Single)

Base.ExtractDefaultMacros(String)

Base.Dispose(Boolean)

Base.SetFlags(Flags, Boolean)

Base.SetReport(Report)

Base.SetName(String)

Base.SetParent(Base)

Base.SetParentCore(Base)

Base.FindObject(String)

Base.CreateUniqueName()

Base.Clear()

Base.BaseAssign(Base)

Base.AssignAll(Base)

Base.HasParent(Base)

Base.HasFlag(Flags)

Base.HasRestriction(Restrictions)

Base.InvokeEvent(String, Object)

Base.GetCustomScript()

Base.ExtractMacros()

Base.IsHaveToConvert(Object)

Base.GetConvertedObjects()

Base.ForEachAllConvectedObjects(Object)

FastReport.Base.IsParentSelected

FastReport.Base.Delete()

FastReport.Base.GetImageIndex()

Namespace: FastReport.AdvMatrix

Assembly: FastReport.dll

Syntax

public class AdvMatrixObject : TableBase, IComponent, 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

TableBase.ColumnCount

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

ReportComponentBase.IsCompilationNeeded

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

TableBase.RowCount

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

TableBase.Assign(Base)

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.

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

Base.DeserializeSubItems(FRReader)

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

TableBase.Draw(FRPaintEventArgs)

FinalizeComponent()

Performs a finalization after the report is finished.

Declaration

public override void FinalizeComponent()

Overrides

ReportComponentBase.FinalizeComponent()

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

ReportComponentBase.GetData()

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

ReportComponentBase.GetDataAsync(CancellationToken)

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

ReportComponentBase.GetExpressions()

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

ReportComponentBase.InitializeComponent()

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

ReportComponentBase.OnAfterData(EventArgs)

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

ReportComponentBase.ResetData()

RestoreState()

Restores the object's state after printing it.

Declaration

public override void RestoreState()

Overrides

TableBase.RestoreState()

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

TableBase.SaveState()

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

TableBase.Serialize(FRWriter)

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

IFRSerializable

IParent