Purpose

The module :module:this` allows for filtering the items of an object derived from ml.AbstractItemModel 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. Consider using the Filter Mode DirectMatchOrHasChildren in this case, as is avoids this behavior, though it 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

Defines 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 (regardless of whether they are filtered or not) are displayed. The child indicator updates only when the item is expanded; in other words, child items of the source model are not retrieved beforehand.
Check Recursively CheckRecursively

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

This mode may be slow for trees with significant depth.

Filter Expression

name: filterExpression, type: String

Sets 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 in the ItemModel, the item is passed through to the output ItemModel.

This uses the same expression parser as the one used for the visibleOn and dependsOn tags of the MDL, allowing you to apply the same constructs permitted there, such as comparison and numerical operators, regular expressions, min, max, and cond functions. Attribute names directly represent the value of the attribute for the current item (uppercase and lowercase characters are distinguished). Additionally, there is a pseudo-attribute called depth that indicates the item’s depth in the item tree: Top-level items have a depth of 1, their children a depth of 2, and so forth.

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

Expression Ok

name: expressionOk, type: Bool, persistent: no

Shows whether the Filter Expression could be parsed successfully. This is also updated whenever the input ItemModel is replaced.