2.2.4.34.20 PageBase::Rename

Rename

Description

Rename a Page.

Syntax

int Rename( LPCSTR lpcszNewName, BOOL bAskIfAlreadyUsed = FALSE, BOOL bLongName = FALSE )

Parameters

lpcszNewName

[input]Pointer to string holding the new Short Name of the page (or Long Name if bLongName is TRUE)

bAskIfAlreadyUsed

[input]TRUE opens a dialog box to ask for a new name when lpcszNewName already exists, FALSE causes name enumeration as described above

bLongName

[input]TRUE if lpcszNewName points to a Long Name and both Long and Short Names are to be changed

Return

Returns 1 if lpcszNewName is successfully used to rename the page, 0 if some other name is used to rename the page (either by user input or by enumeration), and -1 if the user clicks Cancel when asked for a new Short Name due to name duplication.

Examples

EX1

int PageBase_Rename_ex1()
{
    PageBase pb = Project.Pages(); // Get the active page
    if( pb )
    {
        string strOldName = pb.GetName();
        string strNewName = "Graph2";
        int nRet =  pb.Rename(strNewName);
        if( nRet > 0 )
            printf("Page renamed from %s to %s\n", strOldName, strNewName);
        else 
        	if( nRet == 0 )
				printf("Graph2 already exists, so rename this page to %s by enumeration\n", pb.GetName());
			else
				printf("Failed to rename page\n");
    }
    else
        printf("There is no Active page\n");
    return 0;
}

EX2

void PageBase_Rename_ex2()
{
    Project.ClearModified(); // Prevent Save As dialog
    Project.Open(); // Open new project
    WorksheetPage wp;
    string strTitle = "Full Name Enumerated - 1"; // Last character = 1 to invoke auto enumeration, also keeps
                                                  //   long/short name consistent with respect to enumeration
    wp.Create("origin.otw");
    wp.Rename(strTitle, FALSE, TRUE);//both Long and Short Names are to be changed 

    // Create another workbook
    WorksheetPage wp2;
    wp2.Create("origin.otw");
    wp2.Rename(strTitle, TRUE, FALSE);//TRUE, opens a dialog box to ask for a new name when lpcszNewName already exists
}

Remark

The Rename function is primarily used to rename the Short Name of an Origin page (window) but may alter the Long Name of

the page depending on circumstances and options chosen. If the argument bLongName is FALSE (default) then only the Short

Name is changed unless the Long Name is the same as the Short Name in which case the Long Name is also changed (to maintain

sameness with the now changed Short Name). If bLongName is FALSE and the Long Name is not the same as the Short Name then

only the Short Name is changed. If bLongName is TRUE then this function will change both the Long Name and the Short Name

however bAskIfAlreadyUsed must also be FALSE to ensure name enumeration.

Page Short Names must always be unique within the Origin project but page Long Names have no such limitation. If bAskIfAlreadyUsed

is FALSE then name enumeration automatically occurs for the Short Name when an existing Short Name is specified for lpcszNewName

(with no intervening dialog asking for a unique name). To keep the Long Name and Short Name consistent with respect to enumeration

include the character '1' as the last character of the argument lpcszNewName. If bAskIfAlreadyUsed is TRUE and a specified Short

Name already exists then enumeration does not occur and a dialog asking for a new Short Name opens.

The function OriginObject::SetLongName should be primarily used to change page Long Names.

See Also

PageBase::GetName, OriginObject::SetLongName

Header to Include

origin.h