1.5.2.1 Basic Matrix Sheet Operation

Examples in this section are similar to those found in the Basic Worksheet Operation section, because matrix sheet and worksheet are at the same level in the Origin object structure.

Add New Matrix Sheet

Add a matrixsheet in a matrixbook using the AddLayer method.

// Access the matrixbook named "MBook1"
MatrixPage mp("MBook1");

// Add a new sheet to the matrixbook
int index = mp.AddLayer("New Matrix Sheet"); 

// Access the new matrixsheet
MatrixLayer mlayerNew = mp.Layers(index);

Activate a Matrixsheet

To make a matrixsheet in matrixbook to be activated, the function set_active_layer can be used.

// Access a matrixsheet by full name
MatrixLayer mLayer("[MBook1]MSheet1");

// Set this matrixsheet to be active
set_active_layer(mLayer);

Delete Matrixsheet

Use the Destroy method to delete a matrixsheet.

MatrixLayer ly = Project.ActiveLayer();
if( ly ) // If the active layer is a matrixsheet
    ly.Destroy(); // Delete the matrixsheet

Access Matrixsheets in Matrixbook

Similar to accessing worksheets in workbook, matrixsheets in matrixbook can also be accessed by the following ways.

  1. By full layer name.
  2. // Full matrixsheet name
    string strFullName = "[MBook1]MSheet1!";
    
    // Construct a matrixsheet instance and attach it to the named sheet
    MatrixLayer matLy1(strFullName);
    
    // Attach an existing matrixsheet instance to the named sheet
    matLy2.Attach(strFullName);
  3. A matrixbook constains a collection of matrix layers. Loop through all matrix layers in a specified matrixbook using the foreach statement.
  4. MatrixPage matPage("MBook1");
    foreach(Layer ly in matPage.Layers)
        out_str(ly.GetName());
  5. Access a specified matrixsheet by its name or index.
  6. // Assume there are at least two matrixsheets on the page MBook1,
    // and they are named MSheet1 and MSheet2 separately.
    MatrixPage matPage("MBook1");
    MatrixLayer lyFirst = matPage.Layers(0); //by index
    MatrixLayer lySecond = matPage.Layers("MSheet2"); //by name

Modify Matrixsheet Properties

Get and Set Dimensions

In Origin, all matrix objects in matrixsheet share the same dimension (the same number of columns and rows).

  1. To get number of rows and columns in a matrixsheet, you can get the first matrix object of a matrixsheet, and then use the methods (GetNumCols and GetNumRows) in MatrixObject class.
  2. // get num rows and cols
    MatrixLayer ml = Project.ActiveLayer(); // Get active matrixsheet	
    MatrixObject mo = ml.MatrixObjects(0); // Get the first matrix object
    
    int nNumRows = mo.GetNumRows();  // Get the row number
    int nNumCols = mo.GetNumCols();  // Get the column number
  3. To set dimensions of a matrixsheet, you can use the MatrixLayer::SetSize method.
  4. // set num rows and cols
    MatrixLayer ml = Project.ActiveLayer(); // Get active matrixsheet
    ml.SetSize(-1, 5, 5);  // Set dimensions by 5x5
  5. Also, the MatrixObject class has provided the SetSize method for setting dimensions. However, please note, even this method is defined in MatrixObject, what it changes is the matrixsheet's dimension, because all matrix objects in the same matrixsheet have the same dimensions.
  6. // set num rows and cols
    MatrixLayer ml = Project.ActiveLayer(); // Get active matrixsheet	
    MatrixObject mo = ml.MatrixObjects(0); // Get the first object
    
    int nNumRows = 5, nNumCols = 5;
    mo.SetSize(nNumRows, nNumCols);  // Set dimensions by 5x5
  7. Matrices have numbered columns and rows which are mapped to linearly spaced X and Y values. You can use the SetXY method to set the XY mapping coordinates. Note: this method is available by matrix object, however, the XY mapping is shared by all matrix objects in the same matrixsheet.
  8. MatrixLayer ml = Project.ActiveLayer();  // Get active layer
    MatrixObject mo = ml.MatrixObjects(0);  // Get the first matrix object
    mo.SetXY(-10, 20, -2.3, 12.4);  // Set X from -10 to 20, and Y from -2.3 to 12.4

Get and Set Labels

A matrix label includes a Long Name, Units, and Comments for X, Y, Z. The labels of X and Y are for all matrix objects in the matrixsheet, the label of Z is for each matrix object. The following code shows how to get and set the labels.

  1. Set XY Labels
  2. MatrixPage mp("MBook1");
    MatrixLayer ml = mp.Layers(0); // the first matrixsheet	
    
    Tree tr;
    tr.Root.Dimensions.X.LongName.strVal = "X Values";
    tr.Root.Dimensions.X.Unit.strVal = "X Units";
    tr.Root.Dimensions.X.Comment.strVal = "X Comment";
    
    tr.Root.Dimensions.Y.LongName.strVal = "Y Values";
    tr.Root.Dimensions.Y.Unit.strVal = "Y Units";
    tr.Root.Dimensions.Y.Comment.strVal = "Y Comment";
    
    // Note, set format on matrixsheet for XY labels.
    if( 0 == ml.UpdateThemeIDs(tr.Root) )
    	ml.ApplyFormat(tr, true, true);
  3. Get XY Labels
  4. MatrixPage mp("MBook1");
    MatrixLayer ml = mp.Layers(0); // the first matrixsheet
    
    // Note, get XY labels from matrixsheet, not matrix object.
    Tree tr;
    tr = ml.GetFormat(FPB_ALL, FOB_ALL, TRUE, TRUE);
    
    TreeNode trX = tr.Root.Dimensions.X;
    if( !trX.LongName.IsEmpty() )
    	printf("X Long Name: %s\n", trX.LongName.strVal);
    if( !trX.Unit.IsEmpty() )
    	printf("X Unit: %s\n", trX.Unit.strVal);
    if( !trX.Comment.IsEmpty() )
    	printf("X Comment: %s\n\n", trX.Comment.strVal);
    
    TreeNode trY = tr.Root.Dimensions.Y;
    if( !trY.LongName.IsEmpty() )
    	printf("Y Long Name: %s\n", trY.LongName.strVal);
    if( !trY.Unit.IsEmpty() )
    	printf("Y Unit: %s\n", trY.Unit.strVal);
    if( !trY.Comment.IsEmpty() )
    	printf("Y Comment: %s\n", trY.Comment.strVal);
  5. Set Z Labels
  6. MatrixPage mp("MBook1");
    MatrixLayer ml = mp.Layers(0); // the first matrixsheet
    MatrixObject mo = ml.MatrixObjects(0);// the first matrix object
    
    // construct format tree and assign string value to tree nodes
    Tree tr;	
    tr.Root.LongName.strVal = "Z Long Name";
    tr.Root.Unit.strVal = "Z Units";
    tr.Root.Comment.strVal = "Z Comment";
    
    // Note, here apply format on matrix object to set Z labels, not matrixsheet.
    if( 0 == mo.UpdateThemeIDs(tr.Root) ) // add id for each tree node
    	mo.ApplyFormat(tr, true, true);	// do apply
  7. Get Z Labels
  8. MatrixPage mp("MBook1");
    MatrixLayer ml = mp.Layers(0); // the first matrixsheet
    MatrixObject mo = ml.MatrixObjects(0);
    
    Tree tr;	
    tr = mo.GetFormat(FPB_ALL, FOB_ALL, TRUE, TRUE);
    
    printf("Z Short Name: %s\n", tr.Root.ShortName.strVal);
    if( !tr.Root.LongName.IsEmpty() )// if not empty
    	printf("Z Long Name is %s\n", tr.Root.LongName.strVal);
    if( !tr.Root.Unit.IsEmpty() )
    	printf("Z Unit is %s\n", tr.Root.Unit.strVal);
    if( !tr.Root.Comment.IsEmpty() )
    	printf("Z Comment is %s\n", tr.Root.Comment.strVal);

Format Matrixsheet

A matrixsheet can be formatted programmatically using a theme tree.

The example below formats a block of cells in the active matrixsheet to have a blue background and light-magenta text.

MatrixLayer ml = Project.ActiveLayer();
 
Tree tr;
tr.Root.CommonStyle.Fill.FillColor.nVal = SYSCOLOR_BLUE;
tr.Root.CommonStyle.Color.nVal = SYSCOLOR_LTMAGENTA;
 
DataRange dr;
dr.Add(NULL, ml, 2, 2, 5, 3); // first row, col, last row, col
if( 0 == dr.UpdateThemeIDs(tr.Root) )
    dr.ApplyFormat(tr, TRUE, TRUE);

Get and Set Matrix Cell Text Color

The next example shows how to get and set the text color of a cell.

// Wrap the 'set' code into a simpler utility function.
bool setCellTextColor(Datasheet& ds, int row, int col, uint color)
{
    Grid grid;
    if( !grid.Attach(ds) )
        return false;
    vector<uint> vTextColor(1);
    vTextColor[0] = color;
    return grid.SetCellTextColors(vTextColor, col, row, row);
}
 
// Wrap the 'get' code into a simpler utility function.
bool getCellTextColor(Datasheet& ds, int row, int col, uint& color)
{
    Grid grid;
    if( !grid.Attach(ds) )
        return false;
    vector<uint> vTextColor;
    if( !grid.GetCellTextColors(vTextColor, col, row, row) )
        return false;
    color = vTextColor[0];
    return true;
}
 
// Simple function for testing the above utility functions.
void testCellTextColor(int nRow = 3, int nCol = 4)
{
    MatrixLayer ml = Project.ActiveLayer();
	// nRow, nCol use LT/GUI indexing, 1-offset, but OC is 0-offset
	int row = nRow-1, col = nCol-1;
    setCellTextColor(ml, row, col, SYSCOLOR_BLUE);
 
    uint color;
    getCellTextColor(ml, row, col, color);
    printf("color == %d\n", color);
}