Custom Primitive Wizard

 
 
 

You can use the Custom Primitive Wizard to generate the basic code for a self-installing plug-in that contains a custom primitive object.

To generate the code for the plug-in using the Custom Primitive Wizard:

  1. Click File Plug-in Manager.

    The Plug-in Manager appears.

  2. Perform one of the following:
    • To create the plug-in in the User location – Select File New Primitive.
    • To create the plug-in 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 select New Primitive.

    The Custom Primitive Wizard appears.

  3. Select the Plugin-Info tab, and type a name for the custom primitive object in the Primitive Name text box.

    The first character in the name must be a letter. Subsequent characters can be letters, numbers, or underscore (_). The wizard automatically replaces spaces in a name with underscores.

  4. Type the name of the plug-in author, for example, your name or the organization name in the Author text box.
  5. Select the correct version of the compiler in the C++ Compiler Version list box. In the Coding Language list box, C++ is selected as the coding language.
    NoteOnly C++ is currently supported as the coding language for the custom primitive object.
  6. Make sure that the location of the generated files as shown in the Output Directory box is correct.
  7. Select the Add Parameter tab to add parameters or buttons to the property page for the custom primitive object. You can define each parameter using the options in the Define Item group, and click Add Item to add the parameter to the property page. See the Adding Parameters section for more information about the Add Parameter tab.
    TipTo remove a parameter, click on the corresponding row handle (the first dark column in the Parameters group), and then click Delete Selected.
  8. Select the Callbacks tab to specify which callbacks must be generated for the plug-in. To select a callback, select the corresponding checkbox.
  9. Select the Layout (Optional) tab to define the layout of the property page. You can do the following:
    • Prevent parameters from appearing on the property page.
    • Assign a parameter to a tab on a property page.
    • Assign a parameter to a group on a property page.
    • Assign a parameter to a row on a property page.
    • Change the parameters's order of appearance in the property page.

    See the Property Page Layout section for more information about the Layout (Optional) tab.

    The wizard creates the basic layout, but you can tweak the property page further using the DefineLayout callback. For more information on the kinds of controls you can add and customize, see Interacting with the User.

  10. Click Generate Code to generate the code for the custom primitive plug-in.

    The generated plug-in is automatically loaded and executed, and the code is loaded into the script editor.

    NoteAny change that you make manually to the code is overwritten if you regenerate the code using the wizard. It is a good practice to make sure that you are ready to begin coding before you click Generate Code.

Adding Parameters

The Add Parameter tab enables you to define the parameters for the Custom Primitive. The wizard uses these settings to determine what code to generate. You can customize the code further and add extra functionality as desired. The following table defines the settings in the Add Parameter tab.

Control Description
ParamType

Specifies the data type for the parameter. Most of these types correspond to actual data types (integer, string, boolean, and others). However, the Button option just adds a button and is not a parameter type.

Depending on the value you choose in this control, some of the other settings in the Add Parameter tab might not be available. For example, value range settings such as Min and Max appear only for parameters with a numerical data type.

Name/Label

Specifies the name for the parameter.

ReadOnly

Specifies whether you can write to the parameter.

Animatable

Specifies whether the parameter can be animated.

Keyable

Specifies whether the parameter is keyable or not.

Default

Specifies the default value to use for the parameter. This setting appears as a text box for the text (string) type, a checkbox for the boolean type, a slider for numeric types, and a color box for the color type. It is not available for FCurves, grid controls, and buttons.

Min

Specifies the lower limit of the parameter. This setting is only available for parameters of numeric type.

Max

Specifies the upper limit of the parameter. This setting is only available for parameters of numeric type.

UIRange

Toggles the availability of the UIMin and UIMax settings that allow you to define the range of values on the parameter's slider bar when the property page is displayed. This option is only available for parameters of numeric type.

Property Page Layout

The Layout (Optional) tab defines the layout of the property page.

The Layout list in the Layout (Optional) tab represents the set of parameters that appear in the property page. You can click Up and Down to change the order in which parameters are arranged in the Layout list (and eventually in the property page). The Layout list represents the groupings as blocks delimited by labeled brackets inside which the parameters can appear as shown in the following figure.

The Parameters list displays all parameters defined for the custom primitive object. By default, all parameters appear in the property page. However, if you add some parameters to the Layout list, then only these parameters are visible in the property page.

To add a parameter to the Layout list:

  1. Click the parameter in the Parameters list

  2. Click Add under the Parameters list.

    Notice that adding parameters to the Layout list does not remove them from the Parameters list.

You can click Remove to remove either groupings or parameters from the Layout group.

To remove a parameter from the Layout list:

  1. Click the parameter in the Layout list.

  2. Click Remove. The parameter disappears from the Layout list (but remains in the Parameters list).

To remove a grouping from the Layout list:

  1. Click either bracket of the group that you want to remove.

  2. Click Remove. The grouping is removed from the Layout list leaving the parameters. The parameters are now nested under the next highest control. For example, if the parameters are nested inside a Row on a Tab and you remove the row, the parameters now appear inside the Tab.

The Groupings area enables you to add tabs, groups and rows to the property page. Each tab or group must be identified by a label which you can specify in the Name text box. You can click the button corresponding to the type of control such as AddTab, AddGroup, or AddRow, and the control brackets appear in the Layout list.

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