Simple Steps in VB.NET. Building a Custom Control
Article source code: ssteps_customcontrol.zip
Introduction
This article is for beginners and demonstrates step by step how you can create a very basic custom control.
The control we are going to create is an enhanced version of a standard Button control which we will call the XtraButton control.
In this demo we are simply going to simply build on the functionality of an existing control, a Button control. There are much more sophisticated things that can be done, but as this is a 'Simple Steps' article, we'll stick to basics for now. We'll maybe get more adventurous in a later article.
Setting Up
First of all, open a new Project. Select the 'Windows Control Library' icon from the New Project - Templates Window.
Give the Project a meaningful name - "XtraButton" will do nicely.
Accept or overwrite the location for the files to be saved to.
Press OK. This will create a Solution which contains a Project named XtraButton, which in turn contains an object named UserControl1.vb.
Let's change the name of this user control to something more meaningful - "XtraButton" again.
Highlight the name 'UserControl1.vb' in the Solution Explorer and change it to XtraButton.vb.
We also need to rename the Class itself. So open the XtraButton.vb's code window and change the line which reads:
Public Class UserControl1
So that it reads:
Public Class XtraButton
As we are basing our new control totally on the standard button control, we can also change the code so that it specifically inherits all the properties, methods and events of a button.
Still in the Code Window, change the line that reads:
Inherits System.Windows.Forms.UserControl
So that it reads:
Inherits System.Windows.Forms.Button
Creating a Test Bed
Before we really begin to roll our sleeves up and create our nifty new control, we ought to have somewhere to test it out. It's often handy to be able to test it at various stages during it's creation, so we will deal with that requirement now.
In the Solution Explorer, select Solution 'XtraButton' and right-click it. From the drop-down menu, select Add... , then 'New Project'.
This time, make sure you select a 'Windows Application' template (it will probably still be highlighting the Windows Control Library template you selected previously). Give this new Windows Application project a meaningful name - 'Test Form', for instance.
I prefer to save the test projects in a subfolder of the Custom Control's own folder, so if you want to do that then use the Browse button to navigate your way there and then click OK to save it.
A quick check in the Solution Explorer will reassure you that all is as it should be - two projects are now displayed: XtraButton and Test Form.
Building the new Button
Turning our attention back to the user control itself now, by changing the code line so that the control inherits specifically from the Button control class and not from the more generic 'UserControl' we actually already have a User Control. However, it's not a very exciting one, because it simply replicates the standard button control at this stage.
But we'll continue to take this a small step at a time. In the Visual Studio menu, choose Build, then Build XtraButton. You're unlikely to get any errors showing in the Output Window (but if you do, I would suggest that you're sufficiently unlucky that you should avoid walking under ladders or going outside in lightning storms!)
(Don't forget to save your Solution at regular intervals.)
Just Checking
Another brief sidestep here to allow us to check that the Control does actually exist and that we can use it, if we wanted to.
Open the Design Window of Form1 in your Test Form Project (selectable from the Solution Explorer).
You've saved and Built the XTraButton. Now, in the Solution Explorer, select the Test Form project. Right Click on the project name and from the context menu that appears, select 'Add Reference'. A new dialog box entitled 'Add Reference' will then appear.
This dialog box has three tabs. Select the 'Projects' tab. It should contain only one entry - 'XtraButton' and its path information. Make sure this item is highlighted and click on the 'Select' button to the right of the dialog box. It will then appear in the lower pane. Select this entry to highlight it, then finally click the OK button down at the bottom of the dialog box to confirm and close it.
Now, open the Toolbox. The Windows Forms Tab will be open by default. Use the small down arrow on the Tab to scroll to the bottom of the list of available controls. And there at the bottom of the list you should find - voila ! - the XtraButton control.
If you find that this doesn't work - and it can be problematic sometimes - then the best procedure is this. Towards the end of this article, there is a paragraph which is titled "Using Your Control in Other Projects". Follow the instructions in that paragraph, but START FROM WHERE IT SAYS "Right Click on the ToolBox..." because you obviously don't want to have another project on the go just yet; you still have a bit of legwork to do here first! This will enable you to add the XtraButton to your toolbox.
Select the XtraButton from the ToolBox and put one instance of it on your form Double click the icon or left click to select and draw it on the form. (If you were a bit generous with the size of the drawing surface when you first created the User Control Project, double clicking might present with a larger than life button!)
For the avoidance of any confusion (as if!), I should point out that the XtraButton appears at the end of the ToolBox list by default. It just happens to be a coincidence that in the example above, it is the last item because it begins with a letter X. If we'd named it SmartButton it would still have been sitting there last in line.
Running Before You Can Walk
At this stage (if you're easily excited) you may be keen to try running the solution in the usual way by pressing F5 or clicking the little Start arrow at the top of the IDE. Go on, then, give it a go!
Disappointing, huh? This little problem arises because at the moment the UserControl project is the StartUp project for this Solution (you created it first, remember?) . User Control projects don't have a Sub Main and can't be executed (VS creates a DLL file for you, but we really don't need to get into that).
All you have to do is set the Test Form project as Startup project.
Here's the easy way to do this:
- Select the Test Form project in Solution Explorer
- Right click it
- Choose "Set as Startup Project"
Now try running it again and everything will be fine - not very exciting ... but fine!
If you're interested, you may also check out the Solution Explorer once again and if you look at the References for the Test Form project, you will see that XtraButton has been added.
Let's Get Coding
Let's get started with those additional properties now. What might be neat would be to add a couple of ways of highlighting the button. The first way we'll do this is have the button change color when the mouse passes or hovers over it. And of course, we'll also need to include the code to change it back to the original color when the mouse is no longer over the button. Depending on the color chosen this can give the impression that the button 'lights up' as the mouse passes over it.
We need to declare some variables to hold the values of the button's colors as they change.
Add this code to the XtraButton Class's code in the Code Window:
Private mOldColor As Color ' Original button color
Private mMOColor As Color ' Mouse Over color
We can now incorporate these private variables into a new Property - the MouseOverColor Property. OK, so it's a bit long as names go, but it is descriptive!
Here is the code to create that property:
Property MouseOverColor() As Color
Get
MouseOverColor = mMOColor
End Get
Set(ByVal Value As Color)
mMOColor = Value
End Set
End Property
Once the control has been built, this new property will appear in the Properties Window of any instance of the XtraButton control that is placed on a form. And just like other standard properties, it can be changed at designtime in the Properties Window or at runtime as a result of code and/or user actions.
OK, fine, but so far it won't actually do anything, will it? So let's address that right now.
We'll create a procedure that will be called automatically whenever the mouse enters the visible area of the button. Here is that code:
Private Sub XB_MouseEnter(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles MyBase.MouseEnter
mOldColor = MyBase.BackColor
Me.BackColor = mMOColor
End Sub
What happens here is that the first line of the code makes a note of the color which had been chosen as the BackColor property of the XtraButton. (Because the XtraButton inherits all the properties of a standard button, it will have a BackColor property, just like any ordinary button).
The second line of code then changes the backcolor of the XtraButton to whatever color has been chosen as the MouseOverColor.
Before we go on to test this code, we'll add another procedure that handles what happens to the XtraButton's Backcolor when the mouse leaves:
Private Sub XB_MouseLeave(ByVal sender As Object, _
ByVal e As System.EventArgs) Handles MyBase.MouseLeave
Me.BackColor = mOldColor
End Sub
All this does is returns the XtraButton to the color it was before the mouse entered it's space.
Checkpoint
This might be a good place to see if we're heading in the right direction, so Build the XtraButton again, then select Form1.vb[Design]. Select an XtraButton from the Toolbox and place it somewhere on the form.
Click on the instance of the button on your form and press F4 to see the Properties Window for the XtraButton if it isn't already in view. You will see that, in addition to the properties you would normally expect to see for a button, there is now one named MouseOverColor, which currently has a white rectangle at the side of it.
A left mouse click on this rectangle will bring you the standard color picker menu. Choose a color.
Now, run the project and move the mouse and then away from the XtraButton. If all has gone to plan, it should change color when the mouse is over it and revert back when the mouse leaves. Try experimenting with different MouseOverColors, as well as with the basic BackColor properties.
Also add two or three XtraButtons in a vertical line on the form and give them the same MouseOverColor. Run the project again and you will see how it can add a kind of dynamic effect as the mouse traverses across them.
Attributes
If anyone else is going to use your control, it would be useful for them to have a description of each new property in the Properties Window. To add such a description, we will need to make some small additions to the code.
Firstly, add this statement at the very top of the code listing in the XtraButton's code window:
Imports System.ComponentModel
This will enable you to include attributes such as Descriptions with your properties.
Now, amend the first part of the code block for the MouseOverColor Property so that it reads as follows
<Description("Gets/Sets the BackColor of Control when Mouse is over it")> _
Property MouseOverColor() as Color
Notice the final underscore in that first line; you'll get an error if you miss it out
You'll need to Build the Control once again, then you can check to see if it has worked by going back to the Test Form Project and clicking on an XtraButton.
Now when you view the properties in the Properties Window, you will see that description is included at the bottom.
Using Your Control in Other Projects
You probably won't want to go to the trouble of creating this control just for use in a single project, so we'll finish off by covering how you can get access to the control in new projects.
Save and close the current project. Open a new project; choosing Windows Application from the Templates.
If you scroll down the controls in the ToolBox now you will see that the XtraButton is not there. So, we will need to add it to the list now.
Right Click on the ToolBox. Select Customize Toolbox from the menu that appears. Choose the .Net Framework Tab.
Now, click on the Browse button and navigate your way to the folder where you saved your User Control. Open the bin Subfolder of the project. You will see the file XtraButton.dll in that folder.
Click on the Open button and the control will be added to the list of .Net Framework Components in front of you. It should have automatically have been checked, but if it hasn't then you can do this now.
Close the Customize Toolbox menu by clicking OK. If you review the ToolBox again you will see that the XtraButton has been added. You are now able to use this control in this (and any future) projects that you create or use.
Moving On
From this very basic example, you will see that you can make many changes to the functionality of this control. You could make the color of the text change when the mouse is over it, or increase the size of the button very slightly (reverting to it's normal size when the mouse leaves). Or you can change the button color when it is clicked or when the mouse is left to hover over it . Some of these have been included in the attached project, but I'm sure you can think of others that you might want to incorporate yourself.
Related devCity.NET articles: