1.5.3.1 Basic Matrix Object Operation

A matrix sheet can have multiple matrix objects, which share the same dimensions. A matrix object is analogous to a worksheet column and can be added or deleted, etc. The following sections provide some practical examples on the basic operations of matrix object.

Add or Insert Matrix Object

It allows to set the number of matrix objects in the matrix sheet by using MatrixLayer::SetSize, so to add matrix objects.

// Set 5 matrix objects in the active matrix sheet
MatrixLayer ml = Project.ActiveLayer();
ml.SetSize(5);

The method MatrixLayer::Insert will insert a specified number of matrix objects before the current matrix object.

// add matrix object to sheet
MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet	

int nNum = 1; // the number of added matrix objects
int nPos = -1; // -1, add as the end
int nDataType = -1; // Optional, -1 as default for double type.
int index = ml.Insert(nNum, nPos, nDataType); // Returns the index of the first one

Activate Matrix Object

To activate a matrix object in the matrix sheet, the MatrixLayer::SetActive is available.

MatrixLayer ml = Project.ActiveLayer();
ml.SetActive(2);  // Set 3rd (index is 0-based) matrix object active

Access Matrix Object

To access a matrix object, you can use the collection of MatrixObjects from MatrixLayer.

// Attach to one matrix page by name
MatrixPage matPage("MBook3"); 

// Attach to the sheet named MSheet1 from matrix page
// Also support get sheet from matrix page by index
MatrixLayer ml1 = matPage.Layers("MSheet1"); 
        
// Get a matrix object from sheet by index 
MatrixObject mo = ml1.MatrixObjects(0); 
   
// The data type of matrix object must keep consistent with the matrix window
if( FSI_SHORT == mo.GetInternalDataType() )
{	
	matrix<short>& mat = mo.GetDataObject();
}

Delete Matrix Object

To delete a specified number of matrix objects from a matrix sheet, you can use the MatrixLayer::Delete method.

// delete matrix object from sheet
MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet	

// Delete two matrix objects from the beginning
int nPos = 0;
int nNum = 2;
ml.Delete(nPos,	nNum);

Switch Between Image Mode and Data Mode

The MatrixLayer::SetViewImage method has provided the option for switching between image mode and data mode of the specified matrix object (by index).

// set image view
MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet
	
int nImgIndex = 0;
MatrixObject mo = ml.MatrixObjects(nImgIndex);

if( !mo.IsImageView() )
{
	BOOL bAllObjs = FALSE;
	ml.SetViewImage(TRUE, bAllObjs, nImgIndex);  // FALSE for data view
}

Get and Set Labels

For each matrix object, you can set Long Name, Comments, and Units. And it actually is to get and set the Z labels, please refer to the Get and Set Z Labels on Base Matrix Sheet Operation chapter.

Data Type and Format

Get and Set Data TypeMatrix Sheet, Set Internal Data Type

Matrix object's internal data types include double, real, short, long, char, text, mixed, byte, ushort, ulong, and complex, etc. And Origin C provides the GetInternalDataType and SetInternalDataType methods in MatrixObject class to get and set matrix object internal data type respectively.

// get and set data type
MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet	
MatrixObject mo = ml.MatrixObjects(0);

if( mo.GetInternalDataType() != FSI_BYTE ) // Get data type
{
	// OCD_RESTORE to backup the data and 
	// attempt to restore it after changing type
	DWORD dwFlags = OCD_RESTORE;
	mo.SetInternalDataType(FSI_BYTE, dwFlags); // Set data type
}

Get and Set Data FormatMatrix Sheet, Data Format

The MatrixObject::GetFormat and MatrixObject::SetFormat are provided for getting and setting the data format of a matrix object respectively.

// get and set data format
MatrixLayer ml = Project.ActiveLayer(); // Get active matrix sheet	
MatrixObject mo = ml.MatrixObjects(0);

int nFormat = mo.GetFormat(); // Only OKCOLTYPE_NUMERIC( = 0) supported
mo.SetFormat(OKCOLTYPE_NUMERIC);