Identifying a Choice of Interest

You can identify choices of interest by using filters. Typically the object owning a filter is a sink used by a subscribing DTC, but you can apply filters to collections and other objects. This help topic covers the following subjects:

• Ways to filter choices
  
  
• Determining a choice's type
  
  
• Evaluating text and description
  
  
• Evaluating additional criteria

Ways to Filter Choices

You can filter choices in the following ways:

• ChoiceSink object: Typically, a DTC subscribes to a Choice object by adding a ChoiceSink object to the ChoiceSinks collection. The ChoiceSink object contains a ChoiceFilter object that specifies which Choice objects are interesting. The first Choice object that matches the ChoiceFilter binds to the ChoiceSink and notifies the DTC.
  
  
• DTC: A DTC can create a ChoiceFilter object that filters the choices that it accepts. Typically Choices are visible to any DTCs that follow the publisher on the page. So a filter that a subscribing DTC applies typically filters those choices published by DTCs which appear before it. Once filtered, the choices are not visible to any DTC which appears after the owner of the filter. You can change the Sequential property of a choice to control when it is available. For more information, see Controlling Choice Availability.
  
  
• Choices Collection: 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 only those Choice objects which match the ChoiceFilter.

Choice filter properties, including the Sequential property, are set initially to no-value and the properties cannot be read, but they can be set. Once a property is set to a value, you can set it back to the no-value state by calling the Reset method on the Choice filter. You can filter on a subset of the properties exposed by a choice.

Determining a Choice's Type

A subscribing DTC uses a sink with a filter to specify choices to subscribe to. A choice is selected based primarily on its Type property. By specifying a Type in the filter on a sink, a subscribing DTC eliminates processing of choices it can't use. If the DTC is interested in more than one type, it creates a sink collection.

Tip   Prefixing the choice's type with the ProgID of the publishing DTC can help you plan DTC interaction and prevent unwanted interaction. This convention is especially helpful if you are working with multiple DTC developers.

For example, the following code creates a filter that accepts Choices of type "Fruit." This filter accepts all choices that are of type "Fruit" regardless of the text or description.

Dim mySink As ChoiceSink
Set mySink = ChoiceSinks.AddChoiceSink
With myFilter.ChoiceFilter 
.Type = "Fruit"
End With

Evaluating Text and Description

A Choice can publish more information than just its type, and a subscriber can filter on that information as well. For example, a filter can specify Description and Text properties of a choice, as well as any of the Tags associated with the choice.

Dim mySink As ChoiceSink
Set mySink = ChoiceSinks.AddChoiceSink
With myFilter.ChoiceFilter 
.Type = "Fruit"
.Text = "grapes"
.Desc = "Grapes"
End With

Evaluating Additional Criteria

In some cases, your DTC may require additional criteria for evaluating a choice's usefulness. The publishing DTC can add a tag or tags collection to a choice. Tags can vary based on what your DTC requires.

For example, the following code creates a filter that accepts Choices of type "Fruit" which have a description of "Grapes" and accepts a tag named "Variety" with a value of "Seedless."

Dim mySink As ChoiceSink
Set mySink = ChoiceSinks.AddChoiceSink
With myFilter.ChoiceFilter 
.Type = "Fruit"
.Desc = "Grapes"
.AddTag("Variety", "Seedless")
End With

The Tags collection is empty initially, which is equivalent to having a no-value state for all possible tags. You can create a tag value by calling the AddTag method. You can individually reset tags to the no-value state by calling the DeleteTag or DeleteTags method.