Composite Controls

A composite control combines several existing controls into one new control. For example, the ColorScroller control shown in Figure 12-4 contains three labels, three scroll bars, and a panel. At runtime, the user can drag the scroll bars to select a color’s red, green, and blue components. The control displays a sample of the color in the panel on the right.

Figure 12-4: The ColorScroller control lets the user select a color interactively by dragging scroll bars.

To build a composite control, start a new control library project as usual. Give the library a meaningful name, and change the name of the default control UserControl1 to something more descriptive.

Next, in Solution Explorer, double-click on the control to open it in the form designer. Use the Toolbox to add constituent controls to the UserControl just as you would add controls to a form. Set the controls’ design-time properties using the Properties window.

Edit the code of the UserControl to make the constituent controls work together to provide the behavior that you want. For the ColorScroller control shown in Figure 12-4, you would make the scroll bars’ events adjust the color displayed in the sample area on the right. You can handle the constituent controls’ events, get and set their property values, and invoke their methods. You can also define new properties, methods, and events for the composite control.

The following code shows how the ColorScroller control works. It starts by declaring the ColorChanged event to tell the program when the user changes the control’s selected color. It then includes property procedures that define the SelectedColor property. The Property Get procedure uses the Color class’s FromArgb to convert the scroll bars’ values into a color. The Property Set procedure sets the control’s Red, Green, and Blue properties to the components of the new Color value. The Red Property Get procedure returns the value of the red scroll bar. The Property Set procedure sets the red scroll bar’s value, displays the value in the red label, displays a sample of the current color, and raises the ColorChanged event. The Green and Blue property procedures are basically the same so they are not shown here. When the user changes the red scroll bar’s value, the hbarRed_Scroll event handler sets the control’s new Red property value. The event handlers for the Green and Blue scroll bars are similar, so they are not shown here.

  Public Class ColorScroller     ' Tell the program that the color has changed.     Public Event ColorChanged(ByVal new_color As Color)     ' Get or set the currently selected Color.     Public Property SelectedColor() As Color         Get             Return Color.FromArgb( _                 255, _                 hbarRed.Value, _                 hbarGreen.Value, _                 hbarBlue.Value)         End Get         Set(ByVal value As Color)             Red = value.R             Green = value.G             Blue = value.B         End Set     End Property     ' Get: Return the color component value.     ' Set: Set the scroll bar value,     '      display the color, and      '      raise the ColorChanged event.     Public Property Red() As Byte         Get             Return CByte(hbarRed.Value)         End Get         Set(ByVal Value As Byte)             hbarRed.Value = Value             lblRed.Text = hbarRed.Value.ToString             panSample.BackColor = SelectedColor             RaiseEvent ColorChanged(SelectedColor)         End Set     End Property     ' Green and Blue property procedures omitted...     ' The user has changed a color value.     ' Set the appropriate color component value.     Private Sub hbarRed_Scroll(ByVal sender As System.Object, _      ByVal e As System.Windows.Forms.ScrollEventArgs) Handles hbarRed.Scroll         Red = CByte(hbarRed.Value)     End Sub     ' Green and Blue scroll bar Scroll event handlers omitted... End Class  

Composite controls are useful when you can build the behavior you want by using existing controls. They are most useful when you will need to use the combined controls many times, either in the same application or in several applications. If you need to implement these features only once, you can simply place the constituent controls right on a form and include code to handle their events.

Composite controls are also useful for keeping the related controls and their code together. This keeps some of the details of the controls and their code separate from the rest of the application. If the interactions among the controls are complex, it may make sense to build a separate UserControl to simplify the project.

Composite controls (or any control, for that matter) also provide a nice, clean separation between developers. If you build a complex control and add it to a large project, other developers can interact with the control only through the properties, methods, and events that it exposes. They cannot access the constituent controls directly, and that removes a potential source of bugs.