ExamplesParameterUserData

UserData Conventions

UserData is a means of collecting arbitrary information attached to a Parameter. Each Parameter has a userData() method which will retrieve it's CompoundObject. We try to document the various uses of user data in the relevant Cortex headers. As it may be overwhelming to locate all of the existing userData conventions, we have categorized them below.

Each line indicates a series of keys into CompoundObjects, followed by the TypedData expected, and finally a brief description of the intended purpose.

i.e.

["key"]["anotherKey"]["usefulness"] --> FloatData - This is how I'm intended to be used

would correspond to this python code the user data on this StringParameter:

IECore.StringParameter(
    name = "myStringParameter",
    description = "what my parameter does",
    defaultValue = "",
    userData = { 'key' : { 'anotherKey' : { 'usefullness' : IECore.FloatData( 0.64 ) } } }
)

Note that in reality, each of those dictionaries is a CompoundObject.

Some userData is generic (although it may only be currently used in specific libraries), while other userData is application specific, in which case the first key should always be the application name (see the Maya section).

General

["updateCount"] --> IntData - Hacky hint at how many times the parameter value has changed
["acceptsMotionSamples"] --> BoolData - Causes the DelightProceduralCacheCmd to provide 1 value per time sample, stored in an ObjectVector when putting procedurals in ribs
["parser"]["flagless"] --> StringVectorData - flagless parameters are parsed in the order they are specified in the data element
["parser"]["serialise"] --> BoolData - Should the parameter be serialised by the parser?
["UI"]["visible"] --> BoolData - Should the parameter show up in the UI?
["UI"]["locked"] --> BoolData - Should the parameter be changeable or not?
["UI"]["update"] --> BoolData - Should the UI update when the parameter value changes?
["UI"]["label"] --> StringData - The UI label for the parameter. Defaults to a UI-ified version of the parameter name
["UI"]["collapsable"] --> BoolData - Is the parameter UI collapsable?
["UI"]["collapsed"] --> BoolData - Should the groups instantiated for CompoundParameters be collapsed?
["UI"]["buttonLabel"] --> StringData - Defines the label to use for an Operate button
['UI']['typeHint'] --> StringData - A type hint to decide which Parameter UI is used
["UI"]["classNameFilter"] --> StringData - This will restrict display of the classes a user can choose in a Class/ClassVector Parameter to those matching the supplied glob matched string.
['UI']['draggable'] --> BoolData - Is the parameter UI draggable?
["UI"]["autoExpandDepth"] --> IntData - The number of levels of the CompoundParameter UI that should expand automatically
["UI"]["fileDialogKey"] --> StringData - A key, used in the 'recent items' history mechanism of the fileDialog. This allows diferent parameters to remeber their own path by specifying different keys.
["UI"]["fileDialog"]["saveMode"] --> BoolData - Determines if the FileDialog is for reading or writing a file
["UI"]["defaultPath"] --> StringData - The default filesystem path for the parameter
["UI"]["obeyDefaultPath"] --> BoolData - Should filesystem dialogs begin at the defaultPath or at their current location
["UI"]["acceptsProceduralObjectName"] --> BoolData - Causes the UI to add menu items for putting the name of selected procedural components into the parameter
["UI"]["acceptsProceduralObjectNames"] --> BoolData - Causes the UI to add menu items for putting the names of selected procedural components into the parameter
["UI"]["acceptsNodeName"] --> BoolData - Causes the UI to add menu items for setting the parameter value from the name of a node
["UI"]["acceptsNodeNames"] --> BoolData - Causes the UI to add menu items for setting the parameter value from the names of nodes
["UI"]["acceptedNodeTypes"] --> StringVectorData - The types of nodes available in the menus described above.
["UI"]["acceptedNodeNameFormat"] --> StringData - "partial" or "full" to specify whether the shortest unique or longest node name is used by the menus described above.
["UI"]["acceptsCoordinateSystemName"] --> BoolData - Causes menu items to be created to set the parameter value to the name of a coordinate system generated by a procedural.
["UI"]["icon"] --> StringData - The name of the icon for the parameter (without extension)
["UI"]["defaultChildIcon"] --> StringData - The name of the default icon for the parameter's children (without extension)
["UI"]["defaultChildLabel"] --> StringData - The default label for the parameter's children?
["UI"]["classVectorParameterPreHeader"] --> StringData - Should the parameter be drawn before the unfold arrow in the UI header for the class when held in a ClassVectorParameter.
["UI"]["classVectorParameterHeader"] --> StringData - Should the parameter be drawn after the icon in the UI header for the class when held in a ClassVectorParameter.
['UI']['copyPaste'] --> BoolData - Is copy/paste enabled for the parameter?
["UI"]["visibleFields"] --> StringData - Which of the fields in a TransformationMatrixParameter should be drawn in the UI. \see TransformationMatrixParameterUI.py
["UI"]["showResult"] --> BoolData -  Should the result be displayed to the user with a UI?
["UI"]["showCompletionMessage"] --> BoolData - Shows a message dialog confirming the completion of the operation (for lengthy Ops).
["UI"]["saveResult"] --> BoolData - Gives the user the option to save the Op result object into a file
["UI"]["autoRun"] --> BoolData - The Op is executed automatically if it's parameters are validated
["UI"]["multiLine"] --> BoolData - Should the text based parameters use multi lined UI fields?
["UI"]["password"] --> BoolData - Should the StringParameter UI mask the value with asterisks?
["UI"]["closeAfterExecution"] --> BoolData - Should the UI window die after the Op is executed

Specific

Manipulators

["UI"]["manipTypeHint"] --> StringData - Sets the manipulatorTypeHint
["UI"]["manipLabel"] --> StringData - Draws this label underneath the constraint switch
["UI"]["box3ManipSpace"] --> StringData - Defines the space of the Box manipulator. Valid values are "world" or "object"
["UI"]["manipulatorBox"] --> Box3fData - A box to be drawn by the TransformationMatrixParameter manipulator.
["UI"]["disableManip"] --> BoolData - Should ManipulatorContext skip this parameter?

Maya Specific

["maya"]["keyable"] --> BoolData - Is the parameter keyable?
["maya"]["channelBox"] --> BoolData - Should the parameter be in the channel box?
["maya"]["defaultConnection"] --> StringData - the default connection for this parameter plug (i.e. "time1.outTime" )
["maya"]["defaultExpression"] --> StringData - the default expression for this parameter plug
["maya"]["storable"] --> BoolData - Is the parameter storable?
["maya"]["valueProvider"]["nodeName"] --> StringData - StringParameter value will be the name of this node
["maya"]["valueProvider"]["connectedNodeName"] --> StringData - StringParameter value will be the name of the connected node
["maya"]["valueProvider"]["setMembers"] --> StringData - StringVectorParameter value will be the names of the members of the connected set
["maya"]["useGeometryCombiner"] --> BoolData - Should the geometry combiner be used?

Nuke Specific

["nuke"]["defaultExpression"] --> StringData - the default expression for this parameter's knob