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

  1. 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.

  2. 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.

  3. 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.

  4. In the Script Language list, click the language you want to generate.

  5. 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.

  6. Add parameters to the property. How?

  7. 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.

  8. 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

  1. 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.

  2. 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.

  3. 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.

  4. 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

  1. 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.

  2. 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

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

  2. 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.

  3. 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

  1. 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.

  2. Click Add Tab.

    The first time you add a tab, all parameters already in the Layout list are put on that tab.

  3. 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.

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