Creating a Windows Form User Control

7/24/2019 Creating a Windows Form User Control

http://slidepdf.com/reader/full/creating-a-windows-form-user-control 1/15

1 | P a g e

Creating a Windows Form User Control

Paul D. Sheriff

PDSA, Inc.

January 2002

Summary: Describes how to create a Windows Form User Control as well as useful enumerations, errormessages, and verification. You will also learn how to add descriptions to your properties and methods

using attributes.

Objectives

Learn to create a Windows Form User Control

Create enumerations for ease of use

Add descriptions to your properties and methods using attributes

Create error messages and verification that will be useful to the users of your Control

Assumptions

The following should be true for you to get the most out of this document:

You understand Windows Form controls and basic coding

You can create classes

You are familiar with enumerations

Contents

Overview of User Controls

Inherited Properties Inherited Events

Creating Your Own Controls vs. Using Microsoft Controls

Overview of the Employee Number Control

Description of the Employee Number User Control Create the User Control

Create the Employee Number Project

Create the User Interface Create Properties

Create Events

Write Event Procedures for Constituent Controls

Create Methods Add Some Attributes

Build the Test Project

Test for an Invalid Employee Number Test for a Valid Employee Number

Summary

About The Author

https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic1


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic1a


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic1b


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic1c














https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic3d


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic3e


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic3f


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_topic3g








https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_summary


https://msdn.microsoft.com/en-us/library/aa302342.aspx#winformusecon_summarya























2 | P a g e

Overview of User Controls

Microsoft® .NET controls are all inherited from a common base class called UserControl. This class has

all the basic functionality for a graphical control that will be used on a Windows Form. All of the built-in.NET controls inherit from this same base class. You can inherit from this same base class as well, and

create your own controls. When you inherit from the UserControl class, you will be automatically

supplied with certain properties and events.

Inherited Properties

There are about 30 properties that you will inherit from the UserControl base class. These propertiesinclude all of the common properties you see on normal controls, such as the accessibility properties,

backcolor, forecolor, anchoring, and docking. You can override these properties if you need to, but you

will probably leave most of them as they are.

Inherited Events

A user control that you create inherits about 40 events from the UserControl base class. These events arethe ones that are most common, such as Load, Resize, and Layout events. Your control will also include

some of the low-level mouse and keyboard events, such as Click , DoubleClick , MouseUp, and

MouseDown.

You may override these inherited events if you need to, but it is best if you override only the inherited

On<EventName> method instead of directly overriding the base event, so that future controls may benefit

from the standards.

Creating Your Own Controls vs. Using Microsoft Controls

There are many reasons why you might want to create your own controls even though Microsoft supplies a

pretty rich set of controls right out of the box. The boxed controls may not solve all of your special business problems, so you’ll want to customize theirs or create new controls to meet your specific needs.

One of the most common uses that you will find for creating your own controls is for individualizing inputmasks and business rules for specific types of identifiers used in your applications across your enterprise.

A good example would be an employee number that is formatted in a special way and must be verifiedagainst a table in a database to make sure it exists. Instead of having each programmer create all of this

logic from scratch, you might create a control that will perform the logic for validating the correct format

and verifying its existence in the database.

Let's create an employee number control that checks to make sure that data is input in a specific format. It

will also check to make sure that the employee number exists in a database table.

Overview of the Employee Number Control

The EmployeeNumber control that you create will allow a user to input a number in the format AA-NNN.You must input two letters, followed by a hyphen, followed by three numbers. Figure 1 shows how this



3 | P a g e

control might look. The control is made up of a label with the text "Employee Number" and a text box thatcan be filled in with an employee number.

Figure 1. An employee number control on a Windows Form

Description of the Employee Number User Control

In addition to the built-in properties and events that are exposed automatically by the UserControl class,

you add on properties, events, and methods to this user control. Let’s discuss the various properties,

methods, events, and even classes that you can create for this user control.

Properties

There are six properties for which you will need to write appropriate Property statements. The Text

property will be a wrapper around the Text property on the TextBox on the User Control. You will alsocreate additional properties to hold employee data that is returned from a database table. These properties

are EmpID, LastName, FirstName, and Salary, and they are all created as wrappers around private

variables. These properties will be filled in only after you make a call to the EmployeeIsValid method

(which will be discussed in the next section). One last property you will need is ConnectionString. This property will be used to make a connection to the appropriate data source to retrieve the employee

information from the employee table.

Methods

You need to create a method that can be called to retrieve information from a database table called

Employees. You will name this method EmployeeIsValid. This optional method can be called by the user

to validate that the employee number is contained within the Employees table. This method returns a Trueor False response based on whether or not the value typed into the control matches the employee number in

the Employees table. If the employee number is found in the Employees table, the four employee propertiesare populated from other columns in this table.

Events

The BadEmployeeNumber event is raised when the user tries to move off the Employee Number controland the input format of the data is incorrect for some reason. If the user moves off the control and the data

is correct, no event will be raised. There are many reasons why the format could be incorrect. These

reasons will be enumerated within a class that is returned as an EmpNumEventArgs object. You will learnto build this class later in this document.



4 | P a g e

Classes

You will create a class within your user control called EmpNumEventArgs. This class inherits from

System.EventArgs and can thus be passed as the second argument to an event procedure. You will add

two properties to this new class, Message and ErrorNumber, and you will use this class when you raise

the BadEmployeeNumber event from your user control. The idea is to identify what is wrong with thedata the user entered, assign a description of what is wrong to the Message property and an error number to

the ErrorNumber property, and then send this object as the second parameter to the

BadEmployeeNumber event.

Enumerations

Instead of just arbitrarily assigning some error number to the ErrorNumber property of the

EmpNumEventArgs, it is a good idea to create an enumerated type that has a list of the possible error

numbers that could be generated. You will create an enumerated type named EmpNumErrors. Thisenumeration will be created with five values, NoError, NotLongEnough, LetterMissing, DashMissing,

NumberMissing. The following section describes the reasons why the error number format could be

wrong.

Create the User Control

To create any User Control, you follow a series of steps. The major steps are as follows.

1. Create a new Windows Control Library project.

2. Draw the user interface by selecting other controls from the toolbox that define how you want yourcontrol to work.

3. Create any additional properties.

4. Create any events that you want.5. Write any event procedures for constituent controls.

6. Create any methods that you want.

7.

Add some attributes.8. Build the control project.9. Add a new Windows Application project so you can test your control.

Create the Employee Number Project

Let's create the Employee Number User Control project.

1. Create a new project in Microsoft Visual Studio® .NET.

2. Choose the Windows Control Library template.

3. Set the Name of the project to PKUserControls.

4.

Click OK .5. You should now have a User Control design surface on which you can draw your user interface.



5 | P a g e

Create the User Interface

To create this Employee Number User Control, you will need to add a label and text box to the User

Control design surface. Add the controls and set the properties as listed in Table 1. When you are finished,you should have something that looks like Figure 2.

Figure 2. Create the Employee Number User Control using one Label and one Text Box control.

Table 1. Controls and properties to create and set in building the Employee User Control

Control Type Property Value

Label Name lblEmpNum

Text Employee Number

TextBox Name txtEmpNum

Text

MaxLength 6

CharacterCasing Upper

Create Properties

You will now build some additional properties that allow you to control the look of this User Control. You

will create the following properties in this control:

EmpID

LastName

FirstName

Salary

ConnectionString

Text



6 | P a g e

You create the first five properties (EmpID, LastName, FirstName, Salary, and ConnectionString)using private member variables and property statements. The Text property is simply a property statement

wrapped around the Text property of the txtEmpNum text box control. The steps are as follows:

Create the following member variables just after the Public Class EmployeeNumber statement as

shown below.

Add the IMPORTS statement, as this will be needed later in this document.

Imports System.ComponentModel

Public Class EmployeeNumber

Inherits System.Windows.Forms.UserControl

' Employee Properties

Private mintEmpId As IntegerPrivate mstrLastName As String

Private mstrFirstName As StringPrivate mdecSalary As Decimal

' Connection StringPrivate mstrConnectString As String

Create the property statements for each of these properties.

ReadOnly Property EmpID() As Integer

GetReturn mintEmpId

End Get

End Property

ReadOnly Property LastName() As StringGet

Return mstrLastNameEnd GetEnd Property

ReadOnly Property FirstName() As String

Get

Return mstrFirstNameEnd Get

End Property

ReadOnly Property Salary() As DecimalGet

Return mdecSalary

End Get

End Property

Property ConnectionString() As StringGet

Return mstrConnectStringEnd Get

Set(ByVal Value As String)mstrConnectString = Value

End Set

End Property



7 | P a g e

Create the Text property as a wrapper around the txtEmpNum text box control.

Public Overrides Property Text() As String

Get

Return txtEmpNum.TextEnd Get

Set(ByVal Value As String)txtEmpNum.Text = Value

End SetEnd Property

Notice that the Text property must use the Overrides attribute because the default Text property on the

UserControl class is used to display a title on the User Control.

Create Events

If the user types in an incorrect employee number format, you will want to raise an event back to the client

application so that you can inform the user of the problem with the format. To raise an event from a

control, you must first declare the event within the User Control. Use the Event declaration followed by thename of the event.

You will also need to pass in the standard parameters you find on all event procedures — sender and e. The

sender parameter is declared as an object data type. The e parameter must be declared as a

System.EventArgs type, or some derived class from the System.EventArgs class. In this case, you willwant to create your own class that inherits from the System.EventArgs class because you want to add an

error number property and a message property. These two properties allow you to fill in additional

information about how the employee number is not in the correct format. Below is the declaration that you

will need to write somewhere near the top of the EmployeeNumber User Control class.

' Create eventPublic Event BadEmployeeNumber( _ByVal Sender As System.Object, _

ByVal e As EmpNumEventArgs)

The EmpNumEventArgs class must be created prior to creating this event declaration. Before you cancreate the EmpNumEventArgs class, you first need to create an enumeration of error numbers. The

ErrorNumber property within the EmpNumEventArgs class will be defined as this enumeration type.

Create enumerated list

The enumeration you will now create, named EmpNumErrors, has five values declared in it. The

declaration for this enumeration is as follows:

Public Enum EmpNumErrorsNoError = 0NotLongEnough = 1

LetterMissing = 2DashMissing = 3

NumberMissing = 4End Enum



8 | P a g e

Each of these error numbers will be used to convey to the user of this control what the problem is with the

employee number that was typed in. Of course there will be a corresponding message filled in with moredescriptive information, but having an enumeration allows you to check for a specific error

programmatically, and potentially ignore that error as well. For example, you may choose allow a blank

employee number. If this is the case when the BadEmployeeNumber event is raised, you could check tosee whether the ErrorNumber property contained the NumberMissing value. If so, you might not display

the message to the user.

Create an enumeration class

Now you need to create the class that will be used to hold the error number and the message. This newclass, named EmpNumEventArgs, must first inherit from the System.EventArgs class. You must inherit

from this class so you can pass this derived object to the event procedure as the second parameter. Other

than the INHERITS statement, this class is a fairly straightforward class with just two property

declarations: Message and ErrorNumber. The ErrorNumber property is declared as the type enumeratedtype EmpNumErrors.

Public Class EmpNumEventArgs

Inherits System.EventArgs

Private mstrMessage As StringPrivate mintError As EmpNumErrors

<Description("Message to display for this error")> _Property Message() As String

GetReturn mstrMessage

End Get

Set(ByVal Value As String)mstrMessage = Value

End Set

End Property

<Description("Error number")> _Property ErrorNumber() As EmpNumErrors

GetReturn mintError

End Get

Set(ByVal Value As EmpNumErrors)

mintError = Value

End SetEnd Property

End Class

You might notice some strange XML-looking stuff in the above class. These are called attributes, and will

be covered later in this document. Now that you have created this class to use for the

BadEmployeeNumber event procedure, you are ready to write the code that checks for the format of the

employee number.



9 | P a g e

Write Event Procedures for Constituent Controls

Now we will write an event procedure that responds to the Validating event of the txtEmpNum text box.

Because the purpose of this control is to allow only a certain format for an employee number, you want tocheck whether or not the value input is in the correct format when the user attempts to tab out of this

control. The event procedure shown below has the code that will verify whether the data input is correct.

Private Sub txtEmpNum_Validating(ByVal sender As Object, _

ByVal e As System.ComponentModel.CancelEventArgs) _

Handles txtEmpNum.ValidatingDim intLoop As Integer

Dim strEmpNum As StringDim strMsg As String

Dim intNum As EmpNumErrors = EmpNumErrors.NoErrorDim eArgs As EmpNumEventArgs

' Get Employee NumberstrEmpNum = Trim(txtEmpNum.Text)

'****************************************' Is anything filled in at all?

'****************************************

If strEmpNum.Length = 0 ThenintNum = EmpNumErrors.NumberMissingstrMsg = "No employee number has been filled in"

End If

If intNum = EmpNumErrors.NoError Then

'****************************************' Is length less than 6 characters'****************************************

If strEmpNum.Length < 6 ThenintNum = EmpNumErrors.NotLongEnough

strMsg = "Not enough charactersin the employee number"

End IfEnd If

If intNum = EmpNumErrors.NoError Then'****************************************' Check first two characters

'****************************************

For intLoop = 0 To 1

If Not Char.IsLetter(strEmpNum, intLoop) ThenintNum = EmpNumErrors.LetterMissingstrMsg = "The first two characters must

be letters in the employee number"

Exit For

End IfNext

End If

If intNum = EmpNumErrors.NoError Then'****************************************' Check for dash (-) as third letter

'****************************************If strEmpNum.Substring(2, 1) <> "-" Then

intNum = EmpNumErrors.DashMissing



10 | P a g e

strMsg = "The third character must be a

dash (-) in the employee number"End If

End If

If intNum = EmpNumErrors.NoError Then'****************************************' Check for numerics in last 3 positions

'****************************************For intLoop = 3 To 5

If Not Char.IsDigit(strEmpNum, intLoop) ThenintNum = EmpNumErrors.NumberMissing

strMsg = "The last three characters

must be numeric in the employee number"

Exit ForEnd If

Next

End If

If intNum <> EmpNumErrors.NoError Then' If message is filled in, raise event

eArgs = New EmpNumEventArgs()

eArgs.ErrorNumber = intNumeArgs.Message = strMsg

e.Cancel = True

RaiseEvent BadEmployeeNumber(Me, eArgs)End If

End Sub

The code in this event procedure should be very simple to understand. You just check all of the possibleerror conditions regarding the number input by the user. If a part of the employee number is invalid, you

assign an error number to a local variable and an appropriate message to another local variable. At the end

of this procedure, you create a new EmpNumEventArgs object, fill in the ErrorNumber and Message

properties with the values in the local variables, and then raise the BadEmployeeNumber event, passing inthe instance of the User Control and the EmpNumEventArgs object.

Create Methods

An additional check you might wish to perform on an employee number is to see whether it exists within a

table in a database. The following method shows how you might validate the data within an Employeestable, and once you find a valid record, populate the additional properties on this control with other

information about the employee. For example, you might fill in the properties from other columns in the

table: EmployeeId (iEmp_id), LastName (szLast_nm), FirstName (sFirst_nm), and Salary

(cSalary_amt).

Public Function EmployeeIsValid() As BooleanDim oCmd As OleDb.OleDbCommand

Dim oDR As OleDb.OleDbDataReaderDim strSQL As String

strSQL = "SELECT iEmp_id, sEmp_num, szLast_nm, "

strSQL &= "sFirst_nm, cSalary_amt "

strSQL &= "FROM Employees "



11 | P a g e

strSQL &= "WHERE sEmp_num = '" & _

Trim(txtEmpNum.Text) & "'"

' Reset all propertiesmintEmpId = -1

mstrLastName = ""mstrFirstName = ""mdecSalary = 0

Try

oCmd = New OleDb.OleDbCommand()With oCmd

.Connection = New _

OleDb.OleDbConnection(mstrConnectString).Connection.Open()

.CommandText = strSQL' Closes connection when closing' DataReader object

oDR = .ExecuteReader( _CommandBehavior.CloseConnection)

End With

If oDR.Read() Then

mintEmpId = _CType(oDR.Item("iEmp_id"), Integer)

mstrLastName = _CType(oDR.Item("szLast_nm"), String)

mstrFirstName = _

CType(oDR.Item("sFirst_nm"), String)mdecSalary = _

CType(oDR.Item("cSalary_amt"), Decimal)End IfoDR.Close()

Catch oExcept As Exception

' Throws the exceptionThrow

End Try

If mintEmpId = -1 ThenReturn False

Else

Return TrueEnd If

End Function

Of course, this method assumes that you have a table called Employees in a database with the structure, as

follows:

CREATE TABLE Employees(

iEmp_id int IDENTITY (1, 1) NOT NULL

PRIMARY KEY NONCLUSTERED ,

sEmp_num char(6) NULL ,szLast_nm varchar(25) NULL ,

sFirst_nm char(15) NULL ,cSalary_amt money NULL

)



12 | P a g e

Add Some Attributes

In the EmpNumEventArgs class, you created some attributes. They were the XML-like prefixes to the

properties that looked like this:

<Description("Message to display for this error")>

These attributes can be read by any tool that will read meta-data about a class. These descriptions can be

handy when you distribute a compiled DLL and you want to convey additional information about your

class and properties. The attributes come from the System.ComponentModel NameSpace, which is why

you must import that NameSpace within the file where you will use attributes.

You can apply attributes to the definition of the User Control class itself. This can give you the option of

setting the event to be the default when you double-click on the control. Below, you’ll find the attributethat you should add directly above the definition of the EmployeeNumber class. Be sure to either put it on

the same line as the Public Class definition, or include the underscore character, as these attributes must be

placed on the same line as the class definition.

<DefaultEvent("BadEmployeeNumber")> _

Public Class EmployeeNumber

You can assign attributes to properties of the EmployeeNumber class. For example, you can have theattributes of properties such as EmpID, LastName, and FirstName appear in the Properties Window by

using the Browsable(True) attribute. You can assign a category to the property by using the

Category("Employee") attribute. You can also put in a description attribute that will show up in the

description window below the property window.

<Category("Employee"), Browsable(True), Description("Employee ID")> _

ReadOnly Property EmpID() As Integer...

<Category("Employee"), Browsable(True), _Description("Last Name of Employee. Read Only. _

Only filled in after called to _EmployeeIsValid method.")> _

ReadOnly Property LastName() As String...

<Category("Employee"), Browsable(True), _

Description("First Name of Employee. Read Only. _Only filled in after called to _

EmployeeIsValid method.")> __

ReadOnly Property FirstName() As String...



13 | P a g e

Build the Test Project

It is time to test the control that you have created. To do this, you need to close all of the windows for your

User Control, build the project, and add a new Windows Application project.

1. Close all windows for your User Control.

2. From the Build menu, select Build to compile the control.3. To add a new project, from the File menu click Add Project and then click New Project.

4.

Select Windows Application from the list of Templates.5. Give the new project a name, such as TestUserControl, and click OK to add this new project to the

Solution.

6. To set a Reference to your User Control project, from the Project menu click Add Reference.

Then go to the Projects tab and select your User Control project.7. Add a new EmployeeNumber control to your form by finding it in the Toolbox and double-

clicking your control.

8. Set the Name property to enEmp.

9. Add a Save button to the form so that your form looks like Figure 1.10. Set the Name of this Save button to btnSave.

11. Double-click the EmployeeNumber control and add the following MessageBox to the

BadEmployeeNumber event procedure.

Private Overloads Sub _enEmp_BadEmployeeNumber(ByVal Sender As System.Object, _

ByVal e As PKUserControls.EmpNumEventArgs) _Handles enEmp.BadEmployeeNumber

MessageBox.Show(e.Message)

End Sub

Test for an Invalid Employee Number

You can now run the application and see what happens when you put in both a valid and an invalidnumber.

1. Set this new project as the startup project by clicking on the new project. Then right mouse-clickand choose the Set as Startup Project from the menu.

2. Press F5 to run the application.

3. Put in an invalid employee number and tab away from the control.4. You should see an error message describing what is wrong with the number.

Test for a Valid Employee Number

Next, try out the EmployeeIsValid method on the EmployeeNumber control. Write the following codeunder the Click event procedure for the Save button.

Private Sub btnSave_Click(ByVal sender As System.Object, _

ByVal e As System.EventArgs) Handles btnSave.ClickTry

enEmp.ConnectionString = ConnectStringBuild()

If enEmp.EmployeeIsValid() Then' Call Save Routine Here



14 | P a g e

MessageBox.Show("Valid Number for: " & _

enEmp.LastName)Else

MessageBox.Show("Invalid Employee Number")End If

Catch oException As ExceptionMessageBox.Show(oException.Message)

End TryEnd Sub

You will need to create a connection string function that builds a valid OLEDB provider string.

Private Function ConnectStringBuild() As String

Dim strConn As String

strConn = "Provider=sqloledb;"

strConn &= "Data Source=(local);"

strConn &= "Initial Catalog=Employees;"

strConn &= "User ID=sa"

Return strConn

End Function

You will need to create the table in SQL Server and add some valid employee information to the table.Then you can click on the Save button to test out this functionality.

What’s Different in Visual Basic .NET From Visual Basic 6.0?

The basics of creating a user control are very similar to the way you created these controls in Visual

Basic® 6.0. There are some new techniques, such as using attributes, that make adding comments to your

properties and methods a lot easier. Creating properties, methods, and events in Visual Basic .NET is done

in the same way as in Visual Basic 6.0, so creating a control in Visual Basic .NET will be very familiar toyou.

Summary

In this document, you learned how to create a User Control that you can use and reuse on any Windowsform in any application. To reuse this control in any other project, simply customize the toolbox and point

to the DLL that is created. Passing information back in your own custom EventArgs object is an excellent

way to convey additional information to the user of this control. Adding attributes to your control will give

users better information about how to use your control.

About the Author

Paul D. Sheriff is the owner of PDSA, Inc. (www.pdsa.com), a custom software development and

consulting company in Southern California. Paul is the MSDN Regional Director for Southern California,

is the author of a book on Visual Basic 6.0 called Paul Sheriff Teaches Visual Basic, and has produced over72 videos on Visual Basic, SQL Server, .NET, and Web Development for Keystone Learning Systems.

mailto:[email protected]





15 | P a g e

Paul has co-authored a book entitled ASP.NET Jumpstart. Visit the PDSA, Inc. Web site for moreinformation.

About Informant Communications Group

Informant Communications Group, Inc. (www.informant.com) is a diversified media company focused on

the information technology sector. Specializing in software development publications, conferences, catalog publishing, and Web sites, ICG was founded in 1990. With offices in the United States and the United

Kingdom, ICG has served as a respected media and marketing content integrator, satisfying the burgeoningappetite of IT professionals for quality technical information.

Copyright © 2002 Informant Communications Group and Microsoft Corporation

Technical editing: PDSA, Inc., or KNG Consulting

http://service.bfast.com/bfast/click?bfmid=43945&sourceid=0039384188&bfpid=0672323575&bfmtype=Book



Creating a Windows Form User Control

Documents

Transcript of Creating a Windows Form User Control