itemFilter

Go to: Synopsis. Return value. Flags. Python examples.

Synopsis

itemFilter( [string] , [byBin=string], [byName=string], [byScript=string], [byType=string], [category=string], [classification=string], [clearByBin=boolean], [clearByType=boolean], [difference=[string, string]], [exists=boolean], [intersect=[string, string]], [listBuiltInFilters=boolean], [listOtherFilters=boolean], [listUserFilters=boolean], [negate=boolean], [parent=string], [pythonModule=string], [secondScript=string], [text=string], [union=[string, string]], [uniqueNodeNames=boolean])

Note: Strings representing object names and arguments must be separated by commas. This is not depicted in the synopsis.

itemFilter is undoable, queryable, and editable.

Return value

In query mode, return type is based on queried flag.

Flags

Long name (short name)	Argument types	Properties
byBin(bk)	string
The filter will only pass items whose bin list contains the given string as a bin name. This is a multi-use flag. If more than one occurance of this flag is used in a single command, the filter will accept a node if it matches at least one of the given bins (in other words, a union or logical or of all given bins.
byName(bn)	string
The filter will only pass items whose names match the given regular expression string. This string can contain the special characters * and ?. '?' matches any one character, and '*' matches any substring.
byScript(bs)	string
The filter will run a MEL script named by the given string on each item name. Items will pass the filter if the script returns a non-zero value. The script name string must be the name of a proc whose signature is: global proc int procName( string $name ) or def procName(*args, **keywordArgs) if -pym/pythonModule is specified. Note that if -secondScript is also used, it will always take precedence.
byType(bt)	string
The filter will only pass items whose typeName matches the given string. The typeName of an object can be found using the nodeType command. This is a multi-use flag. If more than one occurance of this flag is used in a single command, the filter will accept a node if it matches at least one of the given types (in other words, a union or logical or of all given types.
category(cat)	string
A string for categorizing the filter.
classification(cls)	string
Indicates whether the filter is a built-in or user filter. The string argument must be either "builtIn" or "user". The "other" classification is deprecated. Use "user" instead. Filters will not be deleted by a file new, and filter nodes will be hidden from the UI (ex: Attribute Editor, Hypergraph etc) and will not be accessible from the command-line.
clearByBin(cbk)	boolean
This flag will clear any existing bins associated with this filter.
clearByType(cbt)	boolean
This flag will clear any existing typeNames associated with this filter.
difference(di)	[string, string]
The filter will consist of the set difference of two other filters, whose names are the given strings. Items will pass this filter if and only if they pass the first filter but not the second filter.
exists(ex)	boolean
Returns true|false depending upon whether the specified object exists. Other flags are ignored.
intersect(intersect)	[string, string]
The filter will consist of the intersection of two other filters, whose names are the given strings. Items will pass this filter if and only if they pass both of the contained filters.
listBuiltInFilters(lbf)	boolean
Returns an array of all item filters with classification "builtIn".
listOtherFilters(lof)	boolean
The "other" classification is deprecated. Use "user" instead. Returns an array of all item filters with classification "other".
listUserFilters(luf)	boolean
Returns an array of all item filters with classification "user".
negate(neg)	boolean
This flag can be used to cause the filter to invert itself, and reverse what passes and what fails.
parent(p)	string
Optional. If specified, the filter's life-span is linked to that of the parent. When the parent goes out of scope, so does the filter. If not specified, the filter will exist until explicitly deleted.
pythonModule(pym)	string
Treat -bs/byScript and -ss/secondScript as Python functions located in the specified module.
secondScript(ss)	string
Cannot be used in conjunction with the -bs flag. The second script is for filtering whole lists at once, rather than individually. Its signature must be: global proc string[] procName( string[] $name ) or def procName(*args, **keywordArgs) if -pym/pythonModule is specified. It should take in a list of items, and return a filtered list of items.
text(t)	string
Defines an annotation string to be stored with the filter
union(un)	[string, string]
The filter will consist of the union of two other filters, whose names are the given strings. Items will pass this filter if they pass at least one of the contained filters.
uniqueNodeNames(unn)	boolean
Returns unique node names to script filters so there are no naming conflicts.

Flag can appear in Create mode of command	Flag can appear in Edit mode of command
Flag can appear in Query mode of command	Flag can have multiple arguments, passed either as a tuple or a list.

Python examples

import maya.cmds as cmds

#    Create a filter that will pass all transforms.
#
transforms = cmds.itemFilter(byType='transform')

#    Create a filter that will pass all spot lights.
#
spotLights = cmds.itemFilter(byType='spotLight')

#    There are two ways to create a filter that passes both
#    spot lights and transforms.  You can create a filter
#    that is a union of the previous two or just specify
#    both object types on one filter.
#
unionFilter = cmds.itemFilter(union=(transforms, spotLights))
spotLightsAndTransforms = cmds.itemFilter(byType=('transform','spotLight'))

#    Create a filter that lists all objects beginning with the
#    letter "a".
#
aFilter = cmds.itemFilter(byName='a*')

#    Create a filter that lists only transforms and spot lights
#    that begin with the letter "a".
#
intersectionFilter = cmds.itemFilter( intersect=(spotLightsAndTransforms, aFilter) )

#    Delete the filters when done with them.
#
cmds.delete( transforms, spotLights, aFilter )
cmds.delete( unionFilter, intersectionFilter )