2.2.4.17.3 GraphLayer::AddPlot

AddPlot

Description

Before plotting with this method, please make sure to create a graph with the correct template and plot ID.

Add one data plot to layer

It adds a copy of an existing dataplot to a graph layer.

Add DataPlot using a range that represent one or more data plots

Add one data plot to layer by using the existing styleholder. The styleholder is usually used in templates to determine the type and other properties of a dataplot which uses the styleholder when being added to a layer.

Add entire worksheet to layer.

Plot a Matrix into a graph layer

Syntax

int AddPlot( Curve & cData, int nPlotID = IDM_PLOT_UNKNOWN, uint dwCntrl = GAP_USE_TEMPLATE )

int AddPlot( DataPlot & dp, DWORD dwOptions = ADDPLTPFROMPLT_ERRORBAR )

int AddPlot( const DataRange & dr, int nPlotID = IDM_PLOT_SCATTER, uint dwCntrl = GAP_GROUP_PLOTS | GAP_USE_TEMPLATE | GAP_ALLOW_DUPLICATE_COL, int * pnAddtionalAddedPlots = NULL, int nAddtionalAddedPlotsBufferSize = 0 )

int AddPlot( Curve & cData, StyleHolder & style )

int AddPlot( Worksheet & wks, int nPlotID = IDM_PLOT_UNKNOWN )

int AddPlot( MatrixObject & matObj, int nPlotID = IDM_PLOT_MATRIX_IMAGE, uint dwCntrl = GAP_USE_TEMPLATE )

Parameters

cData

[input] Data curve to add

nPlotID

[input] Specifies the plot type. The most common are

IDM_PLOT_LINE for line;

IDM_PLOT_SCATTER for scatter;

IDM_PLOT_LINESYMB for line + symbol.

For the list of all plot types, see Plot Type IDs.

dwCntrl

additional control bits, see GraphAddPlotCtrls enum, like GAP_ALLOW_DUPLICATE_COL, GAP_NO_SET_X_TICK_TYPE

dp

[input] source dataplot

dwOptions

[input] optional options (see ADDPLTPFROMPLT_* bits in OC_const.h)

dr

[input] a DataRange that contains named subranges for plotting. It can be a singple XY or can be XYYY types to create multiple plots.

nPlotID

[input] Specifies the plot type. The most common are

IDM_PLOT_LINE for line;

IDM_PLOT_SCATTER for scatter;

IDM_PLOT_LINESYMB for line + symbol.

For the list of all plot types, see Plot Type IDs.

dwCntrl

additional control bits, see GraphAddPlotCtrls enum, like GAP_USE_TEMPLATE, GAP_ALLOW_DUPLICATE_COL, GAP_GROUP_PLOTS, GAP_NO_SET_X_TICK_TYPE

pnAddtionalAddedPlots

[output, optional] if supplied, it will receive the indices of the dataplots beyond the first added dataplot (the index

of the first added dataplot is the return value of the method). On return, the value -1 inside the buffer pnAddtionalAddedPlots will

indicate the end. So, for example, if there total of two plots added, the index of the first added plot will be returned from the method,

whereas the index of the second added plot will be put into *pnAddtionalAddedPlots; also, *(pnAddtionalAddedPlots + 1)

(provided nAddtionalAddedPlotsBufferSize > 1) will be -1, indicating that there were no more added plots.

nAddtionalAddedPlotsBufferSize is the size of the buffer pnAddtionalAddedPlots.

nAddtionalAddedPlotsBufferSize

cData

[input]Data curve to add

style

[input]the style holder to use when creating the dataplot

wks

[input]worksheet object containing all data.

nPlotID

[input] Specifies the plot type. The most common are

IDM_PLOT_LINE for line;

IDM_PLOT_SCATTER for scatter;

IDM_PLOT_LINESYMB for line + symbol.

For the list of all plot types, see Plot Type IDs.

matObj

[input] Matrix data object

nPlotID

[input] Specifies the plot type. The most common are

IDM_PLOT_LINE for line;

IDM_PLOT_SCATTER for scatter;

IDM_PLOT_LINESYMB for line + symbol.

For the list of all plot types, see Plot Type IDs.

Return

0-offset data plot index of the dataplot added or -1 for error

If a dataplot added, returns its index in the layer, or -1 for failure. If there already

existed a dataplot with the same dataset as the source dataplot, then, if dwOptions does not have ADDPLTPFROMPLT_FAIL_IF_DATASET_ALREADY_PRESENT

and it does not have ADDPLTPFROMPLT_ADD_EVEN_IF_DATASET_PRESENT,

the index of the existing dataplot is returned (no new dataplot added), otherwise -1 is returne;

if it has ADDPLTPFROMPLT_FAIL_IF_DATASET_ALREADY_PRESENT, but not ADDPLTPFROMPLT_ADD_EVEN_IF_DATASET_PRESENT, it will

return error (-1). if it has ADDPLTPFROMPLT_ADD_EVEN_IF_DATASET_PRESENT, but not ADDPLTPFROMPLT_FAIL_IF_DATASET_ALREADY_PRESENT, it will

add a new dataplot regardless of whether it already has the same dataset. If both ADDPLTPFROMPLT_ADD_EVEN_IF_DATASET_PRESENT and

ADDPLTPFROMPLT_FAIL_IF_DATASET_ALREADY_PRESENT are present, it will return error (-1) without doing anything.

0-offset data plot index of the dataplot added or -1 for error.

0-offset data plot index of the dataplot added or -1 for error

Examples

EX1

// For this example to run, a worksheet with columns "A" and "B" must
// exist with some numeric data in them.
// Draw a 2d scatter plot.
void    GraphLayer_AddPlot_ex1()
{
    // Construct the Curve object specifying the x and y datasets to be used for
    // the dataplot
    Worksheet wks = Project.WorksheetPages(0).Layers(0);
    if(wks)
    {
        Curve        cc(wks, 0, 1);
 
        // the graph layer needs to be initialized:
        GraphPage gp;
        gp.Create("origin");
        GraphLayer    lay = gp.Layers(0);
        if(lay)
        {                
            // Add the dataplot to the graph:
            int            nIndex = lay.AddPlot(cc, IDM_PLOT_SCATTER);
            lay.Rescale();
            // Display the index of the data plot just added:
            out_int("Dataplot index = ", nIndex);
        }
    }
}

EX2

// For this example to run, the inactive source graph 
// needs to have one dataplot in the first layer.
// Also, another empty graph needs to be active.
//Create a copy of the exist graph with error bar.
void    GraphLayer_AddPlot_ex2()
{
    GraphLayer        grLayDest = Project.ActiveLayer();    
    if ( !grLayDest )
    {
        out_str("Invalid destination layer");
        return;
    }
    
    GraphPage        grPgSource = Project.GraphPages(0);
    if ( !grPgSource )
    {
        out_str("Invalid source page");
        return;
    }
    
    GraphLayer        grLaySource = grPgSource.Layers(0);
    if ( !grLaySource )
    {
        out_str("Invalid source layer");
        return;
    }
    
    DataPlot        dpSource = grLaySource.DataPlots(0);
    if (!dpSource)
    {
        out_str("Invalid source dataplot");
        return;
    }
    
    int                nReturn = grLayDest.AddPlot(dpSource, ADDPLTPFROMPLT_FAIL_IF_DATASET_ALREADY_PRESENT|ADDPLTPFROMPLT_ERRORBAR);
    out_int("nReturn = ", nReturn);
    
    grLayDest.Rescale();
    
    return;
}

EX3

// plot two XY ranges from two worksheets as a grouped line symbol plot
void GraphLayer_AddPlot_ex3(int npts = 250)
{
	// prepare worksheet 1
 	WorksheetPage wksPage; 
 	wksPage.Create("Origin");
 	Worksheet wks = wksPage.Layers(-1);
 	wks.Columns(0).SetLongName("Temperature (C\+(o))");
    wks.Columns(1).SetLongName("Resistance (Ohms)");
 	
    Dataset dx1(wks, 0);
    dx1.Data(1, npts);
    dx1 *= 0.05;
    
    Dataset dy1(wks, 1);
    dy1.Normal(npts);
    dy1 += 1.2;
    
 	// prepare worksheet 2    
 	WorksheetPage wksPage2; 
 	wksPage2.Create("Origin");
 	Worksheet wks2 = wksPage2.Layers(-1);    
  	wks2.Columns(0).SetLongName("Temperature (C\+(o))");
    wks2.Columns(1).SetLongName("Ceramic body");    
    Dataset dx2(wks2, 0);
    dx2 = dx1 * 2;    
    Dataset dy2(wks2, 1);
    dy2.Normal(npts);
    dy2 += 2.2;

    // construct data range
    DataRange dr;
    dr.Add(wks, 0, "X");
    dr.Add(wks, 1, "Y");
    dr.Add("S", NULL); // S:<empty>, add range separator to separate two XY ranges
    
    dr.Add(wks2, 0, "X");
    dr.Add(wks2, 1, "Y");
 
    // prepare graph window
    GraphPage gp;
    gp.Create("origin", CREATE_HIDDEN);
    GraphLayer gl = gp.Layers();
 
    //GAP_GROUP_PLOTS is specified by default, so if data range has multiple plots, they will be grouped
    gl.AddPlot(dr, IDM_PLOT_LINESYMB);
 
    gl.Rescale();
    legend_update(gl); // to update the legend loaded in from template
    gp.SetShow();
}

EX4

//the following example shows how to plot the same column in a graph, first part using scatter, and second part using line
void GraphLayer_AddPlot_ex4()
{
    Worksheet wks;
    wks.Create("origin", CREATE_HIDDEN);
    wks.SetSize(50,3);
    
    int nXCol = 1; // test not using 1st X col
    int nYCol = 2;
    Dataset dx(wks, nXCol);
    dx.Data(1,50);
    dx *= 0.05;
    Dataset dy(wks, nYCol);
    dy.Normal(50);
    dy += 1.2;

    int nR1 = 20;
    DataRange dr;
    dr.Add("X", wks, 0, nXCol, nR1, nXCol);
    dr.Add("Y", wks, 0, nYCol, nR1, nYCol);
    
    GraphPage gp;
    gp.Create("origin", CREATE_HIDDEN);
    GraphLayer gl = gp.Layers();
    gl.AddPlot(dr, IDM_PLOT_SCATTER);
    
    // add 2nd plot of same range
    DataRange dr2;
    dr2.Add("X", wks, nR1, nXCol, -1, nXCol);
    dr2.Add("Y", wks, nR1, nYCol, -1, nYCol);
    gl.AddPlot(dr2, IDM_PLOT_LINE, GAP_ALLOW_DUPLICATE_COL | GAP_USE_TEMPLATE);
    
    gl.Rescale();
    legend_update(gl); // to update the legend loaded in from template
    gp.SetShow();
}

EX5

//the following example shows how to make a 3D scatter plot and change the drop line of the symbols
// assume active worksheet, will fill it with sample data    
void GraphLayer_AddPlot_ex5(int npts = 30, int nXCol = 0, int nYCol = 1, int nZCol = 2)
{
    Worksheet wks = Project.ActiveLayer();
    if( wks )
    {
        wks.SetSize(-1,3);
        wks.SetColDesignations("XYZ");
        Dataset dsX(wks, nXCol);
        Dataset dsY(wks, nYCol);
        Dataset dsZ(wks, nZCol);
        dsX.Data(1, npts);
        dsX *= 0.05;
        dsY.Normal(npts);
        dsY += 1.2;
        dsZ.Normal(npts);

        DataRange dr;
        dr.Add("X", wks, 0, nXCol, -1, nXCol);
        dr.Add("Y", wks, 0, nYCol, -1, nYCol);
        dr.Add("Z", wks, 0, nZCol, -1, nZCol);

        GraphPage gp;
        // You must use a 3D scatter/line template, you can first make a 3d scatter plot, 
        //   make needed modifications, then save your own
        gp.Create("3D"); 
        if( gp )
        {
            GraphLayer gl = gp.Layers();
            if( gl )
            {
                int nPlot = gl.AddPlot(dr, ID_3D_GRAPH_SCATTER);
                DataPlot dp = gl.DataPlots(nPlot);
                Tree tr;
                tr = dp.GetFormat(FPB_ALL, FOB_ALL, true, true); 
                //set drop line to along Y axis only
                TreeNode trdrop = tr.Root.DropLines;
                trdrop.X.nVal = 0;
                trdrop.Z.nVal = 0;
                trdrop.Y.nVal = 1;
                dp.ApplyFormat(tr, true, true);
                gl.Rescale();
            }
        }
    }
}

EX6

// This example shows how to plot a fill area graph into any
// graph layer (without the help of a fill-area template        
void GraphLayer_AddPlot_ex6(int nY1 = 1, int nY2 = 2, int nX = 0)
{
    Worksheet wks = Project.ActiveLayer();
    DataRange dr;
    dr.Add(wks, nX, "X");
    dr.Add(wks, nY1, "Y");
    dr.Add(wks, nY2, "Y");
    GraphPage gp;
    gp.Create(); // load with default template
    GraphLayer gl = gp.Layers();
 
    int nPlot = gl.AddPlot(dr, IDM_PLOT_HILOCLOSE);
 
    DataPlot dp = gl.DataPlots(nPlot);
 
    Tree tr;
    tr.Root.Line.Connect.nVal = 1;
    int nRet = dp.UpdateThemeIDs(tr.Root);
    if(0==nRet)
    {
        dp.ApplyFormat(tr, true, true);
		gl.Rescale();
    }
    else
        out_str("plot settings tree construction error");
 
}

EX7

// For this example to run, a graph window must exist in the project.
// Also, a worksheet with columns "A" and "B" must
// exist with some numeric data in them.
// Draw a Box Chart graph.
void    GraphLayer_AddPlot_ex7()
{
    // Construct the Curve object specifying the x and y datasets to be used for
    // the dataplot
    Worksheet wks = Project.WorksheetPages(0).Layers(0);
    if(wks)
    {
        Curve        cc(wks, 0, 1);
 
        // the graph layer needs to be initialized:
        GraphPage gp;
        gp.Create("Box");
        GraphLayer    lay = gp.Layers(0);
        // Get the first style holder in the layer.
        StyleHolder style;
        style = lay.StyleHolders(0); 
 
        // Check that the style holder is valid:
        if (!style.IsValid())
        {
            out_str("No style holders found!");
            return;
        }
 
        // Add the dataplot to the graph:
        int            nIndex = lay.AddPlot(cc, style);
        lay.Rescale();
 
        // Display the index of the data plot just added:
        out_int("Dataplot index = ", nIndex);
    }
}

EX8

// For this example to run, a graph window must exist in the project.
// Also, a worksheet must exist with some numeric data.
void GraphLayer_AddPlot_ex8()
{
    Worksheet wks = Project.WorksheetPages(0).Layers(0);
    if(wks)
    {
        GraphPage gp;
        gp.Create();
        GraphLayer    gl = gp.Layers(0);
        if(gl)
        {
            gl.AddPlot(wks);
        }
    }
}

EX9

// important step to set the correct template to make 3D plots
//IDM_PLOT_3D_MESH,        "mesh" // filled surface
//IDM_PLOT_3D_MESH,        "cmap" // colormap surface
//IDM_PLOT_3D_MESH,        "3Dbars"
//IDM_PLOT_3D_MESH,        "wirefrm" // wireframes
//IDM_PLOT_3D_MESH,        "wireface"  
//IDM_PLOT_CONTOUR,        "contour"
//IDM_PLOT_CONTOUR,        "contline"
//IDM_PLOT_CONTOUR,        "contgray"
//IDM_PLOT_MATRIX_IMAGE,"image"

// 
// this function plots the given matrix into a new graph
// if nNewLevels is specified, will change the colormap to the specified number of levels
// for plots not using colormap, must pass in 0
bool plot_matrix(MatrixObject& mobj, LPCSTR lpcszTemplate, int nNewLevels = 0, int nPlotID = IDM_PLOT_CONTOUR)
{
    GraphPage gp;
    gp.Create(lpcszTemplate, CREATE_HIDDEN); // use template, create as hidden to avoid unneeded drawing            
    GraphLayer glay = gp.Layers();
    
    int nPlot = glay.AddPlot(mobj, nPlotID);
    if(nPlot < 0)
        return false;            
    
    string strTemp;
    if(nNewLevels) // to reset number of levels in color map
    {
        DataPlot dp = glay.DataPlots(nPlot); 
        BOOL bLogScale;
        vector vLevels;
        if(dp.GetColormap(vLevels, bLogScale))
        {                
            if(nNewLevels != vLevels.GetSize())
            {
                double min = vLevels[0], max = vLevels[vLevels.GetSize()-1];
                double step = (max - min) / (nNewLevels - 1);
                vLevels.Data(min, max, step);
                
                if(dp.SetColormap(vLevels))  
                    strTemp = " Colormap is modified, levels = " + nNewLevels;
            }
        }
    }
    gp.Label = "Plot created using template: " + (string)lpcszTemplate + strTemp;
    gp.TitleShow = WIN_TITLE_SHOW_BOTH;
    glay.Rescale();
    gp.SetShow();// show it when all it ready
    return true;
}

void GraphLayer_AddPlot_ex9()
{
    MatrixLayer mlayer = Project.ActiveLayer();
    MatrixObject mobj = mlayer.MatrixObjects();
    
    plot_matrix(mobj, "contour", 6); // contour filled color
    plot_matrix(mobj, "contour", 22);// contour lines only
    plot_matrix(mobj, "image", 0, IDM_PLOT_MATRIX_IMAGE);
    plot_matrix(mobj, "cmap", 18, IDM_PLOT_3D_MESH);
    plot_matrix(mobj, "wirefrm", 0, IDM_PLOT_3D_MESH);
}

Remark

See Also

Header to Include

origin.h