docs-desktop/dotnet-desktop-guide/framework/winforms/controls/user-drawn-controls.md

title, ms.date, dev_langs, helpviewer_keywords, ms.assetid

title	ms.date	dev_langs	helpviewer_keywords	ms.assetid
User-Drawn Controls	03/30/2017	csharp vb	custom controls [Windows Forms], user-drawn OnPaint method [Windows Forms] user-drawn controls [Windows Forms]	034af4b5-457f-4160-a937-22891817faa8

User-Drawn Controls

The .NET Framework provides you with the ability to easily develop your own controls. You can create a user control, which is a set of standard controls bound together by code, or you can design your own control from the ground up. You can even use inheritance to create a control that inherits from an existing control and add to its inherent functionality. Whatever approach you use, the .NET Framework provides the functionality to draw a custom graphical interface for any control you create.

Painting of a control is accomplished by the execution of code in the control's xref:System.Windows.Forms.Control.OnPaint%2A method. The single argument of the xref:System.Windows.Forms.Control.OnPaint%2A method is a xref:System.Windows.Forms.PaintEventArgs object that provides all of the information and functionality required to render your control. The xref:System.Windows.Forms.PaintEventArgs provides as properties two principal objects that will be used in the rendering of your control:

• xref:System.Windows.Forms.PaintEventArgs.ClipRectangle%2A object - the rectangle that represents the part of the control that will be drawn. This can be the entire control, or part of the control depending on how the control is drawn.

• xref:System.Drawing.Graphics object - encapsulates several graphics-oriented objects and methods that provide the functionality necessary to draw your control.

For more information on the xref:System.Drawing.Graphics object and how to use it, see How to: Create Graphics Objects for Drawing.

The xref:System.Windows.Forms.Control.OnPaint%2A event is fired whenever the control is drawn or refreshed on the screen, and the xref:System.Windows.Forms.PaintEventArgs.ClipRectangle%2A object represents the rectangle in which painting will take place. If the entire control needs to be refreshed, the xref:System.Windows.Forms.PaintEventArgs.ClipRectangle%2A will represent the size of the entire control. If only part of the control needs to be refreshed, however, the xref:System.Windows.Forms.PaintEventArgs.ClipRectangle%2A object will represent only the region that needs to be redrawn. An example of such a case would be when a control was partially obscured by another control or form in the user interface.

When inheriting from the xref:System.Windows.Forms.Control class, you must override the xref:System.Windows.Forms.Control.OnPaint%2A method and provide graphics-rendering code within. If you want to provide a custom graphical interface to a user control or an inherited control, you can also do so by overriding the xref:System.Windows.Forms.Control.OnPaint%2A method. An example is shown below:

Protected Overrides Sub OnPaint(ByVal e As PaintEventArgs)  
   ' Call the OnPaint method of the base class.  
   MyBase.OnPaint(e)  
  
   ' Declare and instantiate a drawing pen.  
   Using myPen As System.Drawing.Pen = New System.Drawing.Pen(Color.Aqua)  
      ' Draw an aqua rectangle in the rectangle represented by the control.  
      e.Graphics.DrawRectangle(myPen, New Rectangle(Me.Location, Me.Size))  
   End Using
End Sub  

protected override void OnPaint(PaintEventArgs e)  
{  
   // Call the OnPaint method of the base class.  
   base.OnPaint(e);  
  
   // Declare and instantiate a new pen.  
   using (System.Drawing.Pen myPen = new System.Drawing.Pen(Color.Aqua))  
   {
      // Draw an aqua rectangle in the rectangle represented by the control.  
      e.Graphics.DrawRectangle(myPen, new Rectangle(this.Location,
         this.Size));  
   }
}  

The preceding example demonstrates how to render a control with a very simple graphical representation. It calls the xref:System.Windows.Forms.Control.OnPaint%2A method of the base class, it creates a xref:System.Drawing.Pen object with which to draw, and finally draws an ellipse in the rectangle determined by the xref:System.Windows.Forms.Control.Location%2A and xref:System.Windows.Forms.Control.Size%2A of the control. Although most rendering code will be significantly more complicated than this, this example demonstrates the use of the xref:System.Drawing.Graphics object contained within the xref:System.Windows.Forms.PaintEventArgs object. Note that if you are inheriting from a class that already has a graphical representation, such as xref:System.Windows.Forms.UserControl or xref:System.Windows.Forms.Button, and you do not wish to incorporate that representation into your rendering, you should not call your base class's xref:System.Windows.Forms.Control.OnPaint%2A method.

The code in the xref:System.Windows.Forms.Control.OnPaint%2A method of your control will execute when the control is first drawn, and whenever it is refreshed. To ensure that your control is redrawn every time it is resized, add the following line to the constructor of your control:

SetStyle(ControlStyles.ResizeRedraw, True)  

SetStyle(ControlStyles.ResizeRedraw, true);  

Note

Use the xref:System.Windows.Forms.Control.Region%2A?displayProperty=nameWithType property to implement a non-rectangular control.

See also

• xref:System.Windows.Forms.Control.Region%2A
• xref:System.Windows.Forms.ControlStyles
• xref:System.Drawing.Graphics
• xref:System.Windows.Forms.Control.OnPaint%2A
• xref:System.Windows.Forms.PaintEventArgs
• How to: Create Graphics Objects for Drawing
• Constituent Controls
• Varieties of Custom Controls