2.2.4.32.46 OriginObject::SetName

SetName

1 Description
2 Syntax
3 Parameters
4 Return
5 Examples
6 Remark
7 See Also
8 Header to Include

Description

Rename a Page.

Syntax

BOOL SetName( LPCSTR lpcszNewName, DWORD dwOptions = 0 )

Parameters

lpcszNewName: [input] Pointer to string holding the new Short Name of the page (or Long Name if bLongName is TRUE)
dwOptions: [input] Bits representing options. See OCD_* defines OC_Const.h

Return

TRUE for success, FALSE for failure.

Examples

EX1

int OriginObject_SetName_ex1()
{
    PageBase pb = Project.Pages(); // Get the active page
    if( pb )
    {
        string strOldName = pb.GetName();
        string strNewName = strOldName + "AA";
        if( pb.SetName(strNewName) >=0 )
            printf("Page renamed from %s to %s\n", strOldName, strNewName);
        else
            printf("Failed to rename page\n");
    }
    else
        printf("There is no Active page\n");
    return 0;
}

EX2

// Try to create some workbooks of the same name (not allowed)
// and handle with dialog or automatically
// WARNING! The example closes the current project without prompting to save
int OriginObject_SetName_ex2()
{
    Project.ClearModified(); // Prevent Save As dialog
    Project.Open(); // Open new project
    WorksheetPage wp1;
    string strTitle = "Full Name Enumerated - 1";             // Last character = 1 to invoke auto enumeration, also keeps
                                                              // long/short name consistent with respect to enumeration
    wp1.Create("origin.otw");                                // Create workbook
    wp1.SetName(strTitle, OCD_LONG_NAME);                    // Name it
    ASSERT(wp1.GetLongName() == "Full Name Enumerated - 1");    // Test success of Long Name
    ASSERT(wp1.GetName() == "FullNameEnu1");                    // Test success of Short Name
    
    WorksheetPage wp2;
    wp2.Create("origin.otw");                                // Create another workbook
    wp2.SetName(strTitle, OCD_LONG_NAME);                    // Name it with the same name as previous - see next comment

    // A dialog will open asking how to name the window due to name conflict
    // No dialog appears in the following case because the control bit to auto-enumerate names (OCD_ENUM_NEXT) has been added    
    WorksheetPage wp3;
    wp3.Create("origin.otw");                                // Create another workbook
    wp3.SetName(strTitle, OCD_LONG_NAME | OCD_ENUM_NEXT);    // Name it with the same name as previous and use enumeration

    return 0;
}

Remark

The SetName 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 option Long Name is not specified (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 option Long Name is not specified and the Long Name is not the same as the Short Name then only the Short Name is changed. If option Long Name is specified then this function will change both the Long Name and the Short Name.

however option Ask must also be off to ensure name enumeration.

Page Short Names must always be unique within the Origin project but page Long Names have no such limitation. If option Ask is off 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 option Ask is on 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.