1.5.2.1 Basic Matrix Sheet OperationExamples 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
Matrixbook, Add One SheetMatrixbook, Activate a SheetAdd 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
Active MatrixsheetActive WindowActive WorkbookActive MatrixbookTo 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 Matrixbookmatrixbook, Get One Sheetmatrixbook, Get Name
Similar to accessing worksheets in workbook, matrixsheets in matrixbook can also be accessed by the following ways.
- By full layer name.
// 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);
- A matrixbook constains a collection of matrix layers. Loop through all matrix layers in a specified matrixbook using the foreach statement.
MatrixPage matPage("MBook1");
foreach(Layer ly in matPage.Layers)
out_str(ly.GetName());
- Access a specified matrixsheet by its name or index.
// 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).
- 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.
// 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
- To set dimensions of a matrixsheet, you can use the MatrixLayer::SetSize method.
// set num rows and cols
MatrixLayer ml = Project.ActiveLayer(); // Get active matrixsheet
ml.SetSize(-1, 5, 5); // Set dimensions by 5x5
- 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.
// 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
- 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.
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.
- Set XY LabelsMatrixsheet, Get/Set Labels for XY
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);
- Get XY Labels
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);
- Set Z LabelsMatrixsheet, Get/Set Labels for Z
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
- Get Z Labels
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);
}
|