Purpose

This module allows to filter the items of an ItemModel by their attribute values.

Usage

Enter a filtering expression in Filter Expression and connect the ItemModel to be filtered to the inItemModel input.

Details

The output ItemModel is continuously updated to reflect changes to the input ItemModel, so items may appear in or vanish from the output ItemModel if their attribute values change.

To correctly update the child indicator of items this filter will also retrieve the children of an item that a consumer attached to the output did not request; this may be of importance for source ItemModels that create child items on demand. You may want to use the Filter Mode DirectMatchOrHasChildren in this case, which avoids this behavior, but does not update the child indicator before the item is expanded.

Windows

Default Panel

../../../Modules/Controls/MLABMLItemModelSupport/mhelp/Images/Screenshots/ItemModelItemFilter._default.png

Input Fields

inItemModel

name: inItemModel, type: AbstractItemModel(MLBase)

Takes the ItemModel to be filtered.

For accessing this object via scripting see the Scripting Reference: MLAbstractItemModelWrapper.

Output Fields

outItemModel

name: outItemModel, type: AbstractItemModel(MLBase)

Contains the filtered ItemModel. This will be the input ItemModel if no filter expression was given.

For accessing this object via scripting see the Scripting Reference: MLAbstractItemModelWrapper.

Parameter Fields

Visible Fields

Filter Mode

name: filterMode, type: Enum, default: DirectMatch

This field dictates how the filter expression is applied.

Values:

Title Name Description
Direct Match DirectMatch Only items where the filter expression matches are displayed.
Direct Match Or Has Children DirectMatchOrHasChildren Only items where the filter expression matches or that might have children (irrespective of the fact if they are filtered or not) are displayed. The child indicator is only updated if the item is expanded, i.e. child items of the source model are not retrieved beforehand.
Check Recursively CheckRecursively

Only items where the filter expression matches on itself or one of its descendants are displayed.

This mode might be slow for great tree depths.

Filter Expression

name: filterExpression, type: String

A simple expression that can reference attributes of the model. If the expression returns true (or non-zero, or a non-empty string) for an item of the ItemModel, the item is passed through to the output ItemModel.

This uses the same expressions parser as used for the visibleOn and dependsOn tags of the MDL, so you can use the same constructs that are allowed there, like comparison and numerical operators, regular expressions, min, max, and cond functions. Attribute names directly represent the value of this attribute for the current item (upper and lower case characters are distinguished). There is also a pseudo attribute named depth that gives the depth of the item in the item tree: Top-level items have a depth of 1, their children a depth 2, and so on.

The expression is re-parsed whenever the input ItemModel is replaced, because the set of attributes may change then. The Expression Ok flag is updated to indicate if the expression could be parsed cleanly.

Expression Ok

name: expressionOk, type: Bool, persistent: no

This flag indicates if the Filter Expression could be parsed cleanly. This is also updated every time the input ItemModel is replaced.