Line Caps and Line Styles

In previous chapters we saw how to draw lines and curves using Draw-Line, DrawCurve, and related methods of the Graphics class. In these cases we drew only solid lines and curves. Lines and curves can also have styles. For example, you can draw a dotted line with circular caps.

A line has three parts: the line body, starting cap, and ending cap. The line starts with a starting cap and ends with an ending cap. The part that connects these two caps is the line body. The caps and body of a line can have different styles. Figure 9.1 shows two lines with different starting and ending cap and body styles.

Figure 9.1. Lines with different starting cap, ending cap, and dash styles

The ends of a line can have different caps. Table 9.2 shows some of the available line cap styles.

A line body can have its own style, called the dash style. Figure 9.2 shows four different dash styles.

Figure 9.2. Line dash style

Each line dash style can also have its own cap style, which is called a line dash cap. Figure 9.3 shows three different line dash caps.

Figure 9.3. Line dash caps

9.1.1 Line Caps and Styles Specified by the Pen Class

The Pen object specifies the line caps and line styles being used to draw lines. To create a line with caps and styles, we create a Pen object, set its line cap and line style properties (or methods) and use the Pen object to draw the lines.

Table 9.3 lists the members of the Pen class that can be used to set line caps and line styles.

9.1.2 Adding Line Caps and Styles

There is no direct way to apply line caps and line styles to a line. We must go through the Pen object. As we covered in previous chapters, to draw a line we must have a Pen object specifying the color and width of the pen used when we call the DrawLine method of the Graphics class. The Pen object also provides members for attaching line caps and line styles to a pen. After we attach line caps and styles to a pen, we use this pen to draw lines.

In Listing 9.1 we create a Pen object with a specified color and width. Then we set the line caps using the StartCap and EndCap properties of the Pen class, followed by the DashStyle and DashOffset properties. After that we call DrawLine and dispose of the objects.

Listing 9.1 Setting line caps and line styles

Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create a pen Pen blackPen = new Pen(Color.Black, 10); // Set the line caps and line styles blackPen.StartCap = LineCap.Triangle; blackPen.EndCap = LineCap.Triangle; blackPen.DashStyle = DashStyle.Dash; blackPen.DashOffset = 40; g.DrawLine(blackPen, 20, 10, 200, 10); // Dispose of objects blackPen.Dispose(); g.Dispose();

We will cover line caps and styles in more detail in Sections 9.1.3 through 9.1.5.

9.1.3 Getting and Setting Line Caps and Styles

In the previous sections we discussed the LineCap, DashStyle, and DashCap enumerations, which represent the line cap, line dash style, and dash cap, respectively. Now we will write an application and use these enumerations.

We create a Windows application and a MainMenu control with three menu items on the form. We call these menu items GetCapStyle, LineDashStyle, and LineDashCap, respectively, and write menu click event handlers by double-clicking on them. On the GetCapStyle menu item click event handler, we will read different line caps and generate output using these line caps; on the LineDashStyle menu item click event handler, we will generate lines with different dash styles; and on the LineDashCap menu item click event handler, we will generate output with different line dash caps.

The GetCapStyle menu item click event handler is shown in Listing 9.2. We create a pen and set the starting and ending caps using the StartCap and EndCap properties of the Pen object, and then we draw a line.

Listing 9.2 Getting line caps

private void GetCapStyles_Click(object sender, System.EventArgs e) { Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create a pen Pen blackPen = new Pen(Color.Black, 10); // Set line styles blackPen.StartCap = LineCap.Triangle; blackPen.EndCap = LineCap.Triangle; g.DrawLine(blackPen, 20, 10, 200, 10); blackPen.StartCap = LineCap.Square; blackPen.EndCap = LineCap.AnchorMask; g.DrawLine(blackPen, 20, 30, 200, 30); blackPen.StartCap = LineCap.ArrowAnchor; blackPen.EndCap = LineCap.ArrowAnchor; g.DrawLine(blackPen, 20, 50, 200, 50); blackPen.StartCap = LineCap.DiamondAnchor; blackPen.EndCap = LineCap.DiamondAnchor; g.DrawLine(blackPen, 20, 70, 200, 70); blackPen.StartCap = LineCap.Flat; blackPen.EndCap = LineCap.Flat; g.DrawLine(blackPen, 20, 90, 200, 90); blackPen.StartCap = LineCap.Round; blackPen.EndCap = LineCap.Round; g.DrawLine(blackPen, 20, 110, 200, 110); blackPen.StartCap = LineCap.RoundAnchor; blackPen.EndCap = LineCap.RoundAnchor; g.DrawLine(blackPen, 20, 130, 200, 130); blackPen.StartCap = LineCap.Square; blackPen.EndCap = LineCap.Square; g.DrawLine(blackPen, 20, 150, 200, 150); blackPen.StartCap = LineCap.SquareAnchor; blackPen.EndCap = LineCap.SquareAnchor; g.DrawLine(blackPen, 20, 170, 200, 170); blackPen.StartCap = LineCap.Flat; blackPen.EndCap = LineCap.Flat; g.DrawLine(blackPen, 20, 190, 200, 190); // Dispose of objects blackPen.Dispose(); g.Dispose(); }

The output of Listing 9.2 looks like Figure 9.4, in which the lines have different caps.

Figure 9.4. Reading line caps

The LineDashStyle menu item click event handler code is given in Listing 9.3. We create a pen and set the dash style and dash offset values using the DashStyle and DashOffset properties of the Pen object, and then we draw lines.

Listing 9.3 Getting line dash styles

private void LineDashStyle_Click(object sender, System.EventArgs e) { Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create a pen Pen blackPen = new Pen(Color.Black, 6); // Set line styles blackPen.DashStyle = DashStyle.Dash; blackPen.DashOffset = 40; blackPen.DashCap = DashCap.Triangle; g.DrawLine(blackPen, 20, 10, 500, 10); blackPen.DashStyle = DashStyle.DashDot; g.DrawLine(blackPen, 20, 30, 500, 30); blackPen.DashStyle = DashStyle.DashDotDot; g.DrawLine(blackPen, 20, 50, 500, 50); blackPen.DashStyle = DashStyle.Dot; g.DrawLine(blackPen, 20, 70, 500, 70); blackPen.DashStyle = DashStyle.Solid; g.DrawLine(blackPen, 20, 70, 500, 70); // Dispose of objects blackPen.Dispose(); g.Dispose(); }

Figure 9.5 shows the output from Listing 9.3. The lines have different dash styles.

Figure 9.5. Reading line dash styles

The GetCapStyle menu item click event handler code is given in Listing 9.4. We create a pen and set the dash cap styles using the DashCap property of the Pen object.

Listing 9.4 Getting dash caps

private void LineDashCap_Click(object sender, System.EventArgs e) { Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create a pen Pen blackPen = new Pen(Color.Black, 10); // Set DashCap styles blackPen.DashStyle = DashStyle.DashDotDot; blackPen.DashPattern = new float[]{10}; blackPen.DashCap = DashCap.Triangle; g.DrawLine(blackPen, 20, 10, 500, 10); blackPen.DashCap = DashCap.Flat; g.DrawLine(blackPen, 20, 30, 500, 30); blackPen.DashCap = DashCap.Round; g.DrawLine(blackPen, 20, 50, 500, 50); // Dispose of objects blackPen.Dispose(); g.Dispose(); }

Figure 9.6 shows the output from Listing 9.4. The lines have different dash caps: triangular, flat, and round, respectively.

Figure 9.6. Getting line dash caps

9.1.4 Drawing Other Objects with Line Caps and Styles

So far we have applied line caps and line styles only to lines, but these effects can also be applied to other objects, including curves, rectangles, and ellipses. However, some of these objects impose limitations. For example, rectangles, ellipses, and closed curves do not have starting and ending caps, so the StartCap and EndCap properties of a pen will not affect them.

Let's add one more menu item to MainMenu, called OtherObjects. The code for its menu item click event handler is given in Listing 9.5. We create three pens with different colors and widths; set their line cap, dash style, and dash cap properties; and draw a rectangle, an ellipse, and a curve.

Listing 9.5 Drawing other objects using line caps, dash styles, and dash caps

private void OtherObjects_Click(object sender, System.EventArgs e) { Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); g.SmoothingMode = SmoothingMode.AntiAlias; // Create pen objects Pen blackPen = new Pen(Color.Black, 5); Pen bluePen = new Pen(Color.Blue, 8); Pen redPen = new Pen(Color.Red, 4); // Set DashCap styles blackPen.StartCap = LineCap.DiamondAnchor; blackPen.EndCap = LineCap.SquareAnchor; blackPen.DashStyle = DashStyle.DashDotDot; blackPen.DashPattern = new float[]{10}; blackPen.DashCap = DashCap.Triangle; // Set blue pen dash style and dash cap bluePen.DashStyle = DashStyle.DashDotDot; bluePen.DashCap = DashCap.Round; // Set red pen line cap and line dash styles redPen.StartCap = LineCap.Round; redPen.EndCap = LineCap.DiamondAnchor; redPen.DashCap = DashCap.Triangle; redPen.DashStyle = DashStyle.DashDot; redPen.DashOffset = 3.4f; // Draw a rectangle g.DrawRectangle(blackPen, 20, 20, 200, 100); // Draw an ellipse g.DrawEllipse(bluePen, 20, 150, 200, 100); // Draw a curve PointF pt1 = new PointF( 90.0F, 40.0F); PointF pt2 = new PointF(130.0F, 80.0F); PointF pt3 = new PointF(200.0F, 100.0F); PointF pt4 = new PointF(220.0F, 120.0F); PointF pt5 = new PointF(250.0F, 250.0F); PointF[] ptsArray = { pt1, pt2, pt3, pt4, pt5 }; g.DrawCurve(redPen, ptsArray); // Dispose of objects blackPen.Dispose(); g.Dispose(); }

Figure 9.7 shows the output from Listing 9.5. Each graphics objectrectangle, ellipse, and curvehas a different style.

Figure 9.7. A rectangle, an ellipse, and a curve with different line styles

9.1.5 Customizing Line Caps

Sometimes we need to use custom caps. Figure 9.8 shows a line with customized caps of different sizes.

Figure 9.8. A line with custom caps

The CustomLineCap and AdjustableArrowCap classes provide functionality to draw custom line caps. CustomLineCap allows us to define custom caps, which can be attached to a penthen an application can use the pen to draw graphics objects.

The CustomLineCap class constructor takes two parameters of type GraphicsPath. The first parameter defines the fill path, which identifies the fill for the custom cap. The second parameter defines the stroke path, which defines the outline of the custom cap. The fill path and stroke path parameters cannot be used at the same time.

To create a CustomLineCap object, first we create a GraphicsPath object and add items to the path such as a line, ellipse, or rectangle using any of the add methods. Then we pass the GraphicsPath object as an argument to CustomLineCap. The following code snippet shows how to create a CustomLineCap object:

GraphicsPath path1 = new GraphicsPath(); // Add items to GraphicsPath CustomLineCap cap1 = new CustomLineCap(null, path1);

Once we have a CustomLineCap object, we can set the CustomStartCap and CustomEndCap properties of the pen to apply custom line caps. We will see a full working example of custom line caps in a moment.

Table 9.4 describes the properties of the CustomLineCap class.

9.1.5.1 Line Joins

A line join defines how lines and curves are joined in a graphics path. The LineJoin enumeration represents a line join. Its members are described in Table 9.5.

We can set the line join of a pen using its LineJoin property. To see the line joins, we create a Windows application and add a group box, four radio buttons, and a button to the form. The final form looks like Figure 9.9.

Figure 9.9. The line join test application

When we select different line join types and hit the Apply LineJoin button, the application draws lines with different joins.

The code for the Apply LineJoin button click event handler and DrawJoinedLines method is given in Listing 9.6. As the listing shows, the Apply LineJoin button click event handler calls the DrawJoinedLines method with a LineJoin value determined by the current selection.

Listing 9.6 The Apply LineJoin button click event handler

private void ApplyJoin_Click(object sender, System.EventArgs e) { // Create a Graphics object Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Line join type if(BevelRadBtn.Checked) { DrawJoinedLines(g, LineJoin.Bevel); } if(MiterRadBtn.Checked) { DrawJoinedLines(g, LineJoin.Miter); } if(MiterClippedRadBtn.Checked) { DrawJoinedLines(g, LineJoin.MiterClipped); } if(RoundRadBtn.Checked) { DrawJoinedLines(g, LineJoin.Round); } // Dispose of object g.Dispose(); } private void DrawJoinedLines(Graphics g, LineJoin joinType) { // Set smoothing mode g.SmoothingMode = SmoothingMode.AntiAlias; // Create a pen with width 20 Pen redPen = new Pen(Color.Red, 20); // Set line join redPen.LineJoin = joinType; // Create an array of points Point[] pts = { new Point(150, 20), new Point(50, 20), new Point(80, 60), new Point(50, 150), new Point(150, 150) }; // Create a rectangle using lines Point[] pts1 = { new Point(200, 20), new Point(300, 20), new Point(300, 120), new Point(200, 120), new Point(200, 20) }; // Draw lines g.DrawLines(redPen, pts); g.DrawLines(redPen, pts1); // Dispose of object redPen.Dispose(); }

Now if we run the code, the Bevel line join output looks like Figure 9.10.

Figure 9.10. The Bevel line join effect

The Miter line join output looks like Figure 9.11.

Figure 9.11. The Miter line join effect

The Round line join output looks like Figure 9.12.

Figure 9.12. The Round line join effect

9.1.5.2 Stroke Caps

We have already seen how to use the StartCap and EndCap properties of a Pen object to set the starting and ending caps of lines. We have also seen how to use the StartCustomCap and EndCustomCap properties to set customized starting and ending caps.

To understand caps better, take a look at Figure 9.13. The rectangle A is a line cap. The starting cap is triangular, and the ending cap is round.

Figure 9.13. Customized starting and ending caps

The GetStrokeCaps and SetStrokeCaps methods of the CustomLineCap class can also be used to get and set the starting and ending caps of a custom cap. The SetStrokeCaps method takes two arguments of type LineCap enumeration and sets the caps for the starting and ending points of lines. Listing 9.7 creates custom line caps and sets them using the SetStrokeCaps method. After creating custom line caps, we create a pen and set its CustomStartCap and CustomEndCap properties, which use the pen to draw a line.

Listing 9.7 Using SetStrokeCaps

private void SetStrokeCapsMenu_Click(object sender, System.EventArgs e) { // Create a Graphics object Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create a path for custom line cap. This // path will have two lines from points // (-3, -3) to (0, 0) and (0, 0) to (3, -3). Point[] points = { new Point(-3, -3), new Point(0, 0), new Point(3, -3) }; GraphicsPath path = new GraphicsPath(); path.AddLines(points); // Create a custom line cap from the path CustomLineCap cap = new CustomLineCap(null, path); // Set the starting and ending caps of the custom cap cap.SetStrokeCaps(LineCap.Round, LineCap.Triangle); // Create a Pen object and set its starting and ending // caps Pen redPen = new Pen(Color.Red, 15); redPen.CustomStartCap = cap; redPen.CustomEndCap = cap; redPen.DashStyle = DashStyle.DashDotDot; // Draw the line g.DrawLine(redPen, new Point(100, 100), new Point(400, 100)); // Dispose of object g.Dispose(); }

Figure 9.14 shows the output from Listing 9.7.

Figure 9.14. Setting customized starting and ending caps

9.1.5.3 Adjustable Arrow Caps

Adjustable arrow caps allow you to set the size of the cap's base cap, height, width, and joins. The AdjustableArrowCap class, which is inherited from the CustomLineCap class, represents an adjustable arrow-shaped line cap.

The AdjustableArrowCap class constructor takes three parameters: the width of the arrow as a floating value, the height of the arrow as a floating value, and a Boolean value (optional) that, if true, indicates that the arrow cap is filled.

The following code snippet creates an AdjustableArrowCap object:

float w = 2; float h = 5; bool fill = false; AdjustableArrowCap myArrow = new AdjustableArrowCap(w, h, fill);

Besides having CustomLineCap methods and properties, AdjustableArrowCap provides four properties: Filled, Height, Width, and MiddleInset. The Height and Width properties represent the height and the width, respectively, of an arrow cap. The Filled property indicates whether an arrow cap is filled. The MiddleInset property represents the distance between the outline of the arrow cap and the fill.

Now let's add an AdjustableArrowCap option to our application. We add one menu item to the form, along with a menu item click event handler, as shown in Listing 9.8. We create two AdjustableArrowCap objects and set their BaseCap, BaseInset, StrokeJoin, and WidthScale properties. Then we create a black Pen object with a width of 15 and set the CustomStartCap and CustomEndCap properties of the pen as AdjustableArrowCap objects. Finally, we use this pen to draw a line with DrawLine.

Listing 9.8 Using adjustable arrow caps

private void AdjustableRowCapMenu_Click(object sender, System.EventArgs e) { // Create a Graphics object Graphics g = this.CreateGraphics(); g.Clear(this.BackColor); // Create two AdjustableArrowCap objects AdjustableArrowCap cap1 = new AdjustableArrowCap(1, 1, false); AdjustableArrowCap cap2 = new AdjustableArrowCap(2, 1); // Set cap properties cap1.BaseCap = LineCap.Round; cap1.BaseInset = 5; cap1.StrokeJoin = LineJoin.Bevel; cap2.WidthScale = 3; cap2.BaseCap = LineCap.Square; cap2.Height = 1; // Create a pen Pen blackPen = new Pen(Color.Black, 15); // Set CustomStartCap and CustomEndCap properties blackPen.CustomStartCap = cap1; blackPen.CustomEndCap = cap2; // Draw line g.DrawLine(blackPen, 20, 50, 200, 50); // Dispose of objects blackPen.Dispose(); g.Dispose(); }

Figure 9.15 shows the output from Listing 9.8. The end caps have different sizes.

Figure 9.15. Adjustable arrow caps