Have you ever needed an extra property on an existing control? I am sure that this situation occurred many times. To solve your problem, you probably sub-classed existing controls. But what if you need to add this same property to all the controls you are using even those you are not using yet? Will you subclass them all?

I have a more suited solution for you that are specifically tailored for that purpose. We are not talking of changing the behaviour of controls here. We simply want to add a property to existing control. You want an example of an existing extender provider? The Tooltip and the Error (see my column on this topic in the February 2003 edition) providers are probably the mostly known extenders.

I am sure you already used them but have you ever asked yourself how you can build your own? Once an extender provider component (notice that it is not a control!) is hosted by a form, all the controls of this form are extended.

Try an existing provider

To be able to really understand what is an extender provider, lets first place one on a form and see how it interacts with the controls. So for this, you need to create a new Windows application project. Drop a couple of different controls (labels, textboxes, buttons, checkboxes, …) on it. Now, add a Tooltip component to this very same form. You will first notice that instead of appearing on the form, the Tooltip provider will appear in the component tray. Now if you look back at the properties of any of the controls you placed on the form, you will notice that a new property has been added. This property is called “ToolTip on ToolTip1”. Whatever the value you type in this property will be displayed at run time in a small yellow box when end users hover the control.

Figure 1: The ToolTip provider in action

Unlike traditional properties, these new properties cannot be accessed by their name. You cannot change the ToolTip property of a button by typing something like this:

Button1.Tooltip = "Something new"

This syntax is not valid and will not compile. Instead, you need to use methods provided by the extender like this:

ToolTip1.SetToolTip(Button1, "Something new")

If you don’t trust me, take a minute to look under the “Windows Form Designer generated code” region. You will see that all the values you typed into the properties dialog are translated to the SetToolTip syntax.

Likewise, to read the value placed in the Tooltip property, you need to use this syntax:

ToolTip1.GetToolTip(Button1)

Notice that each provider exposes different properties. All these properties will be available through the properties window will always be available by code using the ProviderInstanceName.SetXXX or the ProviderInstanceName.GetXXX syntax.

Steps to create an extender provider

Now that we know how an extender provider interacts with our forms and controls, we can start working on our own extender provider. 

The recipe can seem quite cumbersome at first but it is not. Here are the major steps: 

1. Create a class for your extender provider. 
2. Make this class inherits from System.ComponentModel.Component. 
3. Enumerate the list of provided properties through attributes. This list contains the name of the properties and also the type of objects supported by this extender. 
4. Implement the IExtenderProvider interface. 
5. Create a class-level HashTable to hold the values given to your provider. 
6. Define the SetXXX and the GetXXX methods for each property.

Time to demonstrate it

For the demo, we will simply expose a simple description property and display this description somewhere (the ideal place is a status bar – my September 2004 column talked about this control!). This description will also be triggered in an event so the form can react to it and display the description easily.

Step 1 – Create a class

So you first need to add a class. The one catch to this step is that the class needs to be packaged into a separate assembly from the assembly using it. So you normally create a class library project to hold your extender provider (you can add it to the same solution you add before).

So add a project to your current solution (using the Class library template). You can then simply add a class to this new project. I have named my class as MyExtProv.

Step 2 – Inherits from a base class.

You should normally inherit from System.ComponentModel.Component (but in some occasions you may see the extender inheriting from the System.Windows.Forms.Control class).

To inherits, you need to add a line like this:

Public Class MyExtProv
    Inherits System.ComponentModel.Component

If you inherit the Control class, your provider will appear on the form instead of appearing into the component tray.

Step 3 – Enumerate new properties

You must now list all the new properties you will provide. To do this, you need to add attributes to the class declaration like this:

<ProvideProperty("Description", GetType(Component))> _
Public Class MyExtProv

This attribute says that we are providing a property named Description and this property will be available to any objects that are of the Component Type.

If you give a different type argument (Control for example), only objects that are of that type will be extended. So Timer, Menu, ToolTip and other components won’t be extended but Labels, Buttons, TextBoxes and other controls will.

You may get an error at this stage saying that the ProvideProperty type is not defined. To fix this error, you need to import the class defining it:

Imports System.ComponentModel

Step 4 – Implement the IExtenderProvider interface

Your class must now implements a specific interface. The first thing you need to do is to add this line just after the “Inherits” line:

Implements IExtenderProvider

Adding this line, should automatically add the only method declaration required to implements this interface:

Public Function CanExtend(ByVal extendee As Object) As Boolean _
Implements System.ComponentModel.IExtenderProvider.CanExtend

End Function

This method must return a Boolean value telling if the object received in the extendee argument can be extended or not. You can use this method to limit your new properties to specific type only.

In our example, we will simply return a True value to support any component:

Return True

Step 5 – Create a class-level HashTable

The extender provider class needs any kind of storage to keep track of controls of a form and the value you set to the properties. You will mostly want to use a HashTable to do that. This storage needs to be visible to all the members of the class.

At the top of the class, you will find a line like this:

Private ctrlProps As New Hashtable

Step 6 – Define the SetXXX and GetXXX methods

You now need to implement the setter and the getter for all new properties. These 2 methods will use the HashTable you declared at the previous steps. Remember that these methods MUST be named Set and Get followed by the EXACT name of the property you specified at step 3.

Here is the setter:

Public Sub SetDescription(ByVal ctrl As Component, ByVal value As String)
    'To be sure we don't have the Nothing value
    If value Is Nothing Then value = ""

    If value.Length = 0 AndAlso ctrlProps.Contains(ctrl) Then
        'remove the control from the hashtable if its value is deleted
        ctrlProps.Remove(ctrl)
        RemoveHandler CType(ctrl, Control).Enter, _
                    AddressOf ShowDescription

    ElseIf value.Length > 0 Then
        If Not ctrlProps.Contains(ctrl) Then
            If TypeOf ctrl Is Control Then
                AddHandler CType(ctrl, Control).Enter, _
                        AddressOf ShowDescription
            ElseIf TypeOf ctrl Is MenuItem Then
                AddHandler CType(ctrl, MenuItem).Select, _
                        AddressOf ShowDescription
            End If
        End If
        ctrlProps.Item(ctrl) = value
    End If
End Sub

This method will be called each time you set a value through the properties window or when you directly call the SetDescription method. The control (ctrl) and the new description (value) are received as arguments. This method uses the HashTable (ctrlProps) to store the description. You can also see that we are adding a handler on specific event of the controls. This is needed to be able to raise our own event (more on this later).

The getter method is much simpler. It checks the HashTable to return the value previously set:

Public Function GetDescription(ByVal ctrl As Component) As String
    If ctrlProps.Contains(ctrl) Then
        Return ctrlProps(ctrl).ToString
    Else
        Return ""
    End If
End Function

Last step

This step is specific to our extender because this one is triggering an event.

The event needs to be declared at the top of the class like this:

Public Event MyExtProvEvent(ByVal Description As String)

Finally, the setter used the address of ShowDescription that has not been defined yet. This method needs to raise the event:

Private Sub ShowDescription(ByVal sender As Object, ByVal e As System.EventArgs)
    RaiseEvent MyExtProvEvent(GetDescription(CType(sender, Component)))
End Sub

Extender Provider test drive

You are now ready to see your extender provider in action.

To be able to reference your extender from another assembly, the extender needs to be compiled. So go ahead and build the solution (or at least the class library).

In the project you first created (the one containing the form you place a tooltip on), add a reference to your extender assembly (Project->Add Reference…).

Your extender component will now appear into your toolbox. Double-click on it while your form designer is visible to add an instance to your form. If you now look at the properties of any of the controls that are on the form, you should see one named “Description on MyExtProv1”. You see it? It is exactly like the tooltip provider we test first. Set the description of some controls that can get the focus.

Figure 2: Our own description property!

The last thing we need to do is to catch the event sent by the provider to display the description (notice that I am using a simple StatusBar control here):

Private Sub MyExtProv1_MyExtProvEvent(ByVal Description As String) _
 Handles MyExtProv1.MyExtProvEvent
     StatusBar1.Text = Description
 End Sub

You are now ready to run the application. You should see the value you set as the description appearing in the StatusBar when you go from control to control.

Conclusion

I agree that implementing requires some strict guidelines but I am sure you will agree that it is a lot easier then sub classing each and every control to give the same behaviour.

Keep this sample handy. I am sure you will find occasions to use in the near future unless you already found one!

I hope you appreciated the topic and see you next month.