2.2.20 LogPenEx Object

The LogPenEx object specifies the style, width, and color of an extended logical pen.

PenStyle (4 bytes): An unsigned integer that specifies the pen style. This value is defined from the PenStyle enumeration (section 2.1.25).

The pen style is a combination of pen type, line style, line cap, and line join.

Width (4 bytes): An unsigned integer that specifies the width of the line drawn by the pen.

If the pen type in the PenStyle field is PS_GEOMETRIC, this value is the width in logical units; otherwise, the width is specified in device units. If the pen type in the PenStyle field is PS_COSMETIC, this value MUST be 0x00000001.

BrushStyle (4 bytes): An unsigned integer that specifies a brush style for the pen from the BrushStyle enumeration ([MS-WMF] section 2.1.1.4).

If the pen type in the PenStyle field is PS_GEOMETRIC, this value is either BS_SOLID or BS_HATCHED. The value of this field can be BS_NULL, but only if the line style specified in PenStyle is PS_NULL. The BS_NULL style SHOULD be used to specify a brush that has no effect.

ColorRef (4 bytes): A ColorRef object ([MS-WMF] section 2.2.2.8). The interpretation of this field depends on the BrushStyle value, as shown in the table later in this section.

BrushHatch (4 bytes): The brush hatch pattern. The definition of this field depends on the BrushStyle value, as shown in the table later in this section.

NumStyleEntries (4 bytes): The number of elements in the array specified in the StyleEntry field. This value SHOULD be zero if PenStyle does not specify PS_USERSTYLE.

StyleEntry (variable, optional): An array of 32-bit unsigned integers that defines the lengths of dashes and gaps in the line drawn by this pen when the value of PenStyle is PS_USERSTYLE. The array contains the number of entries specified by NumStyleEntries, but it is used as if it repeated indefinitely.

The first entry in the StyleEntry array specifies the length of the first dash. The second entry specifies the length of the first gap. Thereafter, lengths of dashes and gaps alternate.

If the pen type in the PenStyle field is PS_GEOMETRIC, lengths are specified in logical units; otherwise, they are specified in device units.

The LogPenEx object includes the specification of brush attributes, so it can be used to draw lines that consist of custom or predefined patterns. The following table shows the relationship between the BrushStyle, ColorRef, and BrushHatch fields in this object. Only supported brush styles are listed.