ChoiceFilter Object

Represents filtering criteria that can be applied to a Choices Collection to produce filtered Choices collections.

Syntax

ChoiceFilter

Remarks

Use ChoiceFilter objects in the following ways:

• A DTC object subscribes to Choice objects by adding a ChoiceSink object to the ChoiceSinks collection. The Choice sink contains a ChoiceFilter object that specifies which Choice objects are relevant. The first available Choice object that matches the ChoiceFilter will bind to the Choice sink and notify the DTC object. This is the typical way that DTC objects subscribe to choices.
  
  
• A DTC object can specify a ChoiceFilter object that filters the choices that pass through it. Choices introduced by DTC objects, which appear before the owner of the filter, can be filtered out, so that they are not visible to DTC objects which appear after the owner of the filter, and vice versa.
  
  
• The set of Choice objects in a Choices collection can be filtered by passing a ChoiceFilter object to the Filter method of the Choices collection. The Filter method returns a new Choices collection containing Choice objects which match the ChoiceFilter.
  
  
• Initially, all the properties on the Choice filter including the Sequential property are set to no-value. All the string-valued properties distinguish between an empty string and one with no value. Typically, an empty string is a legal value that must be matched.
  
  
• The special no-value state indicates that any value for the property is acceptable. You can write to a property in this state but you can't read it. Once set to a value, you can only return the property to the no-value state by calling the Reset method on the Choice filter. The Reset method sets all properties back to the no-value state.

All tags in the Tags collection are initially in a no-value state. Tags can be set to a value by calling the AddTag method, and they can be individually reset to the no-value state by calling the DeleteTag or DeleteTags methods.

Note   Filtering is only supported on a subset of the properties exposed by Choice objects: type, text, sequential, and tags.

Note that PopUp choices never match a ChoiceFilter that has its Text property set.

See also   Identifying a Choice of Interest