Dynamically Changing Custom Properties

Changing Parameter Values

For any control with an underlying parameter, you can update the parameter value directly. Most of the time the new value appears immediately in the property page.

Note

The exception to this would be the case where you had specified a standard numeric control with the siUISyncSlider attribute set to false. In that case, you would have to refresh the layout in order to see the new values.

Parameters return either a data value or an object instance for the underlying parameter, depending on what that underlying parameter is. For example, FCurve parameters return the instance of the FCurve while Boolean parameters return either true or false.

To retrieve a value from an underlying parameter, use the PPG object, which is a global variable in the context of a property page's Logic section. The PPG object allows you to access a parameter, which you can use in turn to get the value of the parameter.

Tip

The long form of such a call would look like this:

PPG.Inspected(0).Parameter( "MyPC" ).Value;

The shortcut would look like this:

PPG.MyPC.Value;

For example, say we created a string parameter called DaisyChain and we want to log the parameter value every time it is changed. Here are the highlights of the script:

// Create the underlying parameters (eg., under the _Define callback)
var oCusProp = in_Context.Source
oCusProp.AddParameter3( "DaisyChain", siString, "Wheelbarrow6" );

// <snip>

// Create the property page layout (eg., under the _DefineLayout callback)
var oPPGLayout = in_Context.Source
oPPGLayout.AddItem( "DaisyChain" );

// <snip>

// Event handler must be attached to logic
function DaisyChain_OnChanged() {
	LogMessage( PPG.DaisyChain.Value );
}

Changing the Layout

Each control but the row control is accessible by name from PPGLayout object and generally has some UI component, such as a label or a width. You can enumerate over all the controls in the layout or by accessing a control directly by name (using PPGLayout.Item).

Having access to each control gives you access to their attributes, which is what gives you the control over their look and ... uh ... layout. But the types of attributes are quite diverse. For example, some attributes control the height, width and general style of their controls, whereas others determine whether to interactively update Softimage or not. Some attributes specify the location of bitmaps to display on controls. For a complete listing of item attributes that you can use, see the beginning of the section on Setting Control Attributes.

To set an attribute on a control, use the PPGItem.SetAttribute method. SetAttribute takes two arguments: the name of the attribute to set and the value to use. How you get the PPGItem object depends on which stage of the developement process you are in: when you are defining the layout, you can get a pointer to the item as you create it; in Logic, you need to use the PPG (global) object to get the PPGLayout and from there you can get a PPGItem object.

Important

If you change the layout through the Logic section of the property page, don't forget to update the onscreen layout using the PPG.Refresh method!

For example, say we want to create a bitmap control that could be interactively changed to another image when the user clicks a button. Here are the highlights of the script:

// Create the underlying parameters (eg., inside the Define callback)
var oCusProp = in_Context.Source
oCusProp.AddParameter3( "CompanyLogo", siString );

// <snip>

// Create the property page layout (eg., under the _DefineLayout callback)
var oPPGLayout = in_Context.Source

// Need to set up the location of the bitmap image when layout is defined
var oItem = oPPGLayout.AddItem( "CompanyLogo", "", siControlBitmap );
oItem.SetAttribute( siUIFilePath, "C:\temp\images\pauper.bmp" );
oPPGLayout.AddButton( "ChgImg", "Change Image" );

// <snip>

// Event handler must be attached to logic
function ChgImg_OnClicked() 
{
	// Get a pointer to the control as a PPGItem
	var oCtrl = PPG.PPGLayout.Item( "CompanyLogo" );
	if ( oCtrl.GetAttribute(siUIFilePath) == "C:\temp\images\pauper.bmp" ) {
		oCtrl.SetAttribute( siUIFilePath, "C:\temp\images\prince.bmp" );
	} else {
		oCtrl.SetAttribute( siUIFilePath, "C:\temp\images\pauper.bmp" );
	}

	// Finish by refreshing the layout
	PPG.Refresh();
}

Adding Parameters

You can also add, remove or redefine parameters on the custom property set while the property page is being inspected. The PPG object (which is always available inside the callbacks defined for the Logic section) gives you access to the underlying custom property through the PPG.Inspected property which returns a CustomProperty object.

Note

If you remove a parameter that is associated to a layout control, the control simply does not appear when you refresh the layout. Likewise, if you add a new parameter and you want it to appear on the property page, you need to update the layout.

The PPG object gives you access to the associated layout through the PPG.PPGLayout property which returns a PPGLayout object.

For example, this is a sample of a self-installing plug-in which can add a string field on the fly (when the user clicks the AddField button), complete with a logic (although admittedly weak functionality):

function MyProperty_AddField_OnClicked() 
{
	// Get the CustomProperty and PPGLayout objects
	var oCusProp = PPG.Inspected(0);
	var oLayout = PPG.PPGLayout;

	// Add a new string parameter to the CustomProperty
	sNewName = "Item_" + oLayout.Count.toString();
	oCusProp.AddParameter3( sNewName, siString );

	// Add a new string control to the PPGLayout with logic
	oLayout.AddItem( sNewName );
	oLayout.Logic = oLayout.Logic.toString()
			+ "function " + sNewName + "_OnChanged() {\n"
			+ "    Application.LogMessage( PPG." + sNewName + ".Value );\n"
			+ "}";


	// Redraw the page
	PPG.Refresh();
}