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 System.Drawing namespace and its subnamespaces.
The following elements are involved in control rendering:
- The drawing functionality provided by the base class System.Windows.Forms.Control.
- 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 System.Windows.Forms.Control provides drawing functionality through its Paint event. A control raises the Paint event whenever it needs to update its display. For more information about events in the .NET Framework, see Handling and Raising Events.
The event data class for the Paint event, PaintEventArgs, 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.
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
[C#]
public class PaintEventArgs : EventArgs, IDisposable {
public System.Drawing.Rectangle ClipRectangle {get;}
public System.Drawing.Graphics Graphics {get;}
// Other properties and methods.
...
}
Graphics is a managed class that encapsulates drawing functionality, as described in the discussion of GDI+ later in this topic. The ClipRectangle is an instance of the Rectangle class and defines the available area in which a control can draw. A control developer can compute the ClipRectangle using the ClientRectangle property of a control, as described in the discussion of geometry later in this topic.
A control must provide rendering logic by overriding the OnPaint method that it inherits from Control. OnPaint gets access to a graphics object and a rectangle to draw in through the Graphics and the ClipRectangle properties of the PaintEventArgs instance passed to it.
Protected Overridable Sub OnPaint(pe As PaintEventArgs)
[C#]
protected virtual void OnPaint(PaintEventArgs pe);
The OnPaint method of the base Control class does not implement any drawing functionality but merely invokes the event delegates that are registered with the Paint event. When you override OnPaint, you should typically invoke the OnPaint method of the base class so that registered delegates receive the Paint event. However, controls that paint their entire surface should not invoke the base class's OnPaint, as this introduces flicker. For an example of overriding the OnPaint event, see the Windows Forms Control Sample.
Note Do not invoke OnPaint directly from your control; instead, invoke the Invalidate method (inherited from Control) or some other method that invokes Invalidate. The Invalidate method in turn invokes OnPaint. The Invalidate method is overloaded, and, depending on the arguments supplied to Invalidate, a control redraws either some or all of its screen area.
The base Control class defines another method that is useful for drawing — the OnPaintBackground method.
Protected Overridable Sub OnPaintBackground(pevent As PaintEventArgs)
[C#]
protected virtual void OnPaintBackground(PaintEventArgs pevent);
OnPaintBackground paints the background (and thereby the shape) of the window and is guaranteed to be fast, while OnPaint paints the details and might be slower because individual paint requests are combined into one Paint event that covers all areas that have to be redrawn. You might want to invoke the OnPaintBackground if, for instance, you want to draw a gradient-colored background for your control.
While OnPaintBackground has an event-like nomenclature and takes the same argument as the OnPaint method, OnPaintBackground is not a true event method. There is no PaintBackground event and OnPaintBackground does not invoke event delegates. When overriding the OnPaintBackground method, a derived class is not required to invoke the OnPaintBackground method of its base class.
GDI+ Basics
The System.Drawing.Graphics class provides methods for drawing various shapes such as circles, triangles, arcs, and ellipses, as well as methods for displaying text. The System.Drawing 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 Drawing and Editing Images. The essentials of GDI+ are also described in the Windows Forms QuickStart.
Geometry of the Drawing Region
The ClientRectangle property of a control specifies the rectangular region available to the control on the user's screen, while the ClipRectangle property of PaintEventArgs specifies the area that is actually painted. (Remember that painting is done in the PaintEvent method that takes a PaintEventArgs 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 Invalidate. The overloaded versions of Invalidate that take a Rectangle or Region as an argument use that argument to generate the ClipRectangle property of PaintEventArgs.
The following code fragment shows how the FlashTrackBar custom control computes the rectangular area to draw in. The client variable denotes the ClientRectangle property. For a complete sample, see Windows Forms Control Sample.
Dim invalid As New Rectangle(client.X + min, client.Y, max - min, client.Height)
Invalidate(invalid)
[C#]
Rectangle invalid = new Rectangle(client.X + min, client.Y, max - min, client.Height);
Invalidate(invalid);
Freeing Graphics Resources
Graphics objects are expensive because they use system resources. Such objects include instances of the System.Drawing.Graphics class as well as instances of System.Drawing.Brush, System.Drawing.Pen, 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 IDisposable interface, call its Dispose 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 Brush resource. For the complete source code, see Windows Forms Control Sample.
Private baseBackground As Brush = Nothing
Protected Overrides Sub OnPaint(e As PaintEventArgs)
MyBase.OnPaint(e)
If baseBackground Is Nothing Then
...
baseBackground = New SolidBrush(BackColor)
End If
...
End Sub
Protected Overrides Sub OnResize(e As EventArgs)
MyBase.OnResize(e)
If Not (baseBackground Is Nothing) Then
baseBackground.Dispose()
baseBackground = Nothing
End If
End Sub
[C#]
private Brush baseBackground = null;
protected override void OnPaint(PaintEventArgs e) {
base.OnPaint(e);
if (baseBackground == null) {
...
baseBackground = new SolidBrush(BackColor);
}
...
}
protected override void OnResize(EventArgs e) {
base.OnResize(e);
if (baseBackground != null) {
baseBackground.Dispose();
baseBackground = null;
}
}