BUILDING COMPOUND CONTROLS 401

Building Compound Controls

A compound control provides a visible interface that combines multiple Windows controls. As a result, this type of control doesn’t inherit the functionality of any specific control. You must expose its properties by providing your own code. This isn’t as bad as it sounds, because a compound control inherits the UserControl object, which exposes quite a few members of its own. You will add your own members, and in many cases you can map a property or method of the compound control to a property or method of one of its constituent controls. If your control contains a TextBox control, for example, you can map the custom control’s WordWrap property to the equivalent property of the TextBox. The following property procedure demonstrates how to do it:

Property WordWrap() As Boolean

Get

WordWrap = TextBox1.WordWrap

End Get

Set(ByVal Value As Boolean)

TextBox1.WordWrap = Value

End Set

End Property

As you can see, you don’t have to maintain a private variable for storing the value of the custom control’s WordWrap property. When this property is set, the Property procedure assigns the property’s value to the TextBox1.WordWrap property. Likewise, when this property’s value is requested, the procedure reads it from the constituent control and returns it.

The same logic applies to events. Let’s say your compound control contains a TextBox and a ComboBox control, and you want to raise the TextChanged event when the user edits the TextBox control and the (custom) SelectionChanged event when the user selects another item in the ComboBox control. First, you must declare the two events:

Event TextChanged

Event SelectionChanged

Then, you must raise the two events from within the appropriate event handlers: the TextChanged event from the TextBox.TextChanged event hander and the SelectionChanged from

the ComboBox.SelectedIndexChanged event handler:

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

ByVal e As System.EventArgs) Handles FocusedTextBox1.TextChanged RaiseEvent TextChanged()

End Sub

Private Sub ComboBox1_SelectedIndexChanged(ByVal sender As System.Object, _ ByVal e As System.EventArgs) Handles ComboBox1.SelectedIndexChanged

RaiseEvent SelectionChanged() End Sub

VB.NET at Work: The ColorEdit Control

The control we’ll build in this section is very similar to the Color dialog box. The ColorEdit control allows you to specify a color by adjusting its red, green, and blue components with three scroll bars, or to select a color by name. The control’s surface at runtime on a form is shown in Figure 9.4.

402 Chapter 9 BUILDING CUSTOM WINDOWS CONTROLS

Figure 9.4

The ColorEdit control on a form

Now open the UserControl object and design its interface, as shown in Figure 9.4. The three ScrollBar controls are named RedBar, GreenBar, and BlueBar respectively. The MinimumValue property for all three controls is 0; the MaximumValue for all three is 255. This is the valid range of values for a color component. The control at the top-left corner is a Label control with its background color set to Black. (We could have used a PictureBox control in its place.) The role of this control is to display the selected color.

The ComboBox control at the bottom of the control is the NamedColors control, which is populated with color names when the control is loaded. Color is the name of an object that allows you to manipulate colors, and it exposes 140 properties, which are color names (Beige, Azure, and so on). Don’t bother entering all the color names in the ComboBox control; just open the ColorEdit project on the CD and you will find the AddNamedColors() subroutine, which does exactly that. The first few lines of this function are shown next:

Private Sub AddNamedColors() With ComboBox1.Items

.Add(“AliceBlue”)

.Add(“AntiqueWhite”)

.Add(“Aqua”)

The user can specify a color by sliding the three ScrollBar controls or by selecting an item in the ComboBox control. In either case, the Label control’s Background color will be set to the selected color. If the color was specified with the ComboBox control, the three ScrollBars will be adjusted to reflect the color’s basic components (red, green, and blue components).

Not all possible colors you can specify with the three ScrollBars have a name (there are approximately 16 million colors). That’s why the ComboBox control contains the “Unknown” item, which is selected when the user specifies a color by settings its basic components.

Finally, the ColorEdit control exposes two properties, the SelectedColor and NamedColor properties. The NamedColor property retrieves the selected color’s name. If the color wasn’t isn’t selected on the ComboBox control, the value “Unknown” will be returned. The SelectedColor property returns, or sets, the current color. The SelectedColor property’s type is Color, and it can be assigned any expression that represents a color value. The following statement will assign the form’s BackgroundColor property to the SelectedColor property of the control:

ctrlColorEditor.SelectedColor = Me.BackgroundColor

BUILDING COMPOUND CONTROLS 403

You can also specify a color value with the FromARGB method of the Color object:

ctrlColorEditor.SelectedColor = Color.FromARGB(red, green, blue)

The implementation of the SelectedColor property is shown in Listing 9.3, and it’s straightforward. The Get section of the procedure assigns the Label’s background color to the SelectedColor property. The Set section of the procedure extracts the three color components from the value of the property and assigns them to the three ScrollBar controls. Then it calls the ShowColor subroutine to update the display (you’ll see shortly what this subroutine does).

Listing 9.3: The SelectedColor Property Procedure

Property SelectedColor() As Color

Get

SelectedColor = Label1.BackColor

End Get

Set(ByVal Value As Color)

HScrollBar1.Value = Value.R

HScrollBar2.Value = Value.G

HScrollBar3.Value = Value.B

ShowColor()

End Set

End Property

The NamedColor property (Listing 9.4) is read-only and is marked with the ReadOnly keyword in front of the procedure’s name. This property retrieves the value of the ComboBox control and returns it.

Listing 9.4: The NamedColor Property Procedure

ReadOnly Property NamedColor() As String

Get

NamedColor = ComboBox1.SelectedItem

End Get

End Property

When the user selects a color name in the ComboBox control, the code retrieves the corresponding color value with the Color.FromName method. This method accepts a color name as argument (a string) and returns a color value, which is assigned to the namedColor variable. Then the code extracts the three basic color components with the R, G, and B properties (these properties return the red, green, and blue color components). Listing 9.5 shows the code behind the ComboBox control’s SelectedIndexChanged event, which is fired every time a new color name is selected on the control.

404 Chapter 9 BUILDING CUSTOM WINDOWS CONTROLS

Listing 9.5: Specifying a Color by Name

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

ByVal e As System.EventArgs) Handles ComboBox1.SelectedIndexChanged Dim namedColor As Color

Dim colorName As String

colorName = ComboBox1.SelectedItem If colorName <> “Unknown” Then

namedColor = Color.FromName(colorName) HScrollBar1.Value = namedColor.R HScrollBar2.Value = namedColor.G HScrollBar3.Value = namedColor.B ShowColor()

End If End Sub

The ShowColor property simply sets the Label’s background color to the color specified by the three ScrollBar controls. Even when you select a color value by name, the control’s code sets the three ScrollBars to the appropriate values. This way, we don’t have to write additional code to update the display. The ShowColor subroutine is quite trivial:

Sub ShowColor()

Label1.BackColor = Color.FromARGB(255, HScrollBar1.Value, _

HScrollBar2.Value, HScrollBar3.Value)

End Sub

The single statement in this subroutine picks up the values of the three basic colors from the ScrollBar controls and creates a new color value with the FromARGB method of the Color object. The first argument is the transparency of the color (the “A” or alpha channel), and we set it to 255 for a completely opaque color. You can edit the project’s code to take into consideration the transparency channel as well. If you do, you must replace the Label control with a PictureBox control and display an image on it. Then draw a rectangle with the specified color on top of it. If the color isn’t completely opaque, you’ll be able to see the underlying image and visually adjust the transparency channel.

Testing the ColorEdit Control

To test the new control, you must place it on a form. Build the ColorEdit control, add a new project to the current solution as before, reference the new control in the test project, and then add an instance of the control to the form. You don’t have to enter any code in the test form. Just run it and see how you specify a color either with the scroll bars or by name. You can also read the value of the selected color through the SelectedColor property. The code behind the Color Form button on the test form does exactly that:

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

ByVal e As System.EventArgs) Handles Button1.Click

Me.BackColor = ColorEdit1.SelectedColor

End Sub