This class describes the kind of line that is drawn when using the
Graphics.DrawXXX() members.
Pens are resource-based entities, and it is
therefore important to manage their lifetime carefully, calling
Dispose() when you are finished with them, to
release the resource to the system.
You can construct a Pen from a
Color, Brush, or (optionally) a
Width. If you use a Color, the
line will be a solid, uniform color. If you use a
Brush, you can take advantage of specific
properties to render the line with a gradient or image texture. If
you do not specify a width, the default value of 1 is used.
The width of the Pen is measured in pixels and is
modified by any transforms that apply during the rendering process.
As a geometric line has no intrinsic width, you can also specify an
Alignment property, which determines where the
pixels are rendered relative to the geometric line (see
System.Drawing.Drawing2D.PenAlignment for more
information on this). The default is to center the pixels across this
theoretical line.
You can choose how to render the beginning and end of the line by
specifying the StartCap and
EndCap properties. You can choose one of several
different styles from the
System.Drawing.Drawing2D.LineCap enumeration,
including butt-ends, round-ends, and simple arrows. If the predefined
styles are not suitable, you can specify a
CustomStartCap or CustomEndCap
with an instance of the
System.Drawing.Drawing2D.CustomLineCap class. This
allows you to render more complex arrows or markers. The endcap size
is scaled by the line width, in addition to any transforms that may
be applicable.
The Pen does not necessarily have to consist of a
single, continuous stroke. You can specify one of a number of
predefined dash styles, found in the
System.Drawing.Drawing2D.DashStyle enumeration, or
define a custom DashPattern by specifying an array
of real numbers that represent the lengths of each dash segment. Note
that these values are multiplied by the line width and scaled by any
applicable transforms before they are used. If you wish, you can
provide a DashOffset value, which determines how
far along the line the dash pattern begins. You can also specify the
style of the endcaps on the dash line segments using the
DashCap property. This is similar to the
LineCap properties for the line itself, but the
System.Drawing.Drawing2D.DashCap enumeration
offers a smaller set of cap styles.
In addition to the DashStyle, which determines a
dash pattern along the length of the line, you can specify a
CompoundArray, which specifies a pattern of
parallel lines. Alternate elements in the array specify a gap-width,
then a line-width, as a proportion of the whole line width. That is,
a value of 0.2 in the array represents a line or gap that is 20% of
the total width. Note that you are precluded from using a compound
line if the Alignment property is set to
PenAlignment.Inset.
Finally, if the pen is being used to render multiple line segments,
you can specify the LineJoin style with one of the
elements in the System.Drawing.Drawing2D.LineJoin
enumeration. If you pick a mitered style, the
MiterLimit property determines the point at which
the join is clipped.
public sealed class Pen : MarshalByRefObject :
System.Drawing.Internal.ISystemColorTracker, ICloneable, IDisposable {
// Public Constructors
public Pen(Brush brush);
public Pen(Brush brush, float width);
public Pen(Color color);
public Pen(Color color, float width);
// Public Instance Properties
public PenAlignment Alignment{set; get; }
public Brush Brush{set; get; }
public Color Color{set; get; }
public float[ ] CompoundArray{set; get; }
public CustomLineCap CustomEndCap{set; get; }
public CustomLineCap CustomStartCap{set; get; }
public DashCap DashCap{set; get; }
public float DashOffset{set; get; }
public float[ ] DashPattern{set; get; }
public DashStyle DashStyle{set; get; }
public LineCap EndCap{set; get; }
public LineJoin LineJoin{set; get; }
public float MiterLimit{set; get; }
public PenType PenType{get; }
public LineCap StartCap{set; get; }
public Matrix Transform{set; get; }
public float Width{set; get; }
// Public Instance Methods
public object Clone(); // implements ICloneable
public void Dispose(); // implements IDisposable
public void MultiplyTransform(System.Drawing.Drawing2D.Matrix matrix);
public void MultiplyTransform(System.Drawing.Drawing2D.Matrix matrix,
System.Drawing.Drawing2D.MatrixOrder order);
public void ResetTransform();
public void RotateTransform(float angle);
public void RotateTransform(float angle, System.Drawing.Drawing2D.MatrixOrder order);
public void ScaleTransform(float sx, float sy);
public void ScaleTransform(float sx, float sy, System.Drawing.Drawing2D.MatrixOrder order);
public void SetLineCap(System.Drawing.Drawing2D.LineCap startCap, System.Drawing.Drawing2D.LineCap endCap,
System.Drawing.Drawing2D.DashCap dashCap);
public void TranslateTransform(float dx, float dy);
public void TranslateTransform(float dx, float dy, System.Drawing.Drawing2D.MatrixOrder order);
// Protected Instance Methods
protected override void Finalize(); // overrides object
}
System.MarshalByRefObject