Creating a Self-Installing Property

You can use a wizard to generate the code for a self-installing plug-in that contains a custom property. In addition to generating the skeleton code for the plug-in and the property, the wizard can also generate the code required to add the property to a menu.

If you add a property to a menu, you get a menu command that adds the property to the first object in the selection list.

To create a self-installing property

Click FilePlug-ins to open the Plug-in Manager.

Tip In the Tools Development Environment layout, click the Plug-ins tab to switch to the Plug-in Manager view.
Do one of the following:
- To create the property in the User location, click FileNewProperty.
- To create the property in a different location (such as a workgroup or an Add-on directory), expand the location in the Plug-in Tree, right-click the Plugins folder and click NewProperty.
The custom property wizard appears.
In the Property Name box, type a name for the property.

The first character in a property name should be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.
In the Script Language list, click the language you want to generate.
If you want to add the property to a menu, then in the Add to Menu list, click a menu anchor point.

The wizard generates a menu command that adds the property to the first object in the selection list. The property name is that text that appears on the menu.
Add parameters to the property. How?
Define the layout of the parameters on the property page. How?

This is optional. You can always do this by editing the generated DefineLayout callback.
Click Generate Property.

If you selected a scripting language, the wizard loads the plug-in, adds the property to the scene root, and opens the property page.

If you generated C++, you'll have to build the plug-in first.

Adding Parameters

The Parameters tab generates the body of the Define callback using a series of CustomProperty.AddParameter or CustomProperty::AddParameter calls.

To add a parameter

In the ParamType list, click the type of parameter you want to add.

ParamType	Variant Type	Default Control
Text	siString	siControlString
Boolean	siBool	siControlCheck
Integer	siInt4	siControlNumber
Small Integer	siUByte
Floating Point Number	siFloat
Double Precision Number	siDouble
Color (with Alpha)	Color or Color	siControlRGBA
Grid Control	Grid or Grid	siControlGrid
FCurve	FCurve or FCurve	siControlFCurve
Button	Button	siControlButton

If you want to have a different type of control (for example, a list box, combo box, or synoptic widget), add a parameter of the required type. After you generate the property, you can edit the DefineLayout callback to use a different control for the parameter.

In the Name/Label box, type a name for the parameter.

If you add the parameter to the layout, this name is used as the default label for the control associated with the parameter. You can specify a different label by editing the call to PPGLayout.AddItem or PPGLayout::AddItem in the generated DefineLayout callback function.

The first character in a parameter name should be a letter. Subsequent characters can be letters, numbers, or underscore (_) characters.

Parameter names are used to name callback functions (such as MyProperty_MyParameter_OnChanged), so parameter names must be valid identifiers in your chosen programming language.

The wizard replaces any spaces in the name with underscores.
Set the property attributes"
- Read Only Select this check box to make the parameter read only. If the parameter is added to the layout, the control will be disabled.
- Animatable Select this check box to allow users to animate the control. The parameter will have an animation divot on the property page.
- Callback By default, the wizard generates callbacks for parameters (OnClicked for buttons, and OnChanged for all other parameters). If you do not want a callback for a parameter, clear the Callback check box.
- Default Default value for the parameter, if applicable.
- Value Range Minimum and maximum values for numeric parameters.
- UI Value Range Minimum and maximum values that can be set using the slider (for numeric parameters). By default, the UI Value Range is the same as the Value Range. To change the UI Value Range, select the UIRange check box.
Click Add Item to add the parameter to the Parameters grid.
- Except for the name and type, you can edit parameter attributes in the grid. Click a cell and type the new attribute value.
- To delete a parameter, click the shaded cell at the start of a row (the row should be highlighted a light green), and then click Delete Selected.

Defining the Layout

The Layout tab allows you to add controls to the property page and arrange the controls using rows, groups, and tabs. The generated DefineLayout callback adds the default control type for each parameter you add to the layout.

Parameter Type	Default Control Type
Text	siControlString
Boolean	siControlCheck
Integer	siControlNumber
Small Integer
Floating Point Number
Double Precision Number
Color (with Alpha)	siControlRGBA
Grid Control	siControlGrid
FCurve	siControlFCurve
Button	siControlButton

To add different controls (such as a combo box or a set of radio buttons), you'll have to edit the generated DefineLayout callback. For example, if you want a combo box, add a string or numeric parameter to the layout and generate the code. Then, in the generated DefineLayout callback, replace the generated call to PPGLayout.AddItem or PPGLayout::AddItem:

oLayout.AddItem("Param3");

with the code for a combo box:

var aSnippets = [ "enumerator", 0, "for-in", 1, "switch", 2 ];
oLayout.AddEnumControl( "Param3", aSnippets, "Snippets", siControlCombo );

By default, the wizard uses the parameter name as the label for the control. If you want to include spaces in the label, you have to edit the generated PPGLayout.AddItem or PPGLayout::AddItem calls to look like this:

oLayout.AddItem("Property_Name", "Property Name");

The first argument to PPGLayout.AddItem or PPGLayout::AddItem is the parameter name, and the second is the label.

If you want to do things like set the LabelMinPixels and LabelPercentages, you'll also have to edit the generated code.

To add controls to the property page

In the Parameters list, click a parameter, and then click Add.

By default, parameters are added to the layout in the order you add them. But if you select a parameter in the Layout list, then the next time you add a parameter it is inserted above the selected parameter.

You can reorder the Layout list using the Up and Down buttons.

To add a row

Click Add Row.

An empty row is added to the Layout list. If a parameter is selected in the Layout list, the row is added above the selected parameter.
In the Layout list, click one of the parameters you want to put in the row, and then click Up (or Down) until the parameter is in the row.

Do the same for the other parameters you want to put in the row.

To add a group

Under Groupings, in the Name box, type a name for the group.
Click Add Group.

An empty group is added to the Layout list. If a parameter is selected in the Layout list, the group is added above the selected parameter.
To move a parameter into the group, click the parameter and then click either Up (if the parameter is below the group in the Layout list) or Down (if the parameter is above the group in the Layout list).

Similarily, to move a parameter out of a group, click the parameter and then click Up or Down until the parameter moves out of the group.

To add a tab

Under Groupings, in the Name box, type a name for the tab.

If you want a group without a name (label), you have to edit the generated call to PPGLayout.AddGroup or PPGLayout::AddGroup in the DefineLayout callback.
Click Add Tab.

The first time you add a tab, all parameters already in the Layout list are put on that tab.
To add another tab, type a name for the tab in the Name box, and then (before you click Add Tab) do one of the following:
- Add more parameters to the layout, and then, in the Layout list, click one of the parameters you just added.
- Use the Up and Down buttons to move some parameters off the tab.
- Click a tab (the Tab "name" { line)in the Layout list. This will result in an empty tab being added.

Except where otherwise noted, this work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported License