2.2.4.33.1 Page::AddLayer

AddLayer

Description

Add a new Layer to the page giving it the specified name. Can be used with GraphPage, WorksheetPage, or MatrixPage. The specified Layer name if already exist in the page the new Layer's name will be enumerated.

Copy an existing Layer from one page to another. Can be used with GraphPage, WorksheetPage or MatrixPage.

Syntax

int AddLayer( LPCSTR lpcszLayerName = NULL, DWORD dwOptions = 0, LPCSTR lpcszTemplate = NULL, DWORD dwOption2 = 0, LPCSTR lpcszSheet = NULL )

int AddLayer( Layer & layerToCopy, DWORD dwOptions = DCTRL_COPY_DEFAULT, BOOL bKeepSrcLayer = true, int nNewLayerPos = -1 )

Parameters

lpcszLayerName

[input]Optional name of the new layer. If the specified Layer name already exists in the Page, the new Layer's name is automatically enumerated to make it unique. Consequently, you can not assume the new Layer will always have the specified name. Pass Null for lpcszLayerName to preseve the sheet name stored in the template lpcszTemplate.

dwOptions

[input]Options for the new layer which are dependent on the page layer type. Bits such as CREATE_NO_DEFAULT_TEMPLATE can be used.

lpcszTemplate

[input]Optional template to load the layer from. Use lpcszLayerName=NULL to preseve sheet name in template otherwise sheet will be renamed by lpcszLayerName.

dwOption2

[input]Additional option settings.

lpcszSheet

optionally specifies sheet name from a multiple-sheet template to be loaded, if NULL first sheet is used

layerToCopy

[input]input Layer to copy.

dwOptions

[input] copy layer options, can be one or more of the following

DCTRL_COPY_DATA, DCTRL_COPY_IN_OPERATIONS, DCTRL_COPY_OUT_OPERATIONS, DCTRL_COPY_LINKED_LAYERS, DCTRL_COPY_DEFAULT (= DCTRL_COPY_DATA | DCTRL_COPY_OUT_OPERATIONS)

DCTRL_COPY_DATA, DCTRL_COPY_IN_OPERATIONS, DCTRL_COPY_OUT_OPERATIONS are specific to Worksheet layers

DCTRL_COPY_LINKED_LAYERS is specific to graph layers

bKeepSrcLayer

[input] if false, will do the same as drag sheet from source to destination and dwOptions will be ignored except DCTRL_ADD_LAYER_UNDOABLE

nNewLayerPos

[input] 0 for add to first sheet, -1 as last

Return

Returns the index (0 offset) of the newly added layer on successful exit or -1 on failure.

Returns the index (0 offset) of the newly added layer on successful exit or < 0 on failure.

Examples

EX1

//Add a new layer to worksheet
void Page_AddLayer_ex1()
{
	WorksheetPage wksPg;
	wksPg.Create("Origin");
	if (wksPg)
	{
		int nn = wksPg.AddLayer("New");	//Add a new sheet to worksheet
		Worksheet wksNew = wksPg.Layers(nn);	//Access the new sheet
		printf("A new sheet names \"%s\" was added\n", wksNew.GetName())
	}
}

EX2

//Add a new layer to graph
void Page_AddLayer_ex2()
{
    GraphPage gp;
    gp.Create("origin");
    if( gp )
    {
        int nn = gp.AddLayer("Test");
        if( nn >= 0 )
        {
            GraphLayer gl = gp.Layers(nn);
            if( gl )
                printf("A new layer named %s was added\n", gl.GetName());
        }
    }
}

EX3

// Add a Layer by loading a template sheet into the current workbook
int Page_AddLayer_ex3(string strTemplate="origin", bool bUseDefaultIfNotFound = true)
{
    WorksheetPage wp = Project.Pages(0);
    if( !wp )
        return 0;
    DWORD dwCntrl = bUseDefaultIfNotFound ? 0 : CREATE_NO_DEFAULT_TEMPLATE;
    int nn = wp.AddLayer("Test1", dwCntrl, strTemplate); // Created worksheet(layer) will be named Test1, Test2 etc.
    if( nn < 0 )
        printf("Failed to add a new sheet\n");
    else
    {
        Worksheet wks = wp.Layers(nn);
        if( wks )
            printf("New sheet added index = %d, name = %s, # cols = %d\n", nn, wks.GetName(), wks.GetNumCols());
    }
    return 0;
}

EX4

//Copy an existing Layer from one page to another
void Page_AddLayer_ex4()
{
    GraphPage gpTo; 
    gpTo.Create();
    GraphPage gpFrom;
    gpFrom.Create();
 
    if( gpTo && gpFrom )
    {
        GraphLayer glFrom = gpFrom.Layers(0);
        int nn = gpTo.AddLayer(glFrom);
        if( nn >= 0 )
        {
            GraphLayer glTo = gpTo.Layers(nn);
            if( glTo )
                printf("A new layer named %s was added to %s\n", glTo.GetName(), gpTo.GetName());
        }
    }
}

EX5

//Add a new layer copied from existing layer to worksheet page
int Page_AddLayer_ex5()
{
    GraphPage gp;
    gp.Create("origin");
    if( gp )
    {
        GraphLayer gl1 = gp.Layers(0);
        int nn = gp.AddLayer(gl1);
        if( nn >= 0 )
        {
            GraphLayer gl2 = gp.Layers(nn);
            if( gl2 )
                printf("A new layer named %s was added to %s\n", gl2.GetName(), gp.GetName());
        }
    }
    return 0;
}

EX6

//Add a new layer copied from existing layer to worksheet page
int Page_AddLayer_ex6()
{
    // Assume a workbook window exists in OPJ
    WorksheetPage wp = Project.Pages(0);
    if( wp )
    {
        Worksheet wks1 = wp.Layers(0);
        int nn = wp.AddLayer(wks1);
        if( nn >= 0 )
        {
            Worksheet wks2 = wp.Layers(nn);
            printf("A new layer named %s was added to %s, it's copied from %s.\n",wks2.GetName(), wp.GetName(), wks1.GetName());
        }
    }
    return 0;
}

EX7

//Create a new graph from 2 existing graphs by taking their respective 1st layer and 
//arrange top bottom in new graph.
int Page_AddLayer_ex7()
{
    GraphPage gp1; 
    gp1.Create();
    GraphPage gp2;
    gp1.Create();
 
    GraphPage gpNew;
    gpNew.Create("origin", CREATE_HIDDEN);
    GraphLayer glFirst1 = gp1.Layers(0);
    GraphLayer glFirst2 = gp2.Layers(0);
 
    GraphLayer glTop = gpNew.Layers(gpNew.AddLayer(glFirst1));
    GraphLayer glBottom = gpNew.Layers(gpNew.AddLayer(glFirst2));
 
    if( glTop && glBottom )
    {
        printf("Two new layers named %s and %s was added to %s\n", glTop.GetName(), glBottom.GetName(), gpNew.GetName());
 
        string strLT;
        int nLeft=15, nRight=10, nWidth=35, nHeight=35;
        strLT.Format("layer x y %d %d", nLeft, nRight);
        glTop.LT_execute(strLT);
 
        nRight=50;
        strLT.Format("layer x y %d %d", nLeft, nRight);
        glBottom.LT_execute(strLT);
 
        strLT.Format("layer.width=%d", nWidth);
        glTop.LT_execute(strLT);
        glBottom.LT_execute(strLT);
        strLT.Format("layer.height=%d", nHeight);
        glTop.LT_execute(strLT);
        glBottom.LT_execute(strLT);
 
    }
    gpNew.Layers(0).Destroy();
    gpNew.SetShow();

    return 0;
}

EX8

// drag first sheet from Book1 to end of book2
void Page_AddLayer_ex8(string strB1 = "Book1", string strB2 = "Book2")
{
    WorksheetPage w1(strB1);
    WorksheetPage w2(strB2);
    if(!w1)
        return;
    Worksheet wks1 = w1.Layers();
    if(!wks1)
        return;
    
    if(!w2)
    {
        w2.Create("origin.otw", CREATE_VISIBLE);
        Worksheet wks = w2.Layers(0);
        wks.Destroy(OCD_DEL_LINKED_OBJS);
    }
    
    w2.AddLayer(wks1, DCTRL_ADD_LAYER_UNDOABLE, false);
}

EX9

// merge all books in current folder and move all their sheets to the
// specified book. If no book is specified, then merge to the active book in folder
void Page_AddLayer_ex9(string strBook = "")
{
	WorksheetPage wb(strBook);
	if(!wb)
		wb = Project.Pages();
	
	if(!wb)
	{
		out_str("no valid book found to merge into");
		return;
	}
	wb.GetName(strBook);
	
	string strTemp;
	
	Folder fld = Project.ActiveFolder(); 
    foreach(PageBase pb in fld.Pages)
    {
    	WorksheetPage wb1 = pb;
    	if(!wb1)
    		continue;//not a workbook
    	wb1.GetName(strTemp);
    	if(strTemp == strBook)
    		continue;//skip our destination book
    	
    	foreach(Layer lay in wb1.Layers)
    	{
    		Worksheet wks = lay;
    		wb.AddLayer(wks, 0, false);
    	}
    	wb1.Destroy();
    }
}

Remark

See Also

Header to Include

origin.h