Recipe 9.16. Limiting Display Updates to Specific Regions

Problem

You want to clip your graphics using some complexly shaped area, without having to resort to difficult code to compute intersections and other clipping details.

Solution

Sample code folder: Chapter 09\ClippingRegion

Create a Region object defined by a path, set the Graphics object's Clip property to this region, and draw any standard graphics on the Graphics object surface. Clipping takes place using the path.

Discussion

A single path can range from a simple sequence of lines to an elaborate mix of connected or disconnected rectangles, ellipses, or polygons. This means that a path can take on a complex outline, and it can involve a lot of independent parts. In the example presented here a large number of tall, thin rectangles are added to a single path, and this path is then used to define a Region object that clips the drawing of a string.

Several of the objects used in this example are in the Drawing2D namespace, so be sure to add the following Imports statement to the top of your source code:

 Imports System.drawing.Drawing2D 

The remaining code appears in the form's Paint event handler. The first thing the Paint handler does is access the form's graphics surface, passed as a member of the PaintEventArgs instance (e). The area is cleared to solid white:

 Private Sub Form11_Paint(ByVal sender As Object, _       ByVal e As System.Windows.Forms.PaintEventArgs) _       Handles Me.Paint    ' ----- Draw using a region to restrict output.    Dim canvas As Graphics    Dim fencePath As GraphicsPath    Dim onePicket As Rectangle    Dim counter As Integer    Dim slottedRegion As Region    ' ----- Clear the background.    canvas = e.Graphics    canvas.Clear(Color.White) 

Next, a GraphicsPath object is created and filled with a lot of tall, thin rectangles, spaced apart somewhat like the pickets on a picket fence. These rectangles don't touch each other, but they are all added to a single complex path object:

    ' ----- Create a picket fence path.    fencePath = New GraphicsPath    For counter = 0 To 200       onePicket = New Rectangle(counter * 10, 0, 6, 500)       fencePath.AddRectangle(onePicket)    Next counter 

The path just created is then used to define a new Region object:

    ' ----- Create a region from the path.    slottedRegion = New Region(fencePath) 

The path itself can't be used to define a clipping region, but a Region object can. Even regions defined by complexly shaped paths provide rapid clipping on the graphics surface. To this end, we'll now assign the slottedRegion to the Graphics object's Clip property:

    ' ----- Set clipping using the region.    canvas.Clip = slottedRegion 

You can apply any graphics drawing methods you want at this point, and everything drawn will be clipped as defined by the Graphics object's Clip property. In this example we clear the entire surface to a new color (given a white-cyan-white-cyan picket fence image), and then draw a string of text using a large font:

    ' ----- Draw some slotted   text.    canvas.Clear(Color.Aqua)    canvas.  DrawString("Picket Fence", _       New Font("Times New Roman", 77), _       Brushes.Blue, 20, 20) End Sub 

Figure 9-24 shows how both graphics methods are clipped.

Figure 9-24. Regions can be used to clip graphics in very intricate ways