--- title: Render a control ms.date: "03/30/2017" ms.topic: overview dev_langs: - "csharp" - "vb" helpviewer_keywords: - "custom controls [Windows Forms], rendering" - "OnPaintBackground method [Windows Forms], invoking in Windows Forms custom controls" - "custom controls [Windows Forms], graphics resources" - "custom controls [Windows Forms], invalidation and painting" ms.assetid: aae8e1e6-4786-432b-a15e-f4c44760d302 --- # Rendering a Windows Forms Control Rendering refers to the process of creating a visual representation on a user's screen. Windows Forms uses GDI (the new Windows graphics library) for rendering. The managed classes that provide access to GDI are in the namespace and its subnamespaces. The following elements are involved in control rendering: - The drawing functionality provided by the base class . - The essential elements of the GDI graphics library. - The geometry of the drawing region. - The procedure for freeing graphics resources. ## Drawing Functionality Provided by Control The base class provides drawing functionality through its event. A control raises the event whenever it needs to update its display. For more information about events in the .NET Framework, see [Handling and Raising Events](/dotnet/standard/events/index). The event data class for the event, , holds the data needed for drawing a control — a handle to a graphics object and a rectangle object that represents the region to draw in. These objects are shown in bold in the following code fragment. ```vb Public Class PaintEventArgs Inherits EventArgs Implements IDisposable Public ReadOnly Property ClipRectangle() As System.Drawing.Rectangle ... End Property Public ReadOnly Property Graphics() As System.Drawing.Graphics ... End Property ' Other properties and methods. ... End Class ``` ```csharp public class PaintEventArgs : EventArgs, IDisposable { public System.Drawing.Rectangle ClipRectangle {get;} public System.Drawing.Graphics Graphics {get;} // Other properties and methods. ... } ``` is a managed class that encapsulates drawing functionality, as described in the discussion of GDI later in this topic. The is an instance of the structure and defines the available area in which a control can draw. A control developer can compute the using the property of a control, as described in the discussion of geometry later in this topic. A control must provide rendering logic by overriding the method that it inherits from . gets access to a graphics object and a rectangle to draw in through the and the properties of the instance passed to it. ```vb Protected Overridable Sub OnPaint(pe As PaintEventArgs) ``` ```csharp protected virtual void OnPaint(PaintEventArgs pe); ``` The method of the base class does not implement any drawing functionality but merely invokes the event delegates that are registered with the event. When you override , you should typically invoke the method of the base class so that registered delegates receive the event. However, controls that paint their entire surface should not invoke the base class's , as this introduces flicker. For an example of overriding the event, see the [How to: Create a Windows Forms Control That Shows Progress](how-to-create-a-windows-forms-control-that-shows-progress.md). > [!NOTE] > Do not invoke directly from your control; instead, invoke the method (inherited from ) or some other method that invokes . The method in turn invokes . The method is overloaded, and, depending on the arguments supplied to `e`, a control redraws either some or all of its screen area. The base class defines another method that is useful for drawing — the method. ```vb Protected Overridable Sub OnPaintBackground(pevent As PaintEventArgs) ``` ```csharp protected virtual void OnPaintBackground(PaintEventArgs pevent); ``` paints the background (and thereby the shape) of the window and is guaranteed to be fast, while paints the details and might be slower because individual paint requests are combined into one event that covers all areas that have to be redrawn. You might want to invoke the if, for instance, you want to draw a gradient-colored background for your control. While has an event-like nomenclature and takes the same argument as the `OnPaint` method, is not a true event method. There is no `PaintBackground` event and does not invoke event delegates. When overriding the method, a derived class is not required to invoke the method of its base class. ## GDI+ Basics The class provides methods for drawing various shapes such as circles, triangles, arcs, and ellipses, as well as methods for displaying text. The namespace and its subnamespaces contain classes that encapsulate graphics elements such as shapes (circles, rectangles, arcs, and others), colors, fonts, brushes, and so on. For more information about GDI, see [Using Managed Graphics Classes](../advanced/using-managed-graphics-classes.md). The essentials of GDI are also described in the [How to: Create a Windows Forms Control That Shows Progress](how-to-create-a-windows-forms-control-that-shows-progress.md). ## Geometry of the Drawing Region The property of a control specifies the rectangular region available to the control on the user's screen, while the property of specifies the area that is actually painted. (Remember that painting is done in the event method that takes a instance as its argument). A control might need to paint only a portion of its available area, as is the case when a small section of the control's display changes. In those situations, a control developer must compute the actual rectangle to draw in and pass that to . The overloaded versions of that take a or as an argument use that argument to generate the property of . The following code fragment shows how the `FlashTrackBar` custom control computes the rectangular area to draw in. The `client` variable denotes the property. For a complete sample, see [How to: Create a Windows Forms Control That Shows Progress](how-to-create-a-windows-forms-control-that-shows-progress.md). [!code-csharp[System.Windows.Forms.FlashTrackBar#6](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/CS/FlashTrackBar.cs#6)] [!code-vb[System.Windows.Forms.FlashTrackBar#6](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/VB/FlashTrackBar.vb#6)] ## Freeing Graphics Resources Graphics objects are expensive because they use system resources. Such objects include instances of the class as well as instances of , , and other graphics classes. It is important that you create a graphics resource only when you need it and release it soon as you are finished using it. If you create a type that implements the interface, call its method when you are finished with it in order to free resources. The following code fragment shows how the `FlashTrackBar` custom control creates and releases a resource. For the complete source code, see [How to: Create a Windows Forms Control That Shows Progress](how-to-create-a-windows-forms-control-that-shows-progress.md). [!code-csharp[System.Windows.Forms.FlashTrackBar#5](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/CS/FlashTrackBar.cs#5)] [!code-vb[System.Windows.Forms.FlashTrackBar#5](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/VB/FlashTrackBar.vb#5)] [!code-csharp[System.Windows.Forms.FlashTrackBar#4](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/CS/FlashTrackBar.cs#4)] [!code-vb[System.Windows.Forms.FlashTrackBar#4](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/VB/FlashTrackBar.vb#4)] [!code-csharp[System.Windows.Forms.FlashTrackBar#3](~/samples/snippets/csharp/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/CS/FlashTrackBar.cs#3)] [!code-vb[System.Windows.Forms.FlashTrackBar#3](~/samples/snippets/visualbasic/VS_Snippets_Winforms/System.Windows.Forms.FlashTrackBar/VB/FlashTrackBar.vb#3)] ## See also - [How to: Create a Windows Forms Control That Shows Progress](how-to-create-a-windows-forms-control-that-shows-progress.md)