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], [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.

This command creates a named itemFilter object. This object can be attached to selectionConnection objects, or to editors, in order to filter the item lists going through them. Using union, intersection and difference filters, complex composite filters can be created.

Return value

string
string[]

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

Flags

byBin, byName, byScript, byType, category, classification, clearByBin, clearByType, difference, exists, intersect, listBuiltInFilters, listOtherFilters, listUserFilters, negate, parent, secondScript, text, union, uniqueNodeNames
Long name (short name) Argument types Properties
exists(ex) boolean create
Returns true|false depending upon whether the specified object exists. Other flags are ignored.
byName(bn) string createqueryedit
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.
byType(bt) string createqueryeditmultiuse
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.
clearByType(cbt) boolean createedit
This flag will clear any existing typeNames associated with this filter.
byBin(bk) string createqueryeditmultiuse
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.
clearByBin(cbk) boolean createedit
This flag will clear any existing bins associated with this filter.
byScript(bs) string createqueryedit
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 )
Note that if -secondScript is also used, it will always take precidence.
secondScript(ss) string createqueryedit
Can 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 )
It should take in a list of items, and return a filtered list of items.
union(un) [string, string] createqueryedit
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.
intersect(intersect) [string, string] createqueryedit
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.
difference(di) [string, string] createqueryedit
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.
negate(neg) boolean createqueryedit
This flag can be used to cause the filter to invert itself, and reverse what passes and what fails.
parent(p) string createqueryedit
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.
text(t) string createqueryedit
Defines an annotation string to be stored with the filter
category(cat) string createqueryeditmultiuse
A string for categorizing the filter.
classification(cls) string createqueryedit
Internal use only. Indicates whether the filter is a built-in or user filter. The string argument is one of "builtIn" | "user" | "other".
listBuiltInFilters(lbf) boolean query
Returns an array of all item filters with classification "builtIn".
listUserFilters(luf) boolean query
Returns an array of all item filters with classification "user".
listOtherFilters(lof) boolean query
Returns an array of all item filters with classification "other".
uniqueNodeNames(unn) boolean createqueryedit
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 )