NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

Walkthrough: Developing a Simple Win Forms Control

This section will walk you through the key steps that are required to create a custom Win Forms control. If you have created controls before, the steps may seem familiar. However, even if you are an experienced control developer, it is recommended that you browse through the steps described here. If you are not familiar with properties, events, and attributes, see Properties, Events, and Custom Metadata Using Attributes before executing the tasks below.

The control that you will develop in the walkthrough, merely allows the alignment of text to be changed.

To create a simple custom control

  1. Define a class that derives from System.WinForms.RichControl
    [C#]
    public class FirstControl:RichControl{…}
  2. Define properties. (You are not required to define a property, but a custom control that does anything meaningful will generally need to define additional properties.) The code fragment below defines a property TextAlignment that will be used to format the Text property inherited from RichControl.
    [C#]
    private ContentAlignment alignment = ContentlAlignment.Left;
    public ContentAlignment TextAlignment {
             get {
                return alignment;
             }
             set {
                alignment = value;
    //Invalidate invokes the OnPaint method described 
    //in step 3 below.
                Invalidate(); 
             }
          }
    
  3. Override the protected OnPaint method inherited from RichControl to provide paint logic to your control. Unless you override OnPaint your control will not be able to draw. In the code fragment given below, the OnPaint method displays the Text property inherited from RichControl with a default alignment. The code example at the end of this section shows how OnPaint can change the alignment to that specified by TextAlignment defined in step 2 above.
    [C#]
    public class FirstControl : RichControl{
       public FirstControl() {…}
       protected override void OnPaint(PaintEventArgs e) {
          base.OnPaint(e);
          e.Graphics.DrawString(Text, Font, new SolidBrush (ForeColor),
                                ClientRectangle);
     } 
    }     
  4. Provide attributes for your control. Attributes allow your control and its properties and events to be displayed appropriately at design-time. The code fragment shown below applies attributes to the TextAlignment property. In a designer such as Visual Studio 7.0, the Category attribute (applied below) will cause the property to be displayed under a logical category. The Description attribute will cause a descriptive string to be displayed at the bottom of the property window when the TextAlignment property is selected.
    [C#]
    [
    Category("Alignment"),
    Description("Specifies the alignment of text.")
    ]
    public ContentAlignment TextAlignment {…}
    
  5. (optional) Provide resources for your control. You can provide resources, such as a bitmap for your control, by packaging them with your control. In PDC Technology Preview release, this can be accomplished by using a compiler option (/res for C#). At run time, the resource can be retrieved using methods of the System.Resources.ResourceManager class.

The code for FirstControl is shown below. The control is created in the namespace CustomWinControls. A namespace provides a logical grouping of related types. You can create your control in a new or existing namespace. In C#, the using declaration allows types to be accessed from a namespace without using the fully qualified name of the type. For example, with the using declaration below you can access the class RichControl from System.WinForms simply by typing RichControl instead of System.WinForms. RichControl.

If you compile FirstControl and create an assembly (which will be a .dll file in this case), you will be able to add it to the toolbox of a Win Forms designer such as Visual Studio 7.0. An example that shows how to build and use a custom control is provided in the Win Forms Quickstart.

[C#]
  namespace CustomWinControls{
   using System;
   using System.ComponentModel;
   using System.WinForms;
   using System.Drawing;
   public class FirstControl:RichControl{
      private ContentAlignment alignment = ContentAlignment.Left;
   [
    Category("Alignment"),
    Description("Specifies the alignment of text.")
   ]
      public ContentAlignment TextAlignment {
         get {
            return alignment;
         }
         set {
            alignment = value;
        //Invalidate invokes the OnPaint method
            Invalidate();
         }
      }

    //OnPaint aligns text as specified by the 
    //TextAlignment property, by passing a parameter
    //to the DrawString method of the Grahics object.
      protected override void OnPaint(PaintEventArgs e) {
         base.OnPaint(e);
         //TextFormat style = (TextFormat)0;
         StringFormat style = new StringFormat();
         style.Alignment = StringAlignment.Near;
         switch (alignment) {
            case ContentAlignment.Left:
               style.Alignment = StringAlignment.Near;
               break;
            case ContentAlignment.Right:
               style.Alignment = StringAlignment.Far;
               break;
            case ContentAlignment.Center:
               style.Alignment = StringAlignment.Center;
               break;
         }
   //Call the DrawString method of the System.Drawing class to write text.
   //Text and ClientRectangle are properties inherited from
   //RichControl and Control respectively.
         e.Graphics.DrawString(Text, Font, new SolidBrush (ForeColor), ClientRectangle, style);
      }
  }
}