itemFilter

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

Synopsis

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

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
-exists(-ex)
Returns true|false depending upon whether the specified object exists. Other flags are ignored.
-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.
-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.
-clearByType(-cbt)
This flag will clear any existing typeNames associated with this filter.
-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.
-clearByBin(-cbk)
This flag will clear any existing bins associated with this filter.
-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 ) Note that if -secondScript is also used, it will always take precidence.
-secondScript(-ss)	string
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
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(-in)	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.
-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.
-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.
-text(-t)	string
Defines an annotation string to be stored with the filter
-category(-cat)	string
A string for categorizing the filter.
-classification(-cls)	string
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)
Returns an array of all item filters with classification "builtIn".
-listUserFilters(-luf)
Returns an array of all item filters with classification "user".
-listOtherFilters(-lof)
Returns an array of all item filters with classification "other".
-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 be used more than once in a command.

MEL examples

//    Create a filter that will pass all transforms.
//
string $transforms = `itemFilter -byType transform`;

//    Create a filter that will pass all spot lights.
//
string $spotLights = `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.
//
string $unionFilter = `itemFilter -union $transforms $spotLights`;
string $spotLightsAndTransforms = `itemFilter
    -byType transform -byType spotLight`;

//    Create a filter that lists all objects beginning with the
//    letter "a".
//
string $aFilter = `itemFilter -byName "a*"`;

//    Create a filter that lists only transforms and spot lights
//    that begin with the letter "a".
//
string $intersectionFilter = `itemFilter
    -intersect $spotLightsAndTransforms $aFilter`;

//    Delete the filters when done with them.
//
delete $transforms $spotLights $aFilter;
delete $unionFilter $intersectionFilter;