A design-time control can act as a mini-builder for text within a document and work independently from other DTCs. However, you may find that you want your DTCs to be able to communicate their state and share other information in order to present your user with the best functionality.
For example, in the figure below, you can see that the first DTC publishes the fruit name selected in its text box. The second DTC displays the fruit's name. The first DTC is said to publish a choice and the second DTC is said to subscribe to that choice. When the choice in the first DTC changes, the second can change to match it automatically. A single DTC can be both a publisher and a subscriber.
You can accomplish this publish/subscribe relationship using the Choices interfaces provided in this SDK. The remaining sections summarize the following concepts:
Sharing is possible when each DTC is able to communicate with the Choices engine, a central facility for processing information provided by DTCs. DTCs communicate with this facility by making calls to a DesignTimeControlSite and by using choice objects. The facility matches publishing objects and matches them to subscribing objects.
In the picture below, you can see the lines of communication within a document such as a Web page.
The figure provides the overall view of communication of choices on a page. The ChoicesEngine does the work necessary to keep communication going between publishers and subscribers. The ChoicesEngine is an object that is hosted by the application as a service and which knows about all the choice sources and sinks in its scope.
To communicate with the engine, DTCs use the IDesignTimeControlSite interface. Once you have acces to the site, you are able to use a variety of objects and methods to control what information is passed between DTCs and to manipulate the information.
DTCs share information by publishing and subscribing to choice objects. In general terms, when publishing, a DTC implements a site and creates a choice. A choice contains the "payload" information as well as meta-information that the engine uses to match it with subscribers. The payload information is specified through the choice's text and description properties. For example, the payload in the example above is the fruit's name. The meta-information is the choice's type. A choice can also have a set of tags that carries additional information to the document.
Multiple publishers can publish choices of the same type. For example, a project can have several record sets available, all published as choices of type "RecordSet". A report form can populate a drop-down combo box with all the available record sets by creating a sink to request from the engine the choices of the type "RecordSet."
When subscribing, a DTC creates and uses a sink object. The sink identifies acceptable choices by applying a filter that specifies a choice type and (if needed) text, description, or tags specifying additional criteria. The filter matches a choice only if all the criteria are matched.
The engine iterates through the publishers and collects the choices they have published. Next, the engine compares each gathered choice to the filter of each sink. If the filter accepts a choice, the choice is bound to the sink and the owner of the sink is notified of the binding.
When a choice changes, the engine notifies the subscribing sink's owner about the changes. Several sinks can be bound to the same choice. The engine multicasts the changes in the choice to the sinks.
Rebinds may occur synchronously or asynchronously. A synchronous rebind is necessary when the results of the rebind are required immediately. For example, populating a drop-down combo box with a list of the choices available to the user requires a synchronous rebind. An asynchronous rebind typically occurs in idle time. For example, when the state of a Choice is changed, the notifications are posted to the sinks asynchronously because immediate notification typically is not necessary.
Your DTC can trigger a synchronous rebind by getting the AvailableChoices property of the DesignTimeControl interface. If the DTC needs to notify the engine that it has a dynamic choice to publish, it calls the Rebind method of the IDesignTimeControlSite. In this method, the DTC can trigger either a synchronous or asynchronous rebind.
When multiple matches are found for a Choice filter specified by a DTC, choices with lower conversion costs are considered better than choices with higher conversion costs. If no conversion is needed, the cost is implicitly 0. Conversions do not chain. For example, a conversion may be given from type A to type B, and another from type B to type C; but type A cannot necessarily be converted to type C. A specific conversion from A to C must be specified separately.
Conversions are one-way. If two types are interchangeable, you must specify a conversion each way. For example, to say that all choices of type myControl.filename match filters of type myControl.string with a cost of 20, you could write:
mySite.Types.AddConversion "myControl.filename", "myControl.string", 20
This does not imply the converse, that a string will match a filename.
This section covers the following subject areas: