Adds a new user parameter to the collection.
"userParameters_var" is a variable referencing a UserParameters object. |
"userParameters_var" is a variable referencing a UserParameters object. |
| Type | Description |
| UserParameter | Returns the newly created UserParameter or null if the creation failed. |
| Name | Type | Description |
| name | string | The name of the parameter. This is the name shown in the parameters dialog |
| value | ValueInput | ValueInput object that specifies the value of the parameter. If the ValueInput was created using a real, the value will be interpreted using the internal unit for the unit type specified by the "units" argument. For example, if the ValueInput was created using the real value 5 and the input to the "units" argument is any valid length unit, the value will be interpreted as 5 centimeters since centimeters is the internal unit for lengths. If the "units" argument is a valid angle unit the value will be interpreted as 5 radians. If the ValueInput was created using a string, the string is used as-is for the expression of the parameter. For value parameters, this means if there are units as part of the string, it must evaluate to the same unit type as that specified by the "units" argument and if no units are specified it will use the current default units specified for the current document. For example, if the ValueInput was created with the string "5 in", then the "units" argument must define any valid length so they are compatible. If the ValueInput was created with the string "5", any unit type can be used and the result will be 5 of that unit. If the "units" argument is "Text" then a text parameter will be created using the value provided as the expression. For text parameters, the expression must be a valid string literal enclosed in single quotes (e.g. "'Hello Fusion'") or it can be an expression that combines string literals with other text parameters (e.g. "'Length: ' + lengthParam"). An unquoted value like "Hello Fusion" will fail to parse because the tokens are interpreted as symbols rather than literal text. After the parameter has been created, you can use the textValue property on the resulting Parameter object to get or set the plain string value without having to manage the surrounding quotes yourself. When using a ValueInput created using a string, it's the same as creating a parameter in the user-interface. You can specify any valid expression, i.e. "5", "5 in", "5 in / 2", "5 + Length", etc. and you can choose from many different types of units. The only requirement is that the units must match in type. For example, they must both be lengths, or they must both be angles. Boolean ValueInput objects (created via ValueInput.createByBoolean) are not supported by UserParameters.add and attempting to use one will fail. Boolean-like behavior can be approximated by creating a unitless numeric parameter (with an empty string for the "units" argument) using the expressions "true" or "false", which are evaluated as 1 and 0 respectively. |
| units | string | The units to use for the value of the parameter. The use of any of the measurement units will result in the creation of a numeric parameter. The units specified must match the units specified (if any) in the ValueInput object. To create a parameter with no units, you can specify an empty string as the units, which will also create a numeric parameter. To create a text parameter, use "Text" as the unit type; in this case the expression supplied via the ValueInput must be a quoted string literal (see the "value" parameter description for details). A Boolean ValueInput is not supported by this method. |
| comment | string | The comment to display in the parameters dialog. Specify an empty string ("") for no comment |