Hiding Inherited Parameters

Introduction

The Object Node Example illustrates how to retrieve the inherited parameters and use them in the node's own parameter list. However, for nodes with very large list, it is often desirable to tidy it up and hide some of the less relevant parameters.

One way to clean up the parameter interface, is to put all newly added parameters in one folder and to put the inherited parameters in the second folder. Another way to clean up the interface is to set the PRM_TYPE_INVISIBLE flag in the parameter type, which will hide such parameter from the UI. The examples below describe these approaches in more detail.

Putting Parameters in a Folder

The source code of OBJ_Shake.C illustrates one approach of cleaning up the parameter list. It puts all the inherited parameters in its own folder, however you need to uncomment the SWITCHER_EXAMPLE define to compile this example properly. The trick is to define a parameter of type PRM_SWITCHER, which will partition the list into folders. The PRM_SWITCHER parameter takes a default value array whose entries specify the name of a folder and how many parameters it should contain. All parameters that follow the switcher parameter are partitioned according to these counts and each set of parameters is put into own folder with the corresponding name.

static PRM_Name     OBJjitter("jitter",           "Jitter scale");
static PRM_Name     OBJswitcherName("shakeswitcher");

static PRM_Default      switcher[] = {
    PRM_Default( 1, "Shake"),       // 1 is number of parameters in tab
    PRM_Default( 0, "Other"),       // actually have no parameters here
};

static PRM_Template     templatelist[] =
{
    // the switcher that defines the parameter folders
    PRM_Template(PRM_SWITCHER,  sizeof(switcher)/sizeof(PRM_Default),
                                &switcherName, switcher),

    // the jitter parameter
    PRM_Template(PRM_XYZ_J, 3, &OBJjitter, PRMoneDefaults),

    PRM_Template()  // terminator
};

Parameter Hiding Example

This example shows how to retrieve the inherited parameter list and then process it to hide all of the parameters except the translation parameter, t. The full source code is available in the toolkit example file OBJ_WorldAlign.C.

Parameter hiding is achieved by setting the PRM_TYPE_INVISIBLE flag in its type. Altering the inherited parameter list is risky, because it may affect geometry object node (implemented by the base class OBJ_Geometry). So, we need to copy the original parameter and initialize that new copy with the invisible flag.

static void
copyParmWithInvisible(PRM_Template &src, PRM_Template &dest)
{
    . . .
    dest.initialize(
            (PRM_Type) (src.getType() | PRM_TYPE_INVISIBLE),
    . . .
}

Then, when building the parameter list template, we iterate through the base class parameters and copy them while adding the invisible flag. For the translation parameter, we leave the original unchanged, and because its invisible flag is clear, it will show up in the parameter pane. The switcher also needs to be visible for its folders (and their content) to be visible.

OP_TemplatePair *
OBJ_WorldAlign::buildTemplatePair(OP_TemplatePair *prevstuff)
{
    OP_TemplatePair     *align, *geo;
    static PRM_Template *theTemplate = 0;

    if(!theTemplate)
    {
        PRM_Template    *obj_template;
        int              i, size;
        UT_String        parm_name;

        // retrieve the base class parameters
        obj_template = OBJ_Geometry::getTemplateList(OBJ_PARMS_PLAIN);
        size = PRM_Template::countTemplates( obj_template );
        theTemplate = new PRM_Template[size + 1];   // add +1 for sentinel
        for( i = 0; i < size; i++ )
        {
            theTemplate[i] = obj_template[i];
            theTemplate[i].getToken( parm_name );

            // leave only the translation parameter visible 
            if( parm_name != "t" && parm_name != "stdswitcher" )
                copyParmWithInvisible( obj_template[i], theTemplate[i] );
        }
    }

    // concatenate the altered copies of the inherited parameters and own ones
    align = new OP_TemplatePair(templatelist, prevstuff);
    geo   = new OP_TemplatePair(theTemplate, align);

    return geo;
}