Ch22

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

22

CHAPTER

Build Your Own Windows Control In this chapter, you will • Get acquainted with the different types of Windows controls you can create • Learn to build a composite control • Understand how to license your control • Be able to test your control

There will be times during your application development that you will need a control that cannot be found in the Toolbox or in the component libraries. You may also discover that you often create the same combination of controls on your Windows Forms or that you would like a particular control to exhibit extra functionality every time you use it. All of these dilemmas can be solved by creating your own Windows Forms control. Consider a text box control. It has a number of properties, methods, and events that you can use when you add the control to your form. But what if you wanted that same text box to accept only numeric input every time you used it. Instead of changing its properties every time, you can create a new type of text box control that exhibits the behavior that you desire. Often in a business application, you will find that a combination of controls is used to request a particular response from the user. Each application you build must have the same controls added and their functionality combined. By creating your own control that is built from the combination of these controls, you can reduce your development time greatly. Finally, if you are in the business of creating user controls for development teams, you may find that you regularly take a blank control and draw its interface and provide its functionality from scratch. In this chapter, we will investigate the ways you can create your own customized controls. You may already be familiar with the term ActiveX controls. These were the controls that Visual Basic programmers created and used. Microsoft has moved away from that term, which had mostly Internet connotations, and, in order to simplify and clarify things, now calls any component that has a visible interface a control. At this point in your OOP career, you should not find this kind of coding to be a mystery—after all, isn’t this just the same thing as building a class file in order to create reusable objects? The only difference here is that you build a graphical interface into the component, with which the user can interact.

1 P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:00 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

2

Methods of Building Windows Controls The Microsoft Visual C# .NET Windows exam will test your knowledge of the three different ways of building custom controls: • Extending an existing control. • Combining existing controls into a new composite control. • Designing and building a control from scratch. In this section, we will consider the three types of controls and briefly describe their use, and later we will examine the process of creating a composite control from a combination of existing controls in detail. Microsoft will likely test your knowledge of combining existing controls into a new single control, but we will look at all three methods individually. The combined control is probably the control most commonly built (unless you are a control developer and build your own from scratch). EXAM TIP There are three ways to build your own controls: inherit from an existing control, combine existing controls into a new control, or design and build your own control from scratch.

Extending an Existing Control In order to change or increase the functionality of an existing control, you can simply inherit from the base control, which gives you the base properties, methods, and events, and allows you to add what you need. To illustrate this, we will extend the standard button and add our own fine-tuning to its base functionality. Our new button will have an extra property called ButtonName that will allow the user to set and retrieve a name for the button.

Creating the New Extended Control To begin, start a new project that uses the Windows Control Library by selecting File | New | Project. From the New Project dialog box, choose Windows Control Library as shown in Figure 22-1. Give the project a name that will reflect the type of control you are building. For this example, name the project NewButton.cs. By naming the project, you will also have given a name to the namespace to which your class will belong. Once you are done, click OK. You will notice that you do not see the standard Windows Form in this type of project. Instead you see a UserControl interface (shown in the following illustration). We

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:00 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

3

Creating a new Windows Control Library project

will explore the UserControl interface in the “Creating Composite Controls” section, when we build controls that are made up of multiple existing controls.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:01 PM

PART IV

Figure 22-1

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

4 Once the new project has been created, you need to do a little housekeeping in order to name the class file and the constructor appropriately. Rename UserControl1.cs in the Solution Explorer to the name you chose (for this example, name it NewButton.cs). Then switch to code view and rename the class file to NewButton and the constructor to NewButton. Now examine the code carefully. You will see that the class file definition looks like this: public class NewButton: System.Windows.Forms.UserControl

This is the inheritance line that you must change if you want to inherit from an existing control. Our specifications state that our new control will have most of the functionality of a regular Button control, along with our own special additions. You must, therefore, change this line to read as follows: public class NewButton: System.Windows.Forms.Button

By changing this line, you have effectively created a new control that derives from the Button class. Your new control will have all the methods, properties, and events of a Button, and you can modify or add to that. Save and build your project before continuing. In order to create a new property that will allow us to set and retrieve the button’s name, you now need to add your own property to the code—ButtonName. Start by creating a private variable to store the new property: private string varValue;

Now create the public property procedure as follows: public string ButtonName { get { return varValue; } set { varValue = value; } }

Save and compile the application.

Testing an Extended Control One method of testing the control is to add a new project to the solution and place your control on the Windows Form of the new project. Follow these steps: 1. Add a new project to your solution (File | Add Project | Windows Application).

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:01 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

5 2. Set the new form as the startup form. Right-click on the application name in Solution Explorer and select Set as Startup Project. EXAM TIP A control created in the Windows Control Library will not start up a form on its own—that is why you need the new project and windows form to test your control. Add a reference to your control to the new project: 1. In Solution Explorer, right-click on the References for the new project and select Add Reference. The Add Reference dialog box will be displayed, as shown in Figure 22-2. 2. Select the Projects tab and choose your new control from the list. Once you have added the reference to the control, you will see it listed under the References heading in the Solution Explorer (see Figure 22-3). You need to do one more thing in order to use the control from the Toolbox.

Figure 22-2

Adding a reference to NewButton

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:01 PM

PART IV

1. Right-click on the Toolbox and select Customize Toolbox.

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

6 Figure 22-3 The NewButton reference in the Solution Explorer

2. You will be presented with the Customize Toolbox dialog box (see Figure 22-4). Choose the .NET Framework Components tab, which lists the installed components from the .NET Framework library. Click the Browse button and select the location of your control. 3. Click OK. You are now ready to build the new form. When you scroll down in the Toolbox, you will see your own control listed there. Notice that its name is NewButton—this is why it is very important to give your control a meaningful name from the start. Your control now operates like any other control. Double-click on it and a default NewButton will be added to your form (see Figure 22-5). The final step in this process is to add the functionality that will set or retrieve the new property. For the purposes of this demonstration, we will simply add code to the Click event of the NewButton that will produce a MessageBox displaying the property value: MessageBox.Show (newButton1.ButtonName);

The following illustration shows the result of clicking on the NewButton object. Notice that we set the property of the ButtonName during program design (look at Figure 22-5), and the property is retrieved through the Get in the property procedure.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:01 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

7

When to Extend an Existing Control

Figure 22-4

Customizing the Toolbox

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:02 PM

PART IV

It can get rather confusing to know when to extend an existing control and when to create a new control. The approach just presented of extending an existing control allows

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

8

Figure 22-5

The new form with a NewButton added

you to derive your control from a base control, maintaining all the properties, methods, and events of the base class. It also allows you to add to the original functionality or to override it. EXAM TIP Use these next two points to determine whether to extend an existing control or build a new one.

• If you need a control that provides much of the functionality of an existing control, it is wise to derive a new control from the existing one and simply add to it or override the base control’s methods. • If you don’t need a combination of existing controls, inherit from a single control. For instance, if you need a button to do the work of a regular button, and also to take on some of your required characteristics.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:02 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

9 If you don’t need to customize the look of the control, inheriting from an existing control is the way to go. However, if you need your own look on a control, this will require more work than simply overriding the behavior of a base control. In that case, you should create a new control independent of any base controls.

Creating Composite Controls Very often, you will find that you need a visual interface that is a combination of a number of controls. A control built from several existing controls is called a composite control. For example, you can build a simple control that will display the date and time by combining a Label control and the Timer control. You can program the label to display the current date and time whenever the Timer control’s Tick event is triggered. This can be set to happen every second or every minute. Of course, you can add these two controls to your form when you need them, so why would you go to the bother of creating a new control? The answer to that lies in the number of times you will need the combination of these two controls. If every form you create needs to display the date and time in this fashion, then you should create the new control.

Before we go into the details of creating a new control based on existing controls, we need to examine the UserControl class. Every control inherits from System.Windows.Forms.UserControl. You can think of the UserControl class as similar to the System.Windows.Forms.Form class—the Form acts as a container for the visual components of your application, and the UserControl acts as a container for the controls that you wish to combine into one. There is an extensive list of properties, methods, and events associated with the UserControl class that provide the basic functionality of your new control: • Properties such as Anchor, AutoScroll, BackColor, CanFocus, CausesValidation, DataBindings, Dock, Enabled, Font, ForeColor, Location, Size, TabIndex, TabStop, Text, and Visible, to name just a few. • Methods such as Dispose, DoDragDrop, Focus, Hide, Refresh, ResetText, Select, Show, and Validate. • Events such as BackColorChanged, ControlAdded, ControlRemoved, DragOver, Enter, GotFocus, KeyDown, KeyPress, MouseMove, Move, Resize, and TextChanged. This is just a short list of the properties, methods, and events that are part of any composite control. You can find the complete listing of control behavior in the help documents attached to Visual Studio .NET. Most of the behavior is inherited from the Control class from which UserControl is derived.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:03 PM

PART IV

The UserControl Class

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

10 The UserControl gives the control developer a container that provides basic control support. For example, a design interface is provided, onto which all other controls are placed. These controls keep their own functionality in the control’s design phase. However, when the control is completed and is used within another application, only the functions that have been released will be available to the user of the control. This gives the control designer free reign over what properties, methods, and events of the original controls are exposed to the world in the composite control. EXAM TIP A control never functions on its own. A control must exist within a hosting application and does not execute independently.

Before we look at how these controls are built, try to keep in mind that a composite control has two different design-time phases. The first phase is when the control itself is designed, and this is when the developer works with the properties of the controls on the UserControl. The second design-time phase is when the developer places the composite control on a new form. At that point, the developer has access to those properties, methods, and events that the control developer has exposed. EXAM TIP The controls that make up the composite control are called the constituent controls. For example, if you create a control that has a Label and a Timer, the Label and Timer are constituent controls. The new control built from the combination of the two is called the composite control.

Creating a Composite Control Let’s examine the overall process of creating a composite control. The following six steps outline the basic procedure, and we will expand upon these as we move through the section: 1. Start a new Windows Control Library project. 2. Add the constituent controls (from the Toolbox) to the UserControl. 3. Adjust the size of the UserControl user interface and the position, size, and properties of the constituent controls. 4. Expose or add any properties to the constituent controls (this involves declaring them as public). 5. Work with methods and events. 6. Test the control. EXAM TIP Properties, methods, and events of the constituent controls are, by default, hidden from the user of the composite control.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:03 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

11 Starting a New Windows Control Library Project The first step in building a composite control is to create the project under which it will be developed. From the menus, select File | New Project. You will be presented with the New Project dialog box (shown earlier in Figure 22-1). Choose the Windows Control Library and click OK. You will see the UserControl design interface shown in Figure 22-6. The Windows Control Library template is used to create customized controls that will be added to Windows Forms. By using the template, you automatically have added all the references to the solution that are required for a new control. These references include the System, System.Data, System.Drawing, System.Windows.Forms, and System.Xml namespaces. You will also notice that the UserControl1.cs file has been added to your solution. This is your UserControl interface. NOTE

The template is unavailable in the Standard Edition of Visual C# .NET.

PART IV

Figure 22-6

The UserControl interface

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:04 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

12 It’s a good idea to rename the UserControl to a more meaningful name, as this will be your control’s name. Follow these steps: 1. Right-click on the UserControl1.cs file in the Solution Explorer, and select Rename. Enter an appropriate name. 2. In the code module associated with the UserControl interface, find the class name and change it to your new name. You should also ensure that the namespace has a meaningful name as well. (Don’t forget to change the constructor name.) Adding Constituent Controls to the UserControl The next step is to add the constituent controls to the UserControl. This is done in the same way as placing controls on a Windows Form—double-click on the control from the Toolbox, or select the control and drag it into place. As an example, create a composite control called StudentValidate that can be used in the college project. This control should contain five constituent controls—two Label controls to display “Student Number:” and “Student Name:”, two TextBox controls to contain the student number and student name, and a Button for validating the input. The composite control is shown in Figure 22-7. Be sure to name all of your controls appropriately and not leave them as Button1, TextBox1, and so forth. Adjusting the Constituent Controls You can now go into the constituent controls and adjust their properties. The first properties that should concern you are the size and position of the controls. Place them as you want to see them in your final product. Be aware that the user of your control can adjust the sizes and move the controls if you leave them with that ability—the properties that allow these changes are exposed for the UserControl. If you allow the user to adjust sizes and positions, you must also provide code within the control’s interface that adjusts the control accordingly. TIP Set the size of the UserControl to be large enough to just hold the constituent controls. Remember that the UserControl will be a control in the Toolbox, and it will be added to another developer’s project. In the StudentValidate example, you could set the ReadOnly property of the student name text box to True, since you don’t want to allow the user to initially type into the text box. This text box should act as a display only. You can also add any additional properties to your new control as we did earlier in the chapter for a simple extended control: 1. In the code editor, add the private variables for the properties. 2. Create the property procedures.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:04 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

13

PART IV

Figure 22-7

The StudentValidate control

EXAM TIP Always use properties for your controls (instead of public variables)—the Visual Studio .NET designer program will only display properties, not variables. In the next section, “Exposing Properties of the Constituent Control,” we will examine the code to not only add new properties but also to expose the existing properties of the constituent control—remember, by default, they are hidden from the user of your control.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:05 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen All-In-One / MCAD/MCSD / MCSD Visual Visual C#C# .NET .NET Certification Certification All-in-One All-in-One Exam Exam Guide Guide / Rempel / Rempel & Lind & Lind / 222443-6 / 222443-6 / Chapter / Chapter 22

22

MCSD Visual C# .NET Certification All-in-One Exam Guide

14 Once you have set all properties to your initial values, the next step is to decide what you will allow the user of your control to do. Exposing Properties of the Constituent Control Let’s examine how you can allow the user of your composite control to take advantage of the functionality of its constituent controls. For this discussion, add a CheckBox control to the StudentValidate project, as shown in the following illustration.

This CheckBox should remain invisible until the student number has been validated since we don’t want the user to have access to it until the validation is performed. To accomplish this, you just need to create a public property that exposes the constituent control’s Visible property: public bool cbValid_Visible { set { if (cbValid.Visible == false) cbValid.Visible = true; else cbValid.Visible = false; } }

On a request to set the Visible property of the CheckBox called cbValid, this simple code segment will reverse the current value. Obviously, in a sophisticated application, the code would be more extensive. For our purposes, though, we must expose it in this manner so the user of the StudentValidate control (who could be another developer) can set the Visible property. This is what encapsulation is all about—users never need to know how the Visible property is set; they just need to know that they can use it. EXAM TIP In order to expose the properties of the constituent control, expose them as properties of the composite control.

You can also simply expose a constituent’s property without any extra coding: public Color txtName_BackColor {

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:05 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

15 get { return txtName.BackColor; } set { txtName.BackColor = value; } }

This is the easiest way to allow a user of the control access to a constituent property. You can also add properties as we did for our extended control, NewButton. Add the private variable declaration and then create the public get and set to access the private data:

EXAM TIP Remember that you can add in all the functionality that is required within the get and set code blocks. This is the value of using properties instead of public variables. Working with Methods and Events There is no practical difference between working with methods in any other class file and working with methods in a custom control. Declare your method and provide the body of the method implementation: public void ControlMethod { // implementation of the method goes here }

Events are a little different. An event is the way your control interacts with the rest of the application. There are two different ways of creating events: • Expose a constituent event (remember, they are private by default) • Create a custom event In order to expose a constituent event, the UserControl must raise the event. Start by adding an event handler in the UserControl (for example, add a Click event to a button control).

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:05 PM

PART IV

private int var; public int NewVariable { get { return var; } set { var = value; } }

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

16 private void btnValidate_Click (object sender, System.EventArgs e) { OnClick(e); }

The “On” before the “Click” in the method is used because all controls have a method that can be called to raise the event. In effect, the OnClick() method raises the Click event from the UserControl. In order to create a custom event, you can use delegates, which is the .NET standard for using exposing and consuming events in Windows Forms. For example, to create the event that should be triggered upon trying the student number too often in our StudentValidate control, you could use this code: // declare the delegate public delegate void OutOfLuckEventHandler (object sender, OutOfLuckEventArgs e);

Then you could add the event declaration: public event OutOfLuckEventHandler OutOfLuck;

And then you would raise the event by creating the “On” method: public void OnOutOfLuck (OutOfLuckEventArgs e) { // invoke the delegate OutOfLuck (this, e); }

You are not done yet. You must now allow the hosting application to use this event. You need to add code within the Click event of your Validate button to check the number of times the button has been clicked, and then cause the event to be raised: OnOutOfLuck (new OutOfLuckEventArgs ( <parameters>);

Finally, the hosting application would use the control’s event to respond to the raising of the event: private void myStudentValidate_OutOfLuck (object sender, OutOfLuckEventArgs e) { // write the code that responds to the 3 click attempts }

If you are still unsure as to how this would work, refer back to Chapter 19 to review the handling of events in Visual C# .NET. Testing the Composite Control Remember that controls are not stand-alone applications—they must be added to a hosting application first and then tested from there. Follow these steps to test your control: 1. Build your control. Select Build | Build from the menus. 2. Create a test project. Select File | Add Project | New Project.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:05 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

17 3. Select Windows Application, and give the new project a name. 4. Add a reference to your control. Right-click the References for your new project in the Solution Explorer and select Add Reference. This will display the Add Reference dialog box (see Figure 22-8). 5. Add your control to the Toolbox. Right-click the Toolbox and select Customize Toolbox. Then, from the .NET Framework Components tab, click Browse and find the directory containing your custom control. Drill down into the Bin\ Debug directory and add the control (see Figure 22-9). 6. Set the test project as the startup project. Right-click on the test project and choose Select as Startup. 7. Run the test project. You should notice that these steps are very similar to the steps taken to test a control that is created by extending an existing control. There is very little difference between the two methods.

PART IV

Figure 22-8

The Add Reference dialog box

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:05 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

18

Figure 22-9

Selecting the control from the Debug directory

When to Use a Composite Control We suggested earlier in the chapter that you would extend an existing control when you wanted the functionality of a single control enhanced with your own customization. When you create a composite control, you are pulling together more than one control into a visual interface (the UserControl). EXAM TIP Use a composite control when you want to bring together the functionality of many controls into one, reusable control.

Building Custom Controls A custom control is one for which you design the user interface elements instead of extending the functionality of one or many controls already in existence. For a custom control, you use the System.Windows.Forms.Control class as a base class, and this provides you with a blank canvas on which you draw the interface for the user. We will not go into the details of creating a custom user control, since you are not likely to see its implementation on the exam. However, for interest’s sake, here is some sample code that would start the process:

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:06 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

19 using System; using System.Drawing; using System.ComponentModel; using System.Windows.Forms; public class MyCustomControl: System.Windows.Forms.Control { // override the OnPaint event of the Control class // draw your own user interface using GDI+ protected override void OnPaint (System.Windows.Forms.PaintEventArgs e) { // using the PaintEventArgs object, call the methods of GDI+ e.Graphics.Draw<Method> (<arguments>); } }

EXAM TIP To build a composite control, extend the UserControl base class. To build a custom control, extend the Control base class.

Visual Studio .NET Support In this section, we will look at a few of the shortcut techniques you can use to build your controls. The goal behind any good integrated development environment is to save the developer time, and the Visual Studio program is no exception.

Using Visual Inheritance One of Microsoft’s stated exam objectives for building your own control is “Create a Windows control by using visual inheritance.” As we have noted already, you can create a control whose base control is just another control. For example, our NewButton is inherited from the base class Button. We accomplished this through code. You can use Visual Inheritance to accomplish the same thing.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:06 PM

PART IV

We have not examined the drawing capabilities of GDI+ (Graphics Device Interface) yet—that will be covered in Chapter 24; however, the preceding code demonstrates the way in which you would start to code your custom control. The base class contains a default event handler, OnPaint, which really does nothing. You must override it and insert the code that will make your control look the way you want it to. Notice that the event handler is sent an argument of type System.Windows.Forms.PaintEventArgs. Using that object, you can work with its most significant property—an object of type System.Drawing.Graphics. The methods of the Graphics object allow you to work with the GDI+ code of the .NET Framework. The draw methods, such as DrawString, allow you to paint a graphics object (in this case a String) onto the drawing surface. Refer to Chapter 24 for more information on GDI+.

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

20 Follow these steps to access the Inheritance Picker dialog box, from which you can choose an existing control: 1. Start a new Windows Application project and name it UsingVIDemo (see Figure 22-10). 2. If you wish, you can add references to existing components. For example, add a reference to the NewButton control by right-clicking on the project References in the Solution Explorer and choosing Add Reference. This opens the Add Reference dialog box (shown in Figure 22-11). From the Projects tab, browse to find your component, and add it to the reference list by clicking Select and then OK. 3. You can also add an inherited control. Select Project | Add New Item to open the Add New Item dialog box (see Figure 22-12). Select Inherited User Control from the Templates list on the right side of the dialog box. 4. If you are just starting your project, and you have not performed the Build operation on it, you will receive a warning message from the Inheritance Picker, as shown in the following illustration. If the control from which you intend to inherit is not found in the current assembly, you will receive this message as well. If you do not receive this message, skip to step 6.

Figure 22-10

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:06 PM

Creating a new Windows Application project

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

21

5. Click the Browse button in the Inheritance Picker warning dialog box, and find the directory with the assembly that contains your base control. PART IV

Figure 22-11

Adding a reference to an existing component

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:07 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

22

Figure 22-12

Adding an inherited control

6. You will now see the Inheritance Picker, as shown in the following illustration. You can either select the component from the list or click the Browse button to point the directory system to the component you wish to use. For this example, find and select the StudentValidate control created earlier in this chapter. Click OK, and the control will be added to your project.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:07 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

23 7. If you wish to alter any of the StudentValidate control’s properties, right-click on the reference to the control in the Solution Explorer and select View Designer. This will take you to the design-time instance of the control (see the following illustration).

PART IV

Notice that the Property Explorer window allows you to see the properties of the StudentValidate control. However, they are grayed out and are inaccessible to the developer. This is because all properties are deemed to be private unless the control designer chooses to expose them. In developing the StudentValidate control, you could create public properties for those constituent properties that you want to let users of the control work with.

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:08 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

24 EXAM TIP You can only modify properties for which there is a public property in the UserControl.

Adding Design-Time Support to Your Control So far, we have not been very friendly to the user of our controls. In this section, we will look at how to add a Toolbox bitmap for the StudentValidate control. We will also add attributes to the control, which can then be applied to properties, methods, or events. Finally, we will look at some of the features included in the .NET Framework to assist in developing controls.

Adding a Toolbox Bitmap A Toolbox bitmap provides a related graphic appearance for your control in the Toolbox. For example, the Label control has an “A” as its graphic, and a Button has a small button as its graphic. The NewButton and StudentValidate controls show default graphics when you add it to the Toolbox (see Figure 22-13). Notice that NewButton has one graphic and StudentValidate has another. It depends on how the control is created and what kind of control it is (simple, composite, custom) as to which bitmap is used. EXAM TIP A very important concept that we will introduce here is that you have your own copy of the control when it is added to your project. This is good news to developers who have, in the past, struggled with versioning of controls. Version 1 might have belonged to a certain number of applications, while version 2 belonged to different applications. By making the control part of the new application, the version is implicitly bound to the application. Here are the steps for adding a Toolbox bitmap to your control: 1. Open your control project. 2. Select Project | Add Existing Item from the menus. You will see the Add Existing Item dialog box, as shown in Figure 22-14. Change the Files of Type filter to “All files (*.*).” 3. Find an appropriate icon in the file system. In this example, we have chosen the MSN icon to represent the StudentValidate control (for no reason, other than we like MSN).

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:08 PM

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

25 Figure 22-13 The default Toolbox bitmaps

PART IV

4. Once the icon file (MSN.ico) has been added to the project, you need to treat it as an embedded resource. Click on the icon file in Solution Explorer, and

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:08 PM

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

26 then move to the Properties Explorer (see the following illustration). You can see that there is a Build Action property that you need to set to Embedded Resource.

Figure 22-14

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:09 PM

The Add Existing Item dialog box

Color profile: Generic CMYK printer profile Composite Default screen All-In-One / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

Chapter 22: Build Your Own Windows Control

27 5. Finally, you need to add the code that will associate the icon with the control. In the line preceding the class definition, add the following code: [ToolboxBitmap(typeof(StudentValidate), @"MSN.ico")]

The MSN.ico string specifies the file (you can also add the path to the file in the string) and the typeof parameter specifies that the icon is to be associated with the StudentValidate type. There are two other forms of this statement. Use whichever you need to access your icon for the Toolbox bitmap: // insert the icon associated with the control type only [ToolboxBitmap(typeof(StudentValidate)] // insert the icon associated with the path [ToolboxBitmap(@"MSN.ico")]

EXAM TIP Remember that this line of code appears before the class definition in your code module.

By adding attributes to properties and events (or to the control itself), you can add design-time functionality to the control. The attributes become part of the metadata of the control and allow you to specify how your custom properties will be grouped together within the Properties Explorer, what types of default values exist for your properties, and whether there are any custom editors for your custom properties. Table 22-1 identifies the types of attributes that you can add to your control.

Property Attribute

Description

Browsable

Indicates whether a property or event can be displayed in the Property Browser/Explorer. Indicates the name of the category that will be used to group the property in the Properties Explorer. Specifies the description the user will see when the property or event is selected from the Property Browser. Indicates the default property for the control. Indicates the default value of the property. Indicates the type converter to use when converting the property to another type. Specifies the editor to be used when changing the property. Specifies how the forms designer will refresh when changes are made to the property values.

Category Description DefaultProperty DefaultValue TypeConverter Editor RefreshProperties Table 22-1

Property Attributes That Can Be Added to a Custom Control

P:\010Comp\All-in-1\443-6\ch22.vp Friday, August 23, 2002 5:05:09 PM

PART IV

Adding Attributes to Properties

Color profile: Generic CMYK printer profile Composite Default All-In-One screen / MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide / Rempel & Lind / 222443-6 / Chapter

22

MCAD/MCSD Visual C# .NET Certification All-in-One Exam Guide

28 These attributes can be inserted into the code module for your control. Place them in front of the property or event to which you are adding this functionality. Here is an example: [Category("StudentValidate"), Description ("The Validate button will check for the existence of the Student Number in the database")] public override Button Validate

Providing Other Design-Time Support In order to give the user of your control extra design-time support, the features listed in Table 22-2 are available to your control. To go into any more detail on these features is beyond the scope of the Microsoft C# Windows exam. You may just need to be aware that these features exist.

Hosting Your Control in Internet Explorer There will be times when your control will be added to a browser page and displayed in Internet Explorer. Be aware that support for this exists only in versions of Internet Explorer 5.5 and higher. The control is loaded from the web server by adding an OBJECT tag into the HTML page as follows: