A Choices Walkthrough in Visual Basic

This walkthrough describes how to build two DTCs that share information using the Choices interface. For simplicity, one DTC acts solely as a publisher and shows how a choice can be published. The other DTC is the subscriber that shows how a choice can be read and used by another DTC. Keep in mind that the ultimate purpose of the DTCs is to generate run-time text for use in a Web page.

The publishing DTC user interface has a label and a drop-down list. When a user chooses a value from the drop-down list, the DTC publishes that value as a choice to a design-time control site and generates run-time text showing the selected value. The subscribing DTC user interface has a label. The DTC uses a ChoiceSink to get the information published by the other DTC and sets the caption for that label based on the value of the choice that was published. This inline user interface is used in the sample; for your DTCs you should use property pages instead.

For working DTCs, see VBSample.ocx provided with this SDK. For more information, read Sharing Information Between DTCs or the Choices Reference.

Publishing Choices in a DTC

The main tasks for publishing choices are:

Create an ActiveX Control project.
Implement the DesignTimeControlSite.
Publish a static choice.
Persist the choice value as a property.
Specify the run-time text that your DTC generates.
Make and Register your DTC.
Test Your DTC in Visual InterDev.

Create an ActiveX Control Project

To begin an ActiveX control project

In Visual Basic, create an ActiveX Control project.
Tip Rename the project and the user control. Although renaming is not required, changing the names makes it easier to find the control when adding it to the Visual InterDev toolbox.
Add references to the DTC SDK type libraries.

Detail From the Project menu, choose References. In the References dialog box, locate and select the following libraries. By default, these libraries are located in the Include directory provided with the SDK.

File Name	Reference Display Name
DTC60.tlb	Microsoft DTC 60 Type Library
webdc.tlb	Microsoft Web Design-time Control Type Library

Create the control's user interface.
Note When creating a DTC, use property pages instead of inline user interface for setting a DTC's properties. An inline user interface is the graphical representation of the DTC within the hosting document such as a form or other object with controls that accept user input. Although Visual InterDev 6.0 supports inline user interface, this is not a guarantee that all DTC hosts are required to support it now or in the future.

Implement the DesignTimeControlSite

An IDesignTimeControlSite works with a DTC to act as a clearinghouse for choices. Through its objects and methods, you can store and access information published and subscribed to by multiple DTCs. The interface site points to the methods for choice objects. A Choice object stores a value that a DTC publishes so that the site is able to pass it to other DTCs. The hosting editor sets the DesignTimeControl property when the DTC is created.

To implement the property

In the Code window, implement the choices interface and the text interface for DTCs.
```
Implements IProvideRuntimeText
Implements IDesignTimeControl
```
Declare and initialize variables for the site object.
```
Dim MySite As IDesignTimeControlSite
```

Add the following private properties for the site.

Note If you use the Code window's textboxes to automatically generate the properties, you may want to change the variable from "RHS" to "Site" for clarity and to match the sample.

Private Property Set IDesignTimeControl_DesignTimeControlSite(ByVal Site As DTC60.IDesignTimeControlSite)
End Property

Private Property Get IDesignTimeControl_DesignTimeControlSite() As DTC60.IDesignTimeControlSite
End Property

Set the site.

Private Property Set IDesignTimeControl_DesignTimeControlSite(ByVal Site As DTC60.IDesignTimeControlSite)
Set MySite = Site
End Property

Now you are ready to add the user interface and publish a choice.

Publish a Static Choice

After you have specified a site, you can publish a choice. To see a sample containing a publishing DTC, see the Fruit sample, SourceDTC.

On the form, add a label and a combo box to create the user interface.
Change the caption for the label. For example, the sample has "Choose a Fruit" as the label's caption.
In the Code window, populate the combo box with alternatives to publish with your Choice object.
For example, if you were creating the Fruit sample, you would enter the following:
```
Private Sub UserControl_Initialize()
With Combo1
    .AddItem "Apple"
    .AddItem "Banana"
    .AddItem "Cherry"
    .AddItem "Durien"
End With
End Sub
```
Declare a choice in the General Declarations.
```
Dim MyChoice As Choice
```
Create a choice in the Property Set statement of the IDesignTimeControlSite interface.
Note The type property of the choice object is the key value that subscribing DTCs use to determine whether or not to use choice. In addition, you can add tags to a choice and subscribing DTCs can also use those for evaluating a choice.
```
Private Property Set IDesignTimeControl_DesignTimeControlSite(ByVal Site As DTC60.IDesignTimeControlSite)
Set MySite = Site
Set MyChoice = MySite.Choices.AddChoice(Nothing, Combo1.Text, "MyChoiceType")
End Property
```
Add stub functions for the remaining methods in the DesignTimeControl interface.
Note Visual Basic requires that all of the methods of the interface be mentioned in the code whether they have code specified or not. The Code window indicates methods you have added in boldface. You need to add those that are not in boldface in order to compile.
In the sample, those methods are:
- DesignTimeControlSet
- OnChoiceChange
- OnChoiceConflict
- OnGetChoices
- OnHostingChange
- OnRebind

Now that the choice has been published, you can make sure that your DTC is able to recall the value for the choice.

Persist the Choice Value as a Property

Your DTC needs to persist the choice it was publishing so that same choice appears in the combo box when the page is reopened. If your run-time text depends on a choice, you need to persist that value for reloading even if the Choice object no longer exists.

To persist the choice value in a property bag

Specify a property to store the value of the choice.

Public Property Get MyStorageProp() As String
MyStorageProp = Combo1.Text
End Property

Public Property Let MyStorageProp(ByVal New_MyStorageProp As String)
Combo1.Text = New_MyStorageProp
PropertyChanged "MyStorageProp"
End Property

Implement a property bag to store the new property.

Private Sub UserControl_ReadProperties(MyPropBag As PropertyBag)
Dim sRead As String
Dim s As String
Dim I As Integer

sRead = MyPropBag.ReadProperty("MyStorageProp", "")
For i=0 To Combo1.ListCount-1
If Combo1.List(I) = sRead Then
Combo1.ListIndex = I
Exit For
End If
Next
End Sub

Write the property value to storage when the document is saved.
```
Private Sub UserControl_WriteProperties(MyPropBag As PropertyBag)
    Call MyPropBag.WriteProperty("MyStorageProp", Combo1.Text, "")
End Sub
```
The properties and a property bag store the choice values for passing between DTCs. When you bind to a choice you need to persist that value for reloading the information even if the choice no longer exists.
Specify a click event for the combo box that updates the text of the choice and notifies the editor that the property has changed.

Private Sub Combo1_Click()

If Not MyChoice Is Nothing Then

MyChoice.Description = Combo1.Text

PropertyChanged "MyStorageProp"

End If

End Sub

Now that your DTC has its user interface and published choice defined, you can specify the run-time text that the DTC inserts into the document.

Specify the Run-time Text

The final output of the DTC is the run-time text that you want inserted into the Web page. In Visual Basic, implement the GetRuntimeText method of the IProvideRuntimeText interface.

To specify the run-time output

Specify the text string your DTC inserts into a document such as a Web page.

Private Function IProvideRuntimeText_GetRuntimeText() As String
Dim s As String
s = "<B>Publishing the choice " & Combo1.text _
& "!</B>"
IProvideRuntimeText_GetRuntimeText = s
End Function

Make and Register Your DTC

Before you can test the DTC in a hosting editor such as Visual InterDev, you need to register it. There are two ways to register a DTC created in Visual Basic. The procedure below describes the recommended way for testing your DTC. For more information, see Registering a Visual Basic Control for Testing. For the recommended procedure for registering a DTC ready for deployment and distribution, see Distributing a DTC.

To register your DTC

Make your .ocx.

How to From the File menu, choose Make. In the Make Project dialog box, specify the directory you want the .ocx to reside in, then choose OK.

Run Regsvr32 on the .ocx you just created.

How to From the Windows taskbar, choose Start and then Run. Type Regsvr32 and the path to the .ocx. A message box appears when the .ocx is registered.

Run Regsvrdc for the control.

How to From the Windows taskbar, choose Start and then Run. Type Regsvrdc followed by the ProgID of the control.

For example, you would enter the following if you were using this procedure on the SrcDTC in the VBSample project.

Regsvrdc vbsample.SourceDTC

Test Your DTC

You are now ready to test the code you've written by using the DTC inside Visual InterDev6.0. If you make changes to the DTC after viewing it in Visual InterDev, you need to close and then reopen Visual InterDev before testing the modified control.

To test your DTC code

In Visual InterDev 6.0, create or open a Web page.
Add your control to the toolbox, then drag it to the Web page in the Source tab of the editor.
Note To add the control, right-click the toolbox and choose Customize Toolbox. In the dialog box, choose the ActiveX Controls tab and locate your DTC.
In the editor, test the functionality of your DTC.
Verify the DTC's run-time output by right-clicking the control and choosing Show Run-Time Text.
Note If you don't see the run-time text update after you change a value, click on another area of the page to update the run-time text view.
Save the Web page and open it in the Web browser.

For more information about testing, see Testing a DTC's Output.

Subscribing to Choices in a DTC

For the purposes of this walkthrough, the subscribing DTC has a single label for displaying the published choice. Like the publishing DTC, the subscribing DTC requires a site. However, only the subscribing DTC requires a ChoiceSink.

The main tasks for creating the subscribing DTC are:

Add a user control to your ActiveX Control project. This is similar to the first DTC. You need to implement the DTC and the Choice interfaces, implement a design-time control site for working with choices, and add the user interface.
Create a ChoiceSink object for binding to the static choice you are interested in.
Handle changes to the published choice.
Finish and test the DTC. The procedures for this are the same as for the publishing DTC. Specify the run-time text that your DTC generates, make and register the control, then test Your DTC in Visual InterDev.

For more information about subscribing, see Subscribing to a Choice.

Add a User Control to Your ActiveX Control Project

The following procedure assumes you have already created your ActiveX control project and the publishing DTC as described previously.

Add the user control to the project and add a label to it.

Implement the DTC and Choice interfaces in the control.

Implements IProvideRuntimeText
Implements IDesignTimeControl

Dim MySite As IDesignTimeControlSite

Private Property Set IDesignTimeControl_DesignTimeControlSite(ByVal Site As DTC60.IDesignTimeControlSite)
Set MySite = Site
End Property

Private Property Get IDesignTimeControl_DesignTimeControlSite() As DTC60.IDesignTimeControlSite
If Not MySite Is Nothing Then
Set IDesignTimeControl_DesignTimeControlSite = MySite
End IF
End Property

Create a ChoiceSink

The site object uses the ChoiceSink object to evaluate which published choices are of interest to the subscribing DTC. For more information about using a sink, see Identifying a Choice of Interest

In the Property Set statement, create a ChoiceSink to detect the choice the DTC subscribes to.
Warning The ChoiceSink type property must match the published Choice's type property. If the two are not the same, the subscribing DTC does not evaluate it as a usable choice.
```
Dim MyChoiceSink As ChoiceSink
Private Property Set IDesignTimeControl_DesignTimeControlSite(ByVal Site As DTC60.IDesignTimeControlSite)
Set MySite = Site
Set MyChoiceSink = MySite.ChoiceSinks.AddChoiceSink("MyChoiceType")
End Property
```

Handle Changes to the Published Choice

Add an event handler to display the published value and handle changes made to the published choice.

Private Sub IDesignTimeControl_OnChoiceChange(ByVal cs As ChoiceSink, ByVal Change As DTC60.dtcChoiceChange)
If cs Is MyChoiceSink Then
    Dim ch As Choice
    Set ch = MyChoiceSink.BoundChoice
    If Not ch Is Nothing Then
        Label1.Caption = ch.Description
    Else
        Label1.Caption = ""
    End If
End If
End Sub

Create stub functions for the methods in the DesignTimeControl interface that are not implemented.
In the sample, those methods as displayed in the Code window text box are:
- DesigntimeControlSet
- OnChoiceConflict
- OnGetChoices
- OnHostingChange
- OnRebind

Create a property to persist values to display in the label even when a choice is not available.

Public Property Get SubscribedValue() As String
SubscribedValue = Label1.Caption
End Property

Public Property Let SubscribedValue(ByVal New_SubscribedValue As String)
    Label1.Caption = New_SubscribedValue
    PropertyChanged "SubscribedValue"
End Property

Private Sub UserControl_ReadProperties(MyPropBag As PropertyBag)
Label1.Caption = MyPropBag.ReadProperty("SubscribedValue", "")
End Sub

Private Sub UserControl_WriteProperties(MyPropBag As PropertyBag)
Call MyPropBag.WriteProperty("SubscribedValue", Label1.Caption)
End Sub

Finish and Test Your DTC

The final steps for creating and testing your subscribing DTC are the same as those for your publishing DTC. They are summarized here using the sample subscribing DTC. For more information about testing a DTC, see Testing a DTC's Output.

In the Code window, implement the GetRuntimeText method and specify the text string your DTC inserts into a document such as a Web page.

Private Function IProvideRuntimeText_GetRuntimeText() As String
   Dim s As String
   s = "<P><B>The Web author selected: " + Label1.Caption + ".in the publishing DTC.</B></P>"
   IProvideRuntimeText_GetRuntimeText = s
End Function

Compile your .OCX file using the Make command.
In Windows, register your .OCX by running regsvr32 on it and regsvrdc on the new control.
In Visual InterDev 6.0, create or open a Web page and add the publishing DTC.

Warning If you make changes to the publishing DTC after viewing it in Visual InterDev, you need to reopen Visual InterDev before testing the modified control. Otherwise the old version of the control is used by Visual InterDev.

Add your new control to the toolbox, then drag it to the Web page in the Source tab of the editor.

Note To add the control, right-click the toolbox and choose Customize Toolbox. In the dialog box, choose the Design Time Controls tab and locate your DTC.

In the editor, test the functionality of your publishing and subscribing DTCs.
Verify the DTC's run-time output by right-clicking the control and choosing Show Run-Time Text.
Note If you don't see the run-time text updated after you change a value, click on another area of the page to update the run-time text view.
Save the Web page and open it in the Web browser.

You can verify that choices are being published by adding the Choice Inspector to the page. For more information about using this tool, see Viewing Available Choices.