Custom Operator Wizard

To create a custom operator using the SDK Operator Wizard

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

   In the Tools Development Environment layout, you can click the Plug-ins tab to switch to the Plug-in Manager view.

2. Do one of the following:

   • To create the operator in the User location, click FileNewOperator.

   • To create the operator 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 NewOperator.

   The operator wizard appears.

3. In the Operator Name box, type a name for the operator.

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

   The wizard automatically replaces spaces with underscores.

4. By default, the plug-in name is based on the operator name. If you want to change the plug-in name, type a different name in the Plug-in Name box.

   Note that if you change the operator name later, the wizard overwrites your plug-in name with a default generated name.

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

6. Click the Connections tab, and then specify the output and input connection ports.

   The wizard makes it easy for you to set up your connections through the UI and then modify them to suit your needs after the code is generated. For example, if you wanted to create a weight map generator operator by blending two other weight maps:

   • Pick a weight map node as the output.

   • Pick the two weight maps to be blended as input. You can also specify a variable Name to use for your input ports in the Update function.

     

     The wizard will generate code that looks something like the following snippet. Notice that these connections we set up on the Connection tab actually appear in the callback for the command to apply the operator, and in the operator's Update callback.

     function ApplyMyWtMapOp_Execute(  )
     {
     
     	// ...
     	var newOp = XSIFactory.CreateObject("MyWtMapOp");
     	newOp.AddOutputPort("torus.polymsh.cls.Point.Weight_Map");
     	newOp.AddInputPort("torus.polymsh.cls.Point.Weight_Map1");
     	newOp.AddInputPort("torus.polymsh.cls.Point.Weight_Map2");
     	newOp.Connect();
     	return newOp;
     }
     
     function MyWtMapOp_Update( ctxt )
     {
     	var inWM1 = ctxt.GetInputValue(0);
     	var inWM2 = ctxt.GetInputValue(1);
     
     	// ...
     	output = ctxt.OutputTarget;
     	return true;
     }
     

   • It is recommended to make the port connections generic so that your operator can be reused in other contexts. For example, you can try to establish a connection based on what objects are selected or launch a picking session:

     function ApplyMyOp_Execute(  )
     {
     	// ...
     	var newOp = XSIFactory.CreateObject("MyOp");
     
     	// Launch a picking session to get the connections
     	var btn, outWMap;
     	var collWMaps = new ActiveXObject("XSI.Collection");
     	do {
     		var rtn = PickObject( "Pick the weight map to write to", "Pick the weight maps to blend" );
     		btn = rtn.Value("ButtonPressed");
     		switch (btn) {
     			case 1 :
     				outWMap = rtn.Value("PickedElement");
     				break;
     			case 2 :
     				collWMaps.Add( rtn.Value("PickedElement") );
     				break;
     			default :
     		}
     	} while (btn)
     	
     	// Extract the input weight maps from the XSICollection
     	var inWMap1 = collWMaps(0);
     	var inWMap2 = collWMaps(1);
     	
     	// Test what we was picked & if it's ok hook up the ports. 
     	if ( 
     			outWMap.IsClassOf(siClusterPropertyID) && 
     			inWMap1.IsClassOf(siClusterPropertyID) && 
     			inWMap2.IsClassOf(siClusterPropertyID) ) 
     	{
     	} else {
     		Application.LogMessage( "Could not connect all ports (one or more specified "
     			+ "objects were invalid connections for this operator). Please try again." );
     		return false;
     	}
     	
     	newOp.AddOutputPort(outWMap.Kinematics.Global);
     	newOp.AddInputPort(inWMap1.Kinematics.Global);
     	newOp.AddInputPort(inWMap2.Kinematics.Global);
     	newOp.Connect();
     	return newOp;
     }
     

     Tip

     For an example of converting wizard-generated code into a truly dynamic operator, see Using the Wizard to Create Dynamic Operators.

7. Click the Code tab. Here you can control which callbacks the wizard will generate, such as callbacks to define the command for applying the operator, and callbacks to allow you to store and clean per-instance user data.

8. If you want to add parameters or buttons to the operator's property page, you can define each parameter using the options in the Define Item group on the Add Parameter tab and then click AddItem at the bottom of the page to add the parameter as defined by these options to the operator's property page.

   Tip

   To remove a parameter, click on the row's handle (the dark leftmost column) and then click Delete Selected.

9. Once you have defined your parameters, click the Layout (Optional) tab to provide some layout on the property page. Here are some of the customization features available through the wizard:

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

   • Tweak the parameters's order of appearance on the property page.

   Note

   The wizard can get you started with customizing the layout for your operator's property page, but there are other possibilities available by modifying the DefineLayout, such as:

   • providing drop down lists

   • hiding animation divots

   • changing the sizes of your controls

   • providing special widgets (for example, a file browser)

   • logic and event routines, etc.

   For more information on the kinds of controls you can add and customize, see Interacting with the User.

10. When you are finished setting up all connections, code, parameters, etc., click Generate Operator to generate the custom operator.

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

    Important

    Don't forget that any changes you make manually to the code will be overwritten if you ask the wizard to regenerate the code, so it is a good idea to make sure you are completely ready to begin coding before clicking Generate Operator.

Notes

• You can turn on operator debugging in an existing plug-in. Open the plug-in in a text editor or script editor, right-click in the editing pane, point to Tools, and then click Enable Operator Debugging. Extra operator information will now be logged to history.

• You can save wizard presets for types of operators that you frequently want to generate.

• The wizard creates a model named SDK_Wizards, and under that model puts a custom property for each operator you create. You can open the wizard for an operator by double-clicking the corresponding custom property.

Plug-in Info

The Plug-in Info tab allows you to enter the information required to generate the XSILoadPlugin function, which registers the plug-in items such as operators and commands with Softimage.

Connections

The Connections tab allows you to define the input and output connection ports for the operator.

Code

The Code tab allows you to specify what code the wizard will generate in some very specific cases.

Add Parameter

This section allows you to define the custom parameters for the operator. These settings tell the wizard how and what code to generate. From there you can customize it further and add extra functionality as desired. These settings basically correspond to the way the generated code calls the XSIFactory.CreateParamDef or Factory::CreateParamDef method.

Layout (Optional)

This section allows you to arrange how the parameters appear on the operator's property page. Much of the functionality of the PPGLayout or PPGLayout object is provided here.

A typical workflow includes:

• adding parameters to be displayed from the Parameters box

• tweaking the order of appearance using the Layout button controls

• adding special layout control brackets from Groupings (such as tabs, groups and rows)

• assigning parameters by moving them in and out of these control brackets

Layout

This box represents the set of parameters that will appear on the operator's property page. The order in which parameters are arranged in this list (and eventually on the property page) can be controlled using the Up and Down button controls underneath the list box.

The Layout box represents Groupings as blocks delimited by labeled brackets inside which parameters can appear. The parameters that appear inside these blocks are considered to be assigned to that control. For example, given the following Layout listing, you can see that Param1 and Param2 will appear inside the Wavy group and Param3 will appear inside the Thick group:

The Remove button allows you to remove either Groupings controls or parameters from the list.

To remove a parameter from the Layout list

1. Click the parameter you want to remove in the Layout list.

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

To remove a grouping control from the Layout list

1. Click either bracket of the control you want to remove.

2. Click Remove. The grouping control brackets disappear from the Layout list leaving the parameters intact. The parameters are now nested under the next highest control.

   For example, if the parameters were nested inside a Row on a Tab and you remove the row, the parameters now appear directly inside the Tab.

Tab "Wavy" {
	Param1
	Param2
}
Tab "Thick" {
	Param3
}