pymel.core.general.addAttr

addAttr(*args, **kwargs)

This command is used to add a dynamic attribute to a node or nodes. Either the longName or the shortName or both must be specified. If neither a dataType nor an attributeType is specified, a double attribute will be added. The dataType flag can be specified more than once indicating that any of the supplied types will be accepted (logical-or). To add a non- double attribute the following criteria can be used to determine whether the dataType or the attributeType flag is appropriate. Some types, such as double3can use either. In these cases the -dtflag should be used when you only wish to access the data as an atomic entity (eg. you never want to access the three individual values that make up a double3). In general it is best to use the -atin these cases for maximum flexibility. In most cases the -dtversion will not display in the attribute editor as it is an atomic type and you are not allowed to change individual parts of it. All attributes flagged as “(compound)” below or the compound attribute itself are not actually added to the node until all of the children are defined (using the “-p” flag to set their parent to the compound being created). See the EXAMPLES section for more details. Type of attributeFlag and argument to useboolean-at bool32 bit integer-at long16 bit integer- at short8 bit integer-at bytechar-at charenum-at enum (specify the enum names using the enumName flag)float-at “float” (use quotes since float is a mel keyword)double-at doubleangle value-at doubleAnglelinear value-at doubleLinearstring-dt “string” (use quotes since string is a mel keyword)array of strings-dt stringArraycompound-at compoundmessage (no data)-at messagetime-at time4x4 double matrix-dt “matrix” (use quotes since matrix is a mel keyword)4x4 float matrix-at fltMatrixreflectance-dt reflectanceRGBreflectance (compound)-at reflectancespectrum-dt spectrumRGBspectrum (compound)-at spectrum2 floats-dt float22 floats (compound)-at float23 floats-dt float33 floats (compound)-at float32 doubles-dt double22 doubles (compound)-at double23 doubles-dt double33 doubles (compound)-at double32 32-bit integers-dt long22 32-bit integers (compound)-at long23 32-bit integers-dt long33 32-bit integers (compound)-at long32 16-bit integers-dt short22 16-bit integers (compound)-at short23 16-bit integers-dt short33 16-bit integers (compound)-at short3array of doubles-dt doubleArrayarray of floats-dt floatArrayarray of 32-bit ints-dt Int32Arrayarray of vectors-dt vectorArraynurbs curve-dt nurbsCurvenurbs surface-dt nurbsSurfacepolygonal mesh-dt meshlattice-dt latticearray of double 4D points-dt pointArrayIn query mode, return type is based on queried flag.

Modifications:
  • allow python types to be passed to set -at type

    str string float double int long bool bool Vector double3

  • when querying dataType, the dataType is no longer returned as a list

  • when editing hasMinValue, hasMaxValue, hasSoftMinValue, or hasSoftMaxValue the passed boolean value was ignored and the command instead behaved as a toggle. The behavior is now more intuitive:

    >>> addAttr('persp', ln='test', at='double', k=1)
    >>> addAttr('persp.test', query=1, hasMaxValue=True)
    False
    >>> addAttr('persp.test', edit=1, hasMaxValue=False)
    >>> addAttr('persp.test', query=1, hasMaxValue=True)
    False
    >>> addAttr('persp.test', edit=1, hasMaxValue=True)
    >>> addAttr('persp.test', query=1, hasMaxValue=True)
    True
    
Flags:
Long name (short name) Argument Types Properties
attributeType (at) unicode ../../../_images/create.gif ../../../_images/query.gif
 

Specifies the attribute type, see above table for more details. Note that the attribute types “float”, “matrix” and “string” are also MEL keywords and must be enclosed in quotes.

binaryTag (bt) unicode ../../../_images/create.gif ../../../_images/query.gif
 
This flag is obsolete and does not do anything any more
cachedInternally (ci) bool ../../../_images/create.gif ../../../_images/query.gif
 
Whether or not attribute data is cached internally in the node. This flag is currently not supported (it will always be set to a default value of true).
category (ct) unicode ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 

An attribute category is a string associated with the attribute to identify it. (e.g. the name of a plugin that created the attribute, version information, etc.) Any attribute can be associated with an arbitrary number of categories however categories can not be removed once associated.

dataType (dt) unicode ../../../_images/create.gif ../../../_images/query.gif
 
Specifies the data type. See “setAttr” for more information on data type names.
defaultValue (dv) float ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Specifies the default value for the attribute (can only be used for numeric attributes).
enumName (en) unicode ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 

Flag used to specify the ui names corresponding to the enum values. The specified string should contain a colon-separated list of the names, with optional values. If values are not specified, they will treated as sequential integers starting with 0. For example: -enumName “A:B:C” would produce options: A,B,C with values of 0,1,2; -enumName “zero:one:two:thousand=1000” would produce four options with values 0,1,2,1000; and -enumName “solo=1:triplet=3:quintet=5” would produce three options with values 1,3,5. (Note that there is a current limitation of the Channel Box that will sometimes incorrectly display an enumerated attribute’s pull-down menu. Extra menu items can appear that represent the numbers inbetween non-sequential option values. To avoid this limitation, specify sequential values for the options of any enumerated attributes that will appear in the Channel Box. For example: “solo=1:triplet=2:quintet=3”.)

exists (ex) bool ../../../_images/create.gif ../../../_images/query.gif
 

Returns true if the attribute queried is a user-added, dynamic attribute; false if not.Flag can appear in Create mode of commandFlag can have multiple arguments, passed either as a tuple or a list.

fromPlugin (fp) bool ../../../_images/create.gif ../../../_images/query.gif
 

Was the attribute originally created by a plugin? Normally set automatically when the API call is made - only added here to support storing it in a file independently from the creating plugin.

hasMaxValue (hxv) bool ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Flag indicating whether an attribute has a maximum value. (can only be used for numeric attributes).
hasMinValue (hnv) bool ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Flag indicating whether an attribute has a minimum value. (can only be used for numeric attributes).
hasSoftMaxValue (hsx) bool ../../../_images/create.gif ../../../_images/query.gif
 
Flag indicating whether a numeric attribute has a soft maximum.
hasSoftMinValue (hsn) bool ../../../_images/create.gif ../../../_images/query.gif
 
Flag indicating whether a numeric attribute has a soft minimum.
hidden (h) bool ../../../_images/create.gif ../../../_images/query.gif
 
Will this attribute be hidden from the UI?
indexMatters (im) bool ../../../_images/create.gif ../../../_images/query.gif
 
Sets whether an index must be used when connecting to this multi-attribute. Setting indexMatters to false forces the attribute to non-readable.
internalSet (internalSet) bool ../../../_images/create.gif ../../../_images/query.gif
 
Whether or not the internal cached value is set when this attribute value is changed. This is an internal flag used for updating UI elements.
keyable (k) bool ../../../_images/create.gif ../../../_images/query.gif
 
Is the attribute keyable by default?
longName (ln) unicode ../../../_images/create.gif ../../../_images/query.gif
 
Sets the long name of the attribute.
maxValue (max) float ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Specifies the maximum value for the attribute (can only be used for numeric attributes).
minValue (min) float ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Specifies the minimum value for the attribute (can only be used for numeric attributes).
multi (m) bool ../../../_images/create.gif ../../../_images/query.gif
 
Makes the new attribute a multi-attribute.
niceName (nn) unicode ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 

Sets the nice name of the attribute for display in the UI. Setting the attribute’s nice name to a non-empty string overrides the default behaviour of looking up the nice name from Maya’s string catalog. (Use the MEL commands “attributeNiceName” and “attributeQuery -niceName” to lookup an attribute’s nice name in the catalog.)

numberOfChildren (nc) int ../../../_images/create.gif ../../../_images/query.gif
 
How many children will the new attribute have?
parent (p) unicode ../../../_images/create.gif ../../../_images/query.gif
 
Attribute that is to be the new attribute’s parent.
readable (r) bool ../../../_images/create.gif ../../../_images/query.gif
 
Can outgoing connections be made from this attribute?
shortName (sn) unicode ../../../_images/create.gif ../../../_images/query.gif
 
Sets the short name of the attribute.
softMaxValue (smx) float ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Soft maximum, valid for numeric attributes only. Specifies the upper default limit used in sliders for this attribute.
softMinValue (smn) float ../../../_images/create.gif ../../../_images/query.gif ../../../_images/edit.gif
 
Soft minimum, valid for numeric attributes only. Specifies the upper default limit used in sliders for this attribute.
storable (s) bool ../../../_images/create.gif ../../../_images/query.gif
 
Can the attribute be stored out to a file?
usedAsColor (uac) bool ../../../_images/create.gif ../../../_images/query.gif
 

Is the attribute to be used as a color definition? Must have 3 DOUBLE or 3 FLOAT children to use this flag. The attribute type “-at” should be “double3” or “float3” as appropriate. It can also be used to less effect with data types “-dt” as “double3” or “float3” as well but some parts of the code do not support this alternative. The special attribute types/data “spectrum” and “reflectance” also support the color flag and on them it is set by default.

usedAsFilename (uaf) bool ../../../_images/create.gif ../../../_images/query.gif
 
Is the attribute to be treated as a filename definition? This flag is only supported on attributes with data type “-dt” of “string”.
writable (w) bool ../../../_images/create.gif ../../../_images/query.gif
 
Can incoming connections be made to this attribute?

Derived from mel command maya.cmds.addAttr

Example:

import pymel.core as pm

pm.sphere( name='earth' )
# Result: [nt.Transform(u'earth'), nt.MakeNurbSphere(u'makeNurbSphere1')] #
# Add an attribute named ms/mass with a default value of 1 and a
# minimum value of 0.001 and a maximum of 10000.
#
pm.addAttr( shortName='ms', longName='mass', defaultValue=1.0, minValue=0.001, maxValue=10000 )
# Add a multi attribute named ff/forcefield of type double3.
#
pm.addAttr( shortName='ff', longName='forcefield', dataType='double3', multi=True )
# Add a compound attribute named sampson with children homeboy, midge,
# damien, elizabeth, and sweetpea of varying types
#
pm.addAttr( longName='sampson', numberOfChildren=5, attributeType='compound' )
pm.addAttr( longName='homeboy', attributeType='matrix', parent='sampson' )
pm.addAttr( longName='midge', attributeType='message', parent='sampson' )
pm.addAttr( longName='damien', attributeType='double', parent='sampson' )
pm.addAttr( longName='elizabeth', attributeType='double', parent='sampson' )
pm.addAttr( longName='sweetpea', attributeType='double', parent='sampson' )
# To add an attribute that is to be interpreted as a color the
# following attribute group must be used.
#
# Note that the word "float" must be in quotations since it is a
# MEL keyword.
#
pm.addAttr( longName='rainbow', usedAsColor=True, attributeType='float3' )
pm.addAttr( longName='redBow', attributeType='float', parent='rainbow' )
pm.addAttr( longName='greenBow', attributeType='float', parent='rainbow' )
pm.addAttr( longName='blueBow', attributeType='float', parent='rainbow' )
# Other legal attribute types that can be interpreted as colors need
# not specify the "-usedAsColor" flag as it will be assumed.  These
# include "-attributeType spectrum", "-attributeType reflectance",
# "-dataType spectrumRGB", and "-dataType reflectanceRGB".
#
pm.addAttr( longName='implColor', dataType='spectrumRGB' )
pm.addAttr( '.implColor', query=True, usedAsColor=True )
# Result: True #
# Add a double3 attribute named sanders with children bess, les and wes
#
pm.addAttr( longName='sanders', attributeType='double3' )
pm.addAttr( longName='bess', attributeType='double', parent='sanders' )
pm.addAttr( longName='les', attributeType='double', parent='sanders' )
pm.addAttr( longName='wes', attributeType='double', parent='sanders' )

Previous topic

pymel.core.general.about

Next topic

pymel.core.general.addExtension

Core

Core Modules

Other Modules

This Page