2.2.2.34 EmfPlusPenOptionalData Object

The EmfPlusPenOptionalData object specifies optional data for a graphics pen.

Note: Each field of this object is optional and might not be present in the OptionalData field of an EmfPlusPenData object (section 2.2.2.33), depending on the PenData flags (section 2.1.2.7) set in its PenDataFlags field. Although it is not practical to represent every possible combination of fields present or absent, this section specifies their relative order in the object. The implementer is responsible for determining which fields are actually present in a given metafile record, and for unmarshaling the data for individual fields separately and appropriately.

TransformMatrix (24 bytes): An optional EmfPlusTransformMatrix object (section 2.2.2.47) that specifies a world space to device space transform for the pen. This field MUST be present if the PenDataTransform flag is set in the PenDataFlags field of the EmfPlusPenData object.

StartCap (4 bytes): An optional signed integer that specifies the shape for the start of a line in the CustomStartCapData field. This field MUST be present if the PenDataStartCap flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the LineCapType enumeration (section 2.1.1.17).

EndCap (4 bytes): An optional signed integer that specifies the shape for the end of a line in the CustomEndCapData field. This field MUST be present if the PenDataEndCap flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the LineCapType enumeration.

Join (4 bytes): An optional signed integer that specifies how to join two lines that are drawn by the same pen and whose ends meet. This field MUST be present if the PenDataJoin flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the LineJoinType enumeration (section 2.1.1.18).

MiterLimit (4 bytes): An optional floating-point value that specifies the miter limit, which is the maximum allowed ratio of miter length to line width. The miter length is the distance from the intersection of the line walls on the inside the join to the intersection of the line walls outside the join. The miter length can be large when the angle between two lines is small. This field MUST be present if the PenDataMiterLimit flag is set in the PenDataFlags field of the EmfPlusPenData object.

LineStyle (4 bytes): An optional signed integer that specifies the style used for lines drawn with this pen object. This field MUST be present if the PenDataLineStyle flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the LineStyle enumeration (section 2.1.1.19).

DashedLineCapType (4 bytes): An optional signed integer that specifies the shape for both ends of each dash in a dashed line. This field MUST be present if the PenDataDashedLineCap flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the DashedLineCapType enumeration (section 2.1.1.10).

DashOffset (4 bytes): An optional floating-point value that specifies the distance from the start of a line to the start of the first space in a dashed line pattern. This field MUST be present if the PenDataDashedLineOffset flag is set in the PenDataFlags field of the EmfPlusPenData object.

DashedLineData (variable): An optional EmfPlusDashedLineData object (section 2.2.2.16) that specifies the lengths of dashes and spaces in a custom dashed line. This field MUST be present if the PenDataDashedLine flag is set in the PenDataFlags field of the EmfPlusPenData object.

PenAlignment (4 bytes): An optional signed integer that specifies the distribution of the pen width with respect to the coordinates of the line being drawn. This field MUST be present if the PenDataNonCenter flag is set in the PenDataFlags field of the EmfPlusPenData object, and the value is defined in the PenAlignment enumeration (section 2.1.1.23).

For example, consider the placement of a line. If the starting and ending coordinates of the line are defined, it is possible to think of a theoretical line between the two points that is zero width. Center alignment means that the pen width is distributed as evenly as possible on either side of that theoretical line.

CompoundLineData (variable): An optional EmfPlusCompoundLineData object (section 2.2.2.9) that specifies an array of 32-bit floating-point values that define the compound line of a pen, which is made up of parallel lines and spaces. This field MUST be present if the PenDataCompoundLine flag is set in the PenDataFlags field of the EmfPlusPenData object.

CustomStartCapData (variable): An optional EmfPlusCustomStartCapData object (section 2.2.2.15) that defines the custom start-cap shape, which is the shape to use at the start of a line drawn with this pen. It can be any of various shapes, such as a square, circle, or diamond. This field MUST be present if the PenDataCustomStartCap flag is set in the PenDataFlags field of the EmfPlusPenData object.

CustomEndCapData (variable): An optional EmfPlusCustomEndCapData object (section 2.2.2.11) that defines the custom end-cap shape, which is the shape to use at the end of a line drawn with this pen. It can be any of various shapes, such as a square, circle, or diamond. This field MUST be present if the PenDataCustomEndCap flag is set in the PenDataFlags field of the EmfPlusPenData object.

Graphics pens are specified by EmfPlusPen objects (section 2.2.1.7).

See section 2.2.2 for the specification of additional structure objects.