Subscribing to a Choice

A DTC can subscribe to Choice objects by notifying the engine about the type of choice objects to evaluate and bind to. More than one DTC can subscribe to any one choice.

This help topic covers the following subjects:

• Subscribing to static choices
  
  
• Subscribing to dynamic choices
  
  
• Responding to changes in choices
  
  
• Canceling a subscription

Subscribing to Static Choices

• To subscribe to a static choice, create a sink using the DTC's site property. To the sink, add a filter to specify which choices the DTC subscribes to. Once created, the sink remains until the DTC is destroyed. For an example, see the Visual Basic Walkthrough or the Visual C++ Walkthrough.
  
  
• After your DTC has subscribed to a choice, the engine handles matching for you. When the engine rebinds and finds a choice that matches the filter on the sink, it does the following:
  • Updates the BoundChoice property of the ChoiceSink with the pointer to the Choice object that matched.
    
    
  • Calls the DTC's OnChoiceChange method and passes the relevant ChoiceSink object.

Static choices remain associated with the publisher throughout the publisher's lifetime.

Your subscribing DTC needs a handler to specify changes to user interface elements and code elements that use the choice information.

Note   Only one Choice object is allowed for each ChoiceSink. If multiple choices match, only the first is bound. To find the set of available choices, your DTC can examine the Choices collection passed to the OnRebind method or call IDesignTimeControlSite::Available Choices. To improve performance, be sure to filter the Choices during the OnRebind method.

Subscribing to Dynamic Choices

Dynamic choices are temporary and exist only as long as a subscriber is bound to them.

To subscribe to a dynamic choice, call the AvailableChoices property on the site to get the current collection of all available choices of all types. To collect these dynamic Choices, rebinds are necessary. For best performance, apply a ChoiceFilter to the engine's collection.

Note   This AvailableChoices property is not available during certain methods, such as the OnRebind method.

Responding to Changes in Choices

Whenever the state of a Bound Choice is changed, the ChoicesEngine notifies the owner of the ChoiceSink that a change has occurred by calling the OnChoiceChange method. This notification applies to changes of all the properties of the Choice interface as well as changes to any of the tags associated with the Choice.

Canceling a Subscription

If for some reason your DTC no longer needs to subscribe to a particular choice, you can call the DeleteChoiceSink method on the sinks collection to delete a sink.

Note   You only need to call this method directly when your DTC still exists but you do not want the sink to exist. The engine automatically calls DeleteChoiceSink when it detects that a DTC has been deleted.