Navigation: ABC Library Reference > ViewManager > ViewManager Methods >====== SetFilter (add, change, or remove active filter)  ====== |    |
SetFilter( expression [, id ] ), VIRTUAL
| SetFilter | Specifies a filter for the active sort order. |
| expression | A string constant, variable, EQUATE, or expression that contains a FILTER expression. See FILTER in the Language Reference for more information. If expression is null (' ') , setFilter deletes any existing filter with same id . |
| id | A string constant, variable, EQUATE, or expression that uniquely identifies (and prioritizes) the filter so you can apply multiple filter conditions, and so you can replace or remove filter conditions with subsequent calls to SetFilter. If omitted, the filter gets a default id so that subsequent calls to SetFilter with no id replace the filter expression set by prior calls to SetFilter with no id. |
The SetFilter method specifies a filter for the active sort order. When the filter is applied, the view only includes those elements whose expression evaluates to true.
The id parameter lets you specify multiple filter expressions or replace a specific expression by its id. If you set several expressions, each with a unique id, then all those expressions must evaluate to true to include an item in the result set. The id parameter must begin with a number.
The ViewManager evaluates the expressions in id order (highest number first, lowest number last), so it is efficient to prioritize expressions most likely to fail; for example:
MyView.SetFilter('TaxPayer=True','1Tax') !low priority expression
MyView.SetFilter('LotteryWinner=True','9Lot') !high priority expression
!evaluates as: (LotteryWinner=True) AND (TaxPayer=True)
The ApplyFilter and ApplyRange methods apply the active sort order's filter. The SetSort method sets the active sort order.
Implementation:
The ViewManager uses the id to indicate the priority of the expression. The priority is implemented by sorting the list of filter expressions by the id. The id is truncated after 30 characters. If omitted, id defaults to '5 Standard' which specifies a medium priority filter that is replaced by any subsequent calls to SetFilter with id omitted (or '5 Standard') and with the same active sort order.
Each call to SetFilter with a unique id parameter adds to the filter expression for the active sort order. Multiple expressions added in this fashion are joined with the boolean AND operator.
The SetFilter method adds the filter id and expression to the Order property.
Example:
MyView.AddSortOrder(ORD:ByOrder) !order no. sort (1)
MyView.SetFilter('(ORD:OrdNo=CUST:OrdNo)','1OrderNo') !filter on OrderNo
MyView.SetFilter('(ORD:Date='&TODAY()&')','1Date') !AND on date. Date test applied
!first because it sorts first
MyView.AddSortOrder(ORD:ByName) !customer name sort (2)
MyView.SetFilter('CUST:Name[1]=A') !filter on cust name
!program code
MyView.SetSort(2) !sort by customer name
MyView.SetFilter('CUST:Name[1]=J') !new filter on cust name
!replaces prior name filter
See Also: AddSortOrder, Order