Smart Tags (Tasks) in your UserControl / Custom control

[NickThissen]

Always wondered how you create the handy little Tasks (often called Smart-Tags) that allow you to change common properties with ease?


Here is an explanation on how to create various types of Smart-Tags, including an example (VS2008).


If you want to add Smart-Tags to your custom control, or your UserControl, you need to create a custom Designer class for that control.

For the purpose of this 'tutorial', I will use a custom control that inherits from the TextBox control, without having any special custom functions. Therefore, it behaves just like any ordinary TextBox. I have called it customTextBox.

Public Class customTextBox
    Inherits TextBox
 
End Class

To even be able to use any Designer functions/methods etc, you first need to add a Reference to System.Design (right-click the solution icon in the Solution Explorer and choose Add Reference..., then choose System.Design in the list).


Now it's time to start on our Designer class. Create a new Class and call it customTextBoxDesigner (or something equally descriptive).

Let's first import a few important namespaces, and make our class inherit from the default ControlDesigner:
(You can also inherit from the ParentControlDesigner for example, which allows your control to Parent other controls, like a Panel, Groupbox etc)

Imports System.Windows.Forms.Design
Imports System.ComponentModel.Design
Imports System.ComponentModel
 
Public Class customTextBoxDesigner
    Inherits ControlDesigner
 
End Class

Now, we need one last class, inheriting from the DesignerActionList. I always find it useful to have this class in the same file as the Designer class, so we can make it Friend instead of Public: you will not need this class outside of the Designer class so making it Friend is sufficient.
Because we are inheriting from the DesignerActionList, this class requires a constructor (Sub New), something Visual Studio will tell you if you forget it.
We will need a reference to our custom control in this last class, so it is useful to be able to pass our control as a reference when we create a New instance of this class. Therefore, we need the constructor to accept a component (IComponent) argument, which will hold our custom control.
We then cast this component to our custom control and store it in a private reference variable (txt).
We will also need a DesignerActionUIService reference to be able to Refresh our Smart-Tag panel when that is required.

Friend Class TextBoxActionList
    Inherits DesignerActionList
 
    Private txt As customTextBox
 
    Private txt As customTextBox
    Private designerActionSvc As DesignerActionUIService
 
    Public Sub New(ByVal component As IComponent)
        MyBase.New(component)
 
        txt = DirectCast(component, customTextBox)
        designerActionSvc = CType(GetService(GetType(DesignerActionUIService)), DesignerActionUIService)
    End Sub
 
End Class

Now, let's go back to our Designer class again. The DesignerActionList class we have just created merely creates the different items on our Smart-Tag panel (we have yet to do that), but we still need to tell the Designer class of our custom control that it should actually use these items.
To do that, we need to Override the ActionLists property, and instead of returning the Mybase.ActionLists (which contain the default ActionListItems), we return a custom DesignerActionListCollection containing our custom DesignerActionList.
There's not much to explain about this other than we need to make sure the ActionListCollection is not empty before returning it. If it is, we need to create a New instance of our collection:

Imports System.Windows.Forms.Design
Imports System.ComponentModel.Design
Imports System.ComponentModel
 
Public Class customTextBoxDesigner
    Inherits ControlDesigner
 
    Private _actionListCollection As DesignerActionListCollection
 
    Public Overrides ReadOnly Property ActionLists() As System.ComponentModel.Design.DesignerActionListCollection
        Get
            If _actionListCollection Is Nothing Then
                _actionListCollection = New DesignerActionListCollection()
                _actionListCollection.Add(New TextBoxActionList(Me.Control))
            End If
 
            Return _actionListCollection
        End Get
    End Property
End Class

The Designer class is now finished. Note that there is MUCH more you can do with a custom Designer class (see for example my WizardControl and my Custom TabControl in my signature), but if all you require is Smart-Tags, this is it.


Let's go back to our DesignerActionList (which I've called TextBoxActionList class (should be in the same file).
We still need to tell the designer which properties and methods should be in the Smart-Tag panel. This will obviously depend on your requirements, so I have added a few different examples in my attached project. I am only going to describe the process for one property and one method here though, since it is the same every time.

You may have noticed from other Smart-Tags that there are different kinds of properties: there are textboxes you can change, there are checkboxes, comboboxes, Font selectors, etc, etc, etc. The great thing about this is, you don't need to worry about that at all! Visual Studio understands which type of 'control' (on the Smart-Tag panel) is required for each Type of your property. If you create a Boolean property, it will create a Checkbox. If you create a String property, a Textbox will appear. If you create a DockStyle property, a complete 'Dock control' will appear.

The most common property of a TextBox is obviously its Text property, so we need a Property (of type String) that gets and sets the Text property of our customTextBox (txt):

Public Property Text() As String
        Get
            Return txt.Text
        End Get
        Set(ByVal value As String)
            txt.Text = value
        End Set
    End Property

(As I've said, if you require a Font property for example, just make it of type Font and you will get a button on the Smart-Tag panel that allows you to browse through Font styles.)

Besides properties, you can also put methods (that will appear as a hyperlink) on the Smart-Tag panel. Clicking these will run a piece of code that can do whatever you want (such as change the size of a control, or more commonly Dock/Undock it into the parent container).

The Dock/Undock method hyperlink on a Smart-Tag usually changes its text to "Undock in parent container." when the control is Docked, and to "Dock in parent container." when the control is Undocked. We will get to that later. For now, let's just create the method that will Dock or Undock our control. One thing is important to allow the text to change: we need to refresh the DesignerActionService (designerActionSvc.Refresh) otherwise the text won't change until you close and re-open the Smart-Tag panel.

Public Sub OnDock()
        If txt.Dock = DockStyle.Fill Then
            txt.Dock = DockStyle.None
        Else
            txt.Dock = DockStyle.Fill
        End If
 
        designerActionSvc.Refresh(txt)
    End Sub

(Continued in next post....)