Custom controls come in three flavors:

There are two ways to approach a custom control of the complexity of the Rolodex. One is to build it incrementally; the other is to design it up front. I typically build incrementally, factoring out common code as I go. However, to present all the myriad iterations as functionality is added one step at a time would be a book in itself.

Thus, as an expedient, I’m going to build this as if I were omniscient, anticipating in advance a complete design that I can then implement.^[*]

Your Rolodex will be housed in forms. You will have a Rolodex form for Customers, a second Rolodex form for Suppliers, and one each for Employees and Orders (you’ll only implement Customers here; the others will be left as an exercise).

These four forms will all derive from a common base form, frmRolodex. The job of frmRolodex will be to hold the code and design common to all the derived forms.

Within each of these forms will be a Rolodex panel. The job of the panel will be to:

The Rolodex panel is shown in Figure 4-2.

Figure 4-2. Rolodex panel

Within the panel are Rolodex entries. You’ll design a MustInherit base class, RolodexEntry, and then you’ll derive classes (like RolodexCustomerEntry) from it. These classes will specialize what information goes in the entry. For Customers, you want the customer name, contract, phone, and fax. For suppliers, Employees, and Orders, you’ll want different information.

In summary, for this chapter, you’ll build the following:

To simplify project management, the forms will be kept in the NorthWindWindows project, but the custom controls (RolodexPanel, RolodexEntry, and RolodexCustomerEntry) will be in a new project named NorthWindControls. Both the NorthWindWindows project and the NorthWindControls project will be housed within the NorthWindWindows solution, thus making it easy for the projects to be kept together and managed as a single development effort.

Add a new project to your existing solution. To do so, right-click on the solution and choose Add → New project. Leave the Location the same as the location for your previous project, but name the new project NorthWindControls. Be sure to set the template to Windows Control Library, as shown in Figure 4-3.

Figure 4-3. Create the new Windows Control Library project

Visual Studio 2005 creates a new project (NorthWindControls) and within that project adds a UserControl, which it names UserControl1. Begin by renaming its file to RolodexPanel.vb.

To use the Rolodex panel, however, you need Rolodex entries. Therefore, you need to create a couple of additional custom controls.

To start, right-click on the new project and choose Add → New User Control and name it RolodexEntry.vb. This will serve as the base class for all the specialized RolodexEntry controls. You will create a derived RolodexEntry type for customers (RolodexCustomerEntry), on which the discussion in this chapter will focus. If you like, you can also create RolodexEntry types for Suppliers, Employees, and Orders.

RolodexEntry will have a Boolean member: chosen.

Public MustInherit Class RolodexEntry
    Protected chosen As Boolean

In addition, you will define an event for this user control. As you remember, all controls can publish events. The controls you’ve used so far have had such events as Click. You can create your own custom event for your new control just by declaring it with the Event keyword. In this case, you’ll want to define an EntrySelected event, as follows:

Public Event EntrySelected(ByVal sender As Object, ByVal e As EventArgs)

Provide a public property for the chosen member variable:

Public Property Selected() As Boolean
   Get
      Return Me.chosen
   End Get
   Set(ByVal value As Boolean)
      Me.chosen = value
      SetSelectedProperties()
   End Set
End Property

Notice that the Set accessor not only sets the value of chosen but also calls the method SetSelectedProperties:

Protected Overridable Sub SetSelectedProperties()
End Sub

SetSelectedProperties has no implementation, but it is marked Overridable. This indicates that the derived class (e.g., RolodexCustomerEntry) will override this method to do some work when the Selected property is set.

Finally, add a method, InternalClick , that raises the EntrySelected event, as shown in Example 4-1.

Public Overridable Sub InternalClick( _
ByVal sender As Object, _
ByVal e As EventArgs)
    RaiseEvent EntrySelected(sender, e)
End Sub

This method looks suspiciously like an event handler, except that it does not have the keyword Handles to indicate what events it does handle. This will be explained in time, but keep an eye on this method!

Before proceeding, build the project to ensure that the RolodexEntry exists so you can derive from it. Next, create the derived RolodexCustomerEntry.

To do so, right-click on the NorthWindControls project and choose Add → New Item. In the Add New Item dialog, choose Inherited User Control and name the new control RolodexCustomerEntry.vb. Clicking Add will bring up the Inheritance Picker so that you can select which control you are inheriting from, as shown in Figure 4-4.

Figure 4-4. Inheritance Picker dialog

Click OK and your third custom control (RolodexCustomerEntry) is created. You want each RolodexCustomerEntry to have a fixed size, large enough to accommodate the information for a customer, as shown in Figure 4-5.

Figure 4-5. RolodexCustomerEntry design

Set the size of the control to 225,75. Open the Toolbox and add the seven labels shown: lblCompanyName, lblContactPrompt, lblContactName, lblPhonePrompt, lblPhone, lblFaxPrompt, and lblFax.

The top label lblCompanyName has a BackColor of Silver and a font of Microsoft Sans Serif, 12pt, style = Bold. Set its AutoSize property to False, and set its size to 225,21. This will cause it to fill the top of the control. Set its TextAlign to TopLeft.

For the other six labels (which you can drag on to the control and then select all at once), set their font to Sans Serif, 8.25 and their BackColor property to Control. Set the TextAlign property to MiddleLeft, and set AutoSize to False. Set the size for the three labels in the left column to 56,16, and for the three in the right column to 145,16.

The name, text, and location of each of the seven labels are shown in Table 4-1.

Now open the code for RolodexCustomerEntry. You should see that it is already marked as Inherits NorthWindControls.RolodexEntry and that there is a collapsed region Windows Form Designer generated code. You may expand and examine that region, but do not edit the code.

It is time to override the overridable methods from the base class. Start by overriding SetSelectedProperties , as shown in Example 4-2.

Protected Overrides Sub SetSelectedProperties()
    If Me.Selected Then
        Me.lblCompanyName.BackColor = Color.Red
    Else
        Me.lblCompanyName.BackColor = Color.Silver
    End If
End Sub

Remember that when the Selected property is set, this method is called. For the selected RolodexCustomerEntry, it sets the background color of its lblCompanyName label to Red. For any RolodexCustomerEntrys that are not selected, it sets the background color of lblCompanyName to Silver.

You will also override the InternalClick method, setting it to handle a click on any of the labels on the RolodexCustomerEntry form (or on the form itself), as shown in Example 4-3.

Public Overrides Sub InternalClick( _
ByVal sender As Object, _
ByVal e As System.EventArgs) _
Handles lblCompanyName.Click, lblFax.Click, _
lblPhone.Click, lblContactName.Click, _
lblFaxPrompt.Click, lblPhonePrompt.Click, _
lblContactPrompt.Click, MyBase.Click
    MyBase.InternalClick(Me, e)
End Sub

Notice that it calls the base class’s InternalClick method (which, you remember, looked a lot like an event handler), passing a reference to itself (the selected RolodexCustomerEntry) and the eventArgs object it receives.

This effectively channels all responses to clicking anywhere in the RolodexCustomerEntry to the base class’s InternalClick method. It, in turn, raises the EntrySelected event, broadcasting a reference to the specific entry that was clicked.

Finally, you will add a method (LoadValues ) to load the values for the lblCompanyName, lblContactName, lblPhone, and lblFax labels, as shown in Example 4-4.

Public Sub LoadValues( _
 ByVal companyName As String, _
 ByVal contactName As String, _
 ByVal phone As String, _
 ByVal fax As String)
     Me.lblCompanyName.Text = companyName
     Me.lblContactName.Text = contactName
     Me.lblPhone.Text = phone
     Me.lblFax.Text = fax
 End Sub

You’ll see how this method is invoked later.

Public Const StartX As Integer = 32
Public Const StartY As Integer = 24
Public Const BufferSpace As Integer = 20
Public Const ScrollBarWidth As Integer = 25
Public Const RowsPerPage As Integer = 4
Public Const ColsPerRow As Integer = 3
Public Const NumEntriesPerPage As Integer = RowsPerPage * ColsPerRow

Public Event RowFillEvent(ByVal sender As Object, ByVal e As EventArgs)
Public Event ButtonSelectedEvent(ByVal sender As Object, ByVal e As EventArgs)

Protected chosenLtr As Char
Protected xIncr As Integer
Protected yIncr As Integer
Protected vsb As VScrollBar = New VScrollBar()
Protected entry As RolodexEntry = Nothing

ReadOnly Property ChosenLetter() As Char
   Get
      Return chosenLtr
   End Get
End Property

Private Sub RolodexPanel_Load( _
   ByVal sender As System.Object, _
   ByVal e As System.EventArgs) Handles MyBase.Load
   Dim entry As RolodexCustomerEntry = New RolodexCustomerEntry()
   xIncr = entry.Width + Me.BufferSpace
   yIncr = entry.Height + Me.BufferSpace
   Me.pnlRolodex.Height = RowsPerPage * _yIncrement + StartY
   Me.pnlNavigationButtons.Top = Me.pnlRolodex.Bottom + BufferSpace
   Me.pnlRolodex.Width = Me.pnlRolodex.Width - ScrollBarWidth
   Me.pnlRolodex.AutoScroll = False
   vsb.SmallChange = ColsPerRow
   vsb.LargeChange = NumEntriesPerPage
   vsb.Parent = Me
   vsb.Location = New Point(pnlrolodex.Right, pnlrolodex.Top)
   vsb.Size = New Size(ScrollBarWidth, pnlrolodex.Height)
   vsb.Minimum = 0
   AddHandler vsb.ValueChanged, AddressOf vbar_ValueChanged
End Sub

Protected Sub vbar_ValueChanged( _
ByVal sender As Object, ByVal e As EventArgs)
    RaiseEvent RowFillEvent(Me, New EventArgs())
End Sub

Private Sub LetterButton_Click( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) _
Handles btnZ.Click, btnY.Click, btnX.Click, btnW.Click, btnV.Click, btnU.Click, _
btnT.Click, btnS.Click, btnR.Click, btnQ.Click, btnP.Click, btnO.Click, btnN.Click, _
btnM.Click, btnL.Click, btnK.Click, btnJ.Click, btnI.Click, btnH.Click, btnG.Click, _
btnF.Click, btnE.Click, btnD.Click, btnC.Click, btnB.Click, btnA.Click
   Me.entry = Nothing
   Dim oldCursor As Cursor = Me.Cursor
   Me.Cursor = Cursors.WaitCursor
   Dim btn As Button = CType(sender, Button)
   If btn IsNot Nothing Then
   Dim letter as char = CChar(btn.Text.ToUpper())
      Me.LoadRolodex(letter)
   End If
   Me.Cursor = oldCursor
   RaiseEvent ButtonSelectedEvent(sender, e)

End Sub

Protected Sub LoadRolodex()
   LoadRolodex(CType("A", Char))
End Sub


Protected Sub LoadRolodex(ByVal letter As Char)
    Me._currentLetter = letter
End Sub

Public Sub Add(ByVal c As Control)
    Me.pnlRolodex.Controls.Add(c)
End Sub

Public Sub Clear()
    Me.pnlRolodex.Controls.Clear()
End Sub

Public Sub entry_click( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs)
    chosenEntry = CType(sender, RolodexEntry)
    For Each c As Control In Me.pnlRolodex.Controls
        Try
            Dim re As RolodexEntry = CType(c, RolodexEntry)
            re.Selected = False
        Catch ex As Exception
            Continue For
        End Try
    Next
    chosenEntry.Selected = True

End Sub

Your custom control (RolodexPanel) will be housed within a form. The base form will be frmRolodex, whose job will be to provide common code for all the specialized forms (e.g., frmCustomerRolodex).

Back in the NorthWindWindows project, add a new form, frmRolodex. Set its size to 976,615. Open the Toolbox and expand the NorthWindControls Components section. Drag a RolodexPanel onto the new form, and drag a label named lblDisplay above it, as shown in Figure 4-6.

Everything in frmRolodex will be shared by all its derived types. You want to factor all the elements common to the derived forms into this form, so they will be as simple (and maintainable) as possible.

You need two members:

Protected orderedBy As String
Protected infoTable As Data.DataTable

The first, orderedBy, will keep track of the sort order for the data table. The second, infoTable, will hold a reference to a DataTable (e.g., the Customers table).

There are three event handlers you must create: one for when the form is loaded, the second for when the RowFillEvent is fired by the RolodexPanel, and the third for when the ButtonSelectedEvent is fired by the RolodexPanel.

When the form is loaded, you’ll call LoadRolodex, a helper method, as shown in Example 4-12.

Figure 4-6. Adding RolodexPanel to frmRolodex

Private Sub frmRolodex_Load( _
ByVal sender As System.Object, _
ByVal e As System.EventArgs) Handles MyBase.Load
    LoadRolodex()
End Sub

This method will not be implemented in the base class, but will be implemented in the derived forms:

Protected Overridable Sub LoadRolodex()
End Sub
Protected Overridable Sub LoadRolodex(ByVal letter As Char)
End Sub

The second event handler responds to the RowFillEvent of the RolodexPanel, as shown in Example 4-13.

Private Sub OnFillRows( _
ByVal sender As Object, _
 ByVal e As EventArgs) _
 Handles RolodexPanel1.RowFillEvent
                  FillRows 
                      
(infoTable)
End Sub

This event handler calls the helper method FillRows, passing in the table to fill the rows from, as shown in Example 4-14.

Protected Sub FillRows(ByVal infoTable As Data.DataTable)
   Dim column As Integer = 0
   Dim row As Integer = 0
   Me.RolodexPanel1.Clear()

   Dim loopcounter As Integer
   For loopcounter = 0 To Me.RolodexPanel1.NumEntriesPerPage -1
      Dim offset As Integer = Me.RolodexPanel1.Vbar.Value + _
      (row * 3) + column
      If offset >= infoTable.Rows.Count Then
         Exit For
      End If
      Dim dataRow As System.Data.DataRow = infoTable.Rows(offset)
      AddEntry(dataRow, column, row)
      column = column + 1
      If column = 3 Then
         column = 0
         row = row + 1
      End If
   Next
End Sub

The effect is to fill the Rolodex Panel with three rows of RolodexEntry objects.

The FillRows method is overloaded. The second version is called by the event handler that responds to an A-Z button being pressed.

Private Sub OnButtonSelected( _
ByVal sender As Object, _
ByVal e As EventArgs) _
Handles RolodexPanel1.ButtonSelectedEvent
    FillRows(Me.RolodexPanel1.CurrentLetter, Me.infoTable)
End Sub

This version of FillRows takes the letter to search for within the data (as well as the DataTable containing the data), as shown in Example 4-15.

Protected Sub FillRows( _
ByVal letter As Char, _
ByVal infoTable As Data.DataTable)
   Dim offset As Integer = 0
   Dim orderByName As Char = CType("A", Char)
   For Each dr As Data.DataRow In infoTable.Rows
      orderByName = dr(orderedby).ToString().ToUpper()(0)
      If orderByName >= letter Then
         Exit For
      End If
      offset = offset + 1
   Next
   Me.RolodexPanel1.Vbar.Value = offset

End Sub

Finally, the code that will be shared by the LoadRolodex override of all the derived forms is factored into the DoLoad method of the base class, shown in Example 4-16.

Protected Sub DoLoad( _
ByVal count As Integer, _
ByVal letter As Char, _
ByVal infoTable As Data.DataTable)
    Me.RolodexPanel1.Vbar.Maximum = count
    Me.lblDisplay.Text = count.ToString() + " records "
    Me.RolodexPanel1.Vbar.Value = 0
    FillRows(infoTable)
End Sub

Private Sub btnAllClick( _
ByVal sender As System.Object, ByVal e As System.EventArgs) _
Handles btnAllCustomers.Click, btnAllSuppliers.Click, _
btnAllEmployees.Click, btnAllOrders.Click, mnuEmployeesShowAll.Click, _
mnuCustomersShowAll.Click, mnuOrdersShowAll.Click
Dim txt As String = String.Empty

If TypeOf sender Is Button Then
    txt = CType(sender, Button).Text
ElseIf TypeOf sender Is ToolStripMenuItem Then
    txt = CType(sender, ToolStripMenuItem).Name
End If
Dim oldCursor As Cursor = Me.Cursor
Me.Cursor = Cursors.WaitCursor
If txt.Contains("Customers") Then
    Dim rolodex As frmRolodex = New frmCustomerRolodex()
    rolodex.Show()
Else
    MessageBox.Show(txt + _
    " not yet implemented", "Not Yet Implemented", _
        MessageBoxButtons.OK, MessageBoxIcon.Exclamation)
End If
Me.Cursor = oldCursor
End Sub

Protected Overrides Sub LoadRolodex()
   LoadRolodex(CChar("A"))
End Sub
Protected Overrides Sub LoadRolodex(ByVal letter As Char)
   CustomersTableAdapter.Fill( _
   CType(Me.NorthwindDataSet.Tables("Customers"), _
   NorthWindWindows.NorthwindDataSet.CustomersDataTable))

   Dim dataTable As NorthwindDataSet.CustomersDataTable = _
       CustomersTableAdapter.GetData()
   Dim count As Integer = dataTable.Rows.Count
   Me.infoTable = dataTable
   Me.orderedby = "CompanyName"
   DoLoad(count, letter, infoTable)
End Sub

Protected Overrides Sub AddEntry( _
ByVal dataRow As System.Data.DataRow, _
ByVal column As Integer, _
ByVal row As Integer)

   Dim entry As NorthWindControls.RolodexCustomerEntry = _
       New NorthWindControls.RolodexCustomerEntry()

   Dim companyName As String = String.Empty
   Dim contactName As String = String.Empty
   Dim phone As String = String.Empty
   Dim fax As String = String.Empty

   If IsDBNull(dataRow("CompanyName")) = False Then
      companyName = CStr(dataRow("CompanyName"))
   End If
   If IsDBNull(dataRow("ContactName")) = False Then
      contactName = CStr(dataRow("ContactName"))
   End If
   If IsDBNull(dataRow("Phone")) = False Then
      phone = CStr(dataRow("Phone"))
   End If
   If IsDBNull(dataRow("Fax")) = False Then
      fax = CStr(dataRow("Fax"))
   End If

   entry.LoadValues(companyName, contactName, phone, fax)
   entry.Left = Me.RolodexPanel1.StartX + _
       (column * Me.RolodexPanel1.XIncrement)
   entry.Top = Me.RolodexPanel1.StartY + _
       (row * Me.RolodexPanel1.YIncrement)
   AddHandler entry.EntrySelected, _
       AddressOf Me.RolodexPanel1.entry_click
   Me.RolodexPanel1.Add(entry)

End Sub

AddHandler entry.EntrySelected, _
    AddressOf Me.RolodexPanel1.entry_click

Walking Through a Letter Button Click

To see what happens when a Letter button is clicked, set break points in:

• RolodexPanel: LetterButtonClick, LoadRolodex, and vBar_valueChanged

• frmRolodex: OnButtonSelected, FillRows

Click on the letter T. The LetterButton_Click method is invoked. The result of this is to invoke LoadRolodex (passing in the letter), which sets the current letter, and then to raise the event ButtonSelectedEvent.

That event is caught by frmRolodex, which invokes the FillRows method, passing in the current letter and the data table. FillRows iterates through the rows until it finds a name that begins with a letter equal to or greater than the requested name, at which time it sets the vertical scrollbar value to the offset.

Setting the vertical scrollbar’s value causes the vbar to raise the ValueChanged event, which you set in RolodexPanel1_Load to be handled by vbar_ValueChanged. That, in turn, raises the RowFillEvent, passing in the Rolodex Panel itself).

The RowFillEvent is handled by OnFillRows in frmRolodex, which calls the other FillRows method, passing in the DataTable. FillRows extracts the offset from the vertical scrollbar and creates the entries, as you saw earlier, filling in the panel, as shown in Figure 4-7.

Figure 4-7. Running the completed Rolodex